Reference
Building & contributing
Go 1.23+, no cgo. Architecture notes live in LLM.md.
#Build from source
git clone https://github.com/lubabs770/gooseneck
cd gooseneck/player
go build -o gooseneck-player .
go vet ./... && go test ./...CI tests and cross-compiles linux/macOS/windows × amd64/arm64 on every change, and publishes a release for v* tags.
#Find your way around
Architecture notes for contributors (and AI agents) are in LLM.md. The short version:
| Package | Role |
|---|---|
internal/library | The service layer: catalog, cache, YouTube Music, player, history. Put logic here. |
internal/cli | Cobra commands |
internal/tui | The Bubble Tea app |
internal/ytm | Read-only YouTube Music client |
internal/mpv | The headless mpv daemon over JSON IPC |
internal/store | SQLite cache and history |
internal/catalog | artists.json, tags, fuzzy search, multi-catalog merge |
#Test without touching your setup
GOOSENECK_HOME=$(mktemp -d) go run . play "8th Day" lucky#The demo GIFs
Recorded with VHS against an isolated, pre-warmed demo home:
demo/setup.sh && vhs demo/tui.tape && vhs demo/cli.tape#This website
It lives in site/: plain HTML fragments and a dependency-free Python script. Theme colours are read from the TUI's source, so they never drift.
python3 site/build.py # writes site/dist/
python3 -m http.server -d site/dist#Roadmap
- Windows playback control via mpv's named-pipe IPC.
- Lyrics in the sidebar where YouTube Music has them.