How it works

A catalog, YouTube Music's web API, a SQLite cache, and mpv running in the background.

#The pieces

• Catalog. artists.json is refreshed daily by a GitHub Action and downloaded on first run.
• Music data. Artist and album pages come from YouTube Music's web API, one request each (about half a second), cached in SQLite: artist pages for 72 hours, albums for 30 days. Stale copies are served when you're offline. Channels without a YouTube Music page fall back to a yt-dlp uploads listing.
• Playback. The first play starts mpv --idle with an IPC socket in $XDG_RUNTIME_DIR/gooseneck/. The TUI and every goose command talk to that socket, which is why any terminal can control the music. mpv streams audio through its yt-dlp hook.
• Daemon. A single background process handles scrobbling and radio top-ups, and exits when there's nothing left to do.
• History. Every play is recorded (goose history, goose top), and the home screen shows recently played artists.

#One brain, two faces

The TUI and the CLI are thin layers over the same library code. The rule in the codebase: every TUI action must be reachable from the CLI. If you can click it, you can script it.

#Media keys

Install mpv-mpris and the background player appears in desktop media controls and playerctl automatically. goose doctor tells you whether it's there.

#Hebrew

Most terminals don't do right-to-left text. gooseneck reorders Hebrew text itself, so titles and artist names read correctly.