Getting started

Install

One line to install gooseneck, plus the two programs it plays music with.

#The one-liner

curl -fsSL https://raw.githubusercontent.com/lubabs770/gooseneck/main/install.sh | sh

This downloads the latest release for your OS and CPU and installs gooseneck-player plus the short alias goose into ~/.local/bin. Make sure that directory is on your PATH.

Variable	Does
`BIN_DIR=`	Install somewhere else, e.g. `BIN_DIR=/usr/local/bin`
`VERSION=`	Pin a release, e.g. `VERSION=v0.4.0`

curl -fsSL https://raw.githubusercontent.com/lubabs770/gooseneck/main/install.sh | BIN_DIR=/usr/local/bin sh

Windows: grab the .exe from the releases page. Playback works, but it's fire-and-forget for now (no pause/skip from other terminals yet).

#Requirements

mpv plays the audio.
yt-dlp fetches streams and downloads. Keep it fresh, since YouTube changes often.
Optional: ffmpeg tags downloaded files, and mpv-mpris puts gooseneck in your desktop's media controls.

# Arch / Omarchy
sudo pacman -S mpv yt-dlp ffmpeg mpv-mpris
# macOS
brew install mpv yt-dlp ffmpeg
# Debian / Ubuntu
sudo apt install mpv ffmpeg && pipx install yt-dlp

#Check everything with doctor

$ goose doctor
✓  config        ~/.config/gooseneck/config.toml
✓  catalog       1655 artists, updated 3h ago
✓  yt-dlp        2026.08.19
✓  player        mpv v0.41.0
✓  control       player idle (starts on first play)
✓  youtube music reachable (458ms)
✓  scrobbling    to local
✓  media keys    mpv-mpris found (desktop media controls work)
✓  images        half-block art (any truecolor terminal)

#Shell completion

Artist and album names complete too, so goose play 8th<tab> just works.

goose completion zsh > "${fpath[1]}/_goose"
goose completion bash > ~/.local/share/bash-completion/completions/goose
goose completion fish > ~/.config/fish/completions/goose.fish

#Updating & uninstalling

Re-run the installer to update. To remove gooseneck, delete the two binaries and, if you like, its data:

goose quit-player
rm ~/.local/bin/goose ~/.local/bin/gooseneck-player
rm -r ~/.config/gooseneck      # config, cache, history, scrobbles

Downloads live in ~/Music/gooseneck and are not removed by the above.

Edit these docs on GitHub