bjarneo/cliamp: a Winamp-style terminal music player that also speaks to your servers

The problem cliamp picks a fight with

Most music players assume one source. A local library player ignores your Navidrome server; a web player ignores the FLAC directory on disk; a podcast app ignores both. cliamp's answer is to put a single terminal interface in front of local files, direct stream URLs, about 58,000 Radio Browser stations, Apple's podcast directory, YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp, Bilibili, NetEase Cloud Music, Yandex Music, Xiaoyuzhou, Spotify, and the self-hosted servers Navidrome, Lyrion, Plex, Jellyfin and Audiobookshelf.

That is a lot of surface for one binary, and it defines the audience. cliamp is for people who already work in a terminal, run a music server at home, and would rather type a path than click through a library view. The README frames the whole thing as a retro player inspired by Winamp, and the spectrum visualizer, parametric EQ and playlist manager are there to back that up. If you do not have a terminal open most of the day, the pitch loses most of its force.

How playback, providers and the daemon fit together

The repository layout shows the split clearly: provider/, resolve/, player/, playlist/, radio/, ui/, pluginmgr/, plugins/, luaplugin/, daemon.go and daemon_v2.go sit at the top level next to main.go. Providers are the adapters for each remote service; resolve/ turns whatever you typed into something playable; player/ handles decoding; ui/ is the Bubbletea and Lip Gloss interface.

Audio decoding is not one library. go.mod lists gopxl/beep/v2, jfreymuth/oggvorbis, dhowden/tag for metadata, devgianlu/go-librespot for Spotify, and kkdai/youtube for YouTube. ffmpeg is an optional runtime dependency for AAC, ALAC, Opus and WMA; yt-dlp is the optional runtime dependency for YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp, Bilibili and NetEase Cloud Music. That means the binary covers common formats on its own, and hands the awkward ones to external tools you install separately.

The daemon files and the ipc/ directory suggest a long-running process that the UI talks to over IPC, which is the usual way to keep playback alive while the interface redraws. The README does not document the IPC protocol or the daemon lifecycle, so treat that as an internal detail rather than something you can script against. Plugins are a separate axis: gopher-lua is a direct dependency, and the luaplugin/, pluginmgr/ and plugins/ directories indicate Lua-based extension. The README does not publish a plugin API reference, so the plugin system is real but undocumented at the level a third-party author would need.

Installing cliamp and playing something in the first five minutes

The README leads with a shell installer, and there are package-manager routes for Homebrew, Arch and Nix. The Homebrew formula is the one the README says installs all required runtime libraries, which matters on macOS because pre-built binaries link dynamically against Homebrew codec libraries.

curl -fsSL https://cliamp.stream/install.sh | sh

If you prefer Homebrew, the tap route pulls in the codec libraries for you:

brew install bjarneo/cliamp/cliamp

Arch users install from the AUR, and Nix users can run it straight from the flake:

yay -S cliamp
nix run github:bjarneo/cliamp

Once it is on PATH, the README's quick start is three commands. Give it a directory, a glob of files, or a URL:

cliamp ~/Music
cliamp *.mp3 *.flac
cliamp https://example.com/stream

Press Ctrl+K inside the player to see every keybinding. If you want the remote providers rather than local files, run the interactive wizard, which writes the relevant block into ~/.config/cliamp/config.toml (or %APPDATA%\cliamp\config.toml on Windows when HOME is unset) and validates supported server connections as you go:

cliamp setup

For podcasts, the README gives a provider flag instead of the wizard. It browses Apple's top 100 shows across 19 categories, with no account or API key required:

cliamp --provider podcast

Radio is not a flag. Press R in the player to browse the Radio Browser directory, N to browse by country, and f to pin countries you listen to.

Where cliamp gets awkward

The dependency story is the first real cost. On Linux you need ALSA development headers to build from source, and the README lists the exact packages for Debian, Fedora and Arch. Spotify support needs go-librespot, which needs CGO, and on Windows that means installing MSYS2 and building from the MinGW64 terminal rather than the standard MSYS2 one. A pure-Go terminal player would avoid all of this. cliamp trades that simplicity for Spotify and a wider codec set, and the trade is visible the moment you try to compile it.

macOS has its own trap. Pre-built binaries from Releases or install.sh link dynamically to FLAC, Vorbis, Ogg and mpg123 from Homebrew, so a fresh machine can fail with a Library not loaded error mentioning libvorbisenc.2.dylib until you run brew install flac libvorbis libogg mpg123. The Homebrew formula route avoids it; the download route does not.

Provider breadth is also a maintenance surface. Each of the streaming services cliamp talks to can change its behaviour, and the yt-dlp dependency for YouTube, SoundCloud, Mixcloud, Bandcamp, Bilibili and NetEase Cloud Music means those providers break when yt-dlp breaks or when it is not installed at all. If you only want to play a local FLAC library, none of this applies to you, and a smaller player is the better tool.

cliamp against a plain MPD client

The closest comparison is not another TUI player but a client for Music Player Daemon. MPD is a server you configure once, and clients like ncmpcpp or mpc connect to it over a socket. The daemon owns the library, the queue and the output; clients are thin. That model is stable, well documented, and easy to script, and it is why MPD setups survive for years.

cliamp inverts this. It is the player, and the remote services are adapters it queries directly. There is no shared protocol other than the ones each service already speaks, which is why the setup wizard has to validate each connection individually and why the config file is a collection of provider blocks rather than one server address. The upside is that you do not run a separate daemon or index your library first. The downside is that cliamp has to know about every service, and that knowledge ages.

If your library is local and you want a headless server that any client can attach to, MPD is the more durable choice. If your music is spread across a Navidrome instance, a Jellyfin server, YouTube and a podcast feed, cliamp is doing work MPD was never designed for.

Maintenance, licence and what upgrading costs

cliamp is MIT licensed, which is permissive and imposes no copyleft obligation on your own code. The practical licence question is elsewhere: the project links against go-librespot for Spotify and depends on yt-dlp at runtime, and those components carry their own terms. The README does not discuss licensing of dependencies, so check them yourself if you plan to redistribute a build.

Maintenance looks current. The last push was on 2026-09-22, and the releases list shows v2.2.0 on 2026-09-08, v2.1.0 the day before, and v2.0.1 on 2026-09-02. Three releases inside a week is a fast cadence, and it usually means the provider adapters are being patched as services change. That is good for correctness and bad for pinning: if you vendor a build, expect to rebuild when a provider stops working.

The Makefile shows what the project expects of contributors. make check runs gofmt, go vet and go test; make ci adds staticcheck, govulncheck, a race-enabled test run, coverage, and shellcheck on site/install.sh. If you are packaging cliamp for a distribution, make install drops the binary into ~/.local/bin, and make build stamps the version through ldflags from git describe. The upgrade path itself is not documented in the README beyond the install commands, so there is no stated rollback procedure if a new release regresses a provider.

What to check before you commit to it

Start with the two optional runtime dependencies, because they decide which providers work at all. Run ffmpeg -version and yt-dlp --version before you file a bug about YouTube or Opus playback. On macOS, confirm the codec libraries resolve by launching the binary once after install rather than assuming the installer handled it. On Linux, if you are building from source, install the ALSA headers for your distribution first, since the build fails without them.

Then run cliamp setup and check that each provider you care about validates. The wizard is the project's own answer to the configuration problem, and it is the fastest way to find out whether your Navidrome, Plex or Jellyfin instance is reachable from the machine you are on. If you want to add stations by hand instead, the README points at ~/.config/cliamp/radios.toml and docs/configuration.md.

Finally, decide whether you need the plugin system. The Lua directories are in the tree, but the README does not document a plugin API, so if extensibility is the reason you are evaluating cliamp, that is the gap to probe first.

Editorial conclusion

Adopt cliamp if you already live in a terminal and want one binary in front of local files, radio, podcasts and your self-hosted music servers. Skip it if you need a GUI, a stable plugin API, or a build that does not pull in CGO and system codec libraries. Verify first that ffmpeg and yt-dlp are on PATH if you plan to use YouTube, SoundCloud or Bilibili, and run cliamp setup to confirm each server connection before you rely on it.

Frequently asked questions

Official sources

1. bjarneo/cliamp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases