gem-hunter
Language: Go
cliamp - Terminal music player inspired by winamp
A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Mixcloud, Bilibili, Spotify, Qobuz, Tidal, Bandcamp purchases, NetEase Cloud Music, Yandex Music, Xiaoyuzhou (小宇宙), Navidrome, Lyrion, Plex, Jellyfin, Emby, and Audiobookshelf. Use the spectrum visualizer, parametric EQ, and playlists.
cliamp.stream | docs | android | discord
On a phone, run cliamp mobile. It is a native Android client for radio, podcasts, and the same servers this player talks to.
cliamp uses Bubbletea, Lip Gloss, Beep, and go-librespot.
cliamp-promo-github.mp4curl -fsSL https://cliamp.stream/install.sh | shHomebrew
brew install bjarneo/cliamp/cliamp
The formula installs all required runtime libraries.
Arch Linux (AUR)
yay -S cliamp
Nix
nix run github:bjarneo/cliamp
For a declarative NixOS configuration, add github:bjarneo/cliamp as a flake
input. Install its default package:
inputs.cliamp.url = "github:bjarneo/cliamp"; environment.systemPackages = [ inputs.cliamp.packages.${pkgs.stdenv.hostPlatform.system}.default ];
Go
go install github.com/bjarneo/cliamp@latest
Install ALSA development headers before you build on Linux. See Building from source.
Pre-built binaries
Download from GitHub Releases.
macOS: Pre-built binaries link dynamically to FLAC, Vorbis, Ogg, and mpg123 from Homebrew. If you download from Releases or use
install.sh, install these libraries first. Otherwise, you can see errors such asLibrary not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib:brew install flac libvorbis libogg mpg123
brew install bjarneo/cliamp/cliampinstalls these libraries.Linux: Pre-built binaries link FLAC, Vorbis, Ogg, and mpg123 statically. No extra codec packages are required. You can still need an ALSA bridge for your sound server. See Troubleshooting.
Windows: Download and extract
cliamp-windows-amd64.zipfrom Releases. It includes the codec DLLs that Spotify requires. On Windows, cliamp stores its config under%APPDATA%\cliampunlessHOMEnames another directory.
Optional runtime dependencies for all platforms and install methods:
On macOS, run brew install ffmpeg yt-dlp. On Linux, use your distribution package manager.
On Windows, install ffmpeg and yt-dlp with your package manager. Keep both on PATH.
Build from source
git clone https://github.com/bjarneo/cliamp.git && cd cliamp && go build -o cliamp .
cliamp ~/Music # play a directory cliamp *.mp3 *.flac # play files cliamp https://example.com/stream # play a URL
Press Ctrl+K to see all keybindings.
Configure remote providers such as Navidrome, Lyrion, Bandcamp, Plex, Jellyfin, Emby, Audiobookshelf, Spotify, Qobuz, Tidal, Mixcloud, YouTube Music, and NetEase Cloud Music with the interactive wizard:
cliamp setup
The wizard guides you through each provider. It writes the provider keys into the section of that provider in your config file (~/.config/cliamp/config.toml, or %APPDATA%\cliamp\config.toml on Windows unless HOME names another directory). It keeps your other keys and comments. It validates supported server connections during setup. The OAuth providers Spotify, Qobuz and Tidal sign in later in the player. Mixcloud checks optional browser-session or OAuth credentials when you use them. See docs/cli.md for details.
See the Mixcloud provider guide for discovery, account, creator/show, genre search, local genre favorites, authentication, signed-in playback, resume, seeking, and limitations.
For podcast discovery and subscriptions, run cliamp --provider podcast.
Browse Apple's top 100 shows and 19 categories, search with / then Enter,
and subscribe with f. No account or API key is needed.
See the Podcasts guide.
Control a running cliamp from a script, a status bar, or a key binding:
cliamp toggle cliamp next cliamp status --json
Media keys work through MPRIS on Linux, Now Playing on macOS, and global hotkeys on Windows.
Run cliamp --daemon to play without a TUI. Headless mode runs the same
player as the TUI. It loads your Lua plugins, reports plays to Navidrome,
Jellyfin, and the other providers that take play reports, and adds each track
to Recently Played when the track starts. See
docs/headless.md and
docs/remote-control.md.
Press R in the player to browse about 58,000 online radio stations in the Radio Browser directory.
Cut that down by location or genre: N browses by country, Browse genres &
tags opens the directory's complete tag index, and / filters either list.
f pins the countries you listen to, and Enter on a country or tag loads its
stations as a playlist. cliamp does not work out where you are unless you pick
"Use my location" and accept; it then reads your country from the system
timezone, never from a geo-IP service. See docs/radio.md.
Add your own stations to ~/.config/cliamp/radios.toml (or %APPDATA%\cliamp\radios.toml on Windows unless HOME names another directory). See docs/configuration.md.
To host a radio station, use cliamp-server.
Prerequisites:
Linux (Debian/Ubuntu):
sudo apt install libasound2-dev libflac-dev libvorbis-dev libogg-dev libmpg123-dev
Linux (Fedora):
sudo dnf install alsa-lib-devel flac-devel libvorbis-devel libogg-devel mpg123-devel
Linux (Arch):
sudo pacman -S alsa-lib flac libvorbis libogg mpg123
macOS:
brew install flac libvorbis libogg mpg123 pkg-config
Windows source builds: Every Windows source build needs CGO and the MSYS2 MinGW64 toolchain because the Spotify provider is compiled in even when it is not configured. ffmpeg.exe and yt-dlp.exe remain optional runtime dependencies for the same formats and providers as other platforms.
Install MSYS2.
Open the MSYS2 MinGW64 terminal, not the standard MSYS2 terminal. Install the toolchain and codec libraries:
pacman -S make \ mingw-w64-x86_64-gcc mingw-w64-x86_64-go mingw-w64-x86_64-pkg-config \ mingw-w64-x86_64-libogg mingw-w64-x86_64-libvorbis \ mingw-w64-x86_64-flac mingw-w64-x86_64-mpg123
To check if Go was installed correctly, run
go env GOROOT
If the command causes the error go: cannot find GOROOT directory: 'go' binary is trimmed and GOROOT is not set,
it means that the enviroment GOROOT variable has to be manually set:
export GOROOT=/mingw64/lib/goNow, when running go env GOROOT, the output should be: <mtsys2-install-folder>/mingw64/lib/go
In that MinGW64 terminal, build with CGO enabled. This keeps gcc and pkg-config on PATH:
CGO_ENABLED=1 go build -o cliamp.exe .Some MSYS2 libogg builds provide libogg-0.dll without ogg_stream_iovecin in its export table. The static libogg.a has this symbol. If linking fails with undefined reference to 'ogg_stream_iovecin', use static linking for this library only:
CGO_LDFLAGS="-Wl,-Bstatic -logg -Wl,-Bdynamic" CGO_ENABLED=1 go build -o cliamp.exe .
cliamp.exe links dynamically to codec and MinGW runtime DLLs. Keep C:\msys64\mingw64\bin on PATH at runtime, or copy each /mingw64/bin/*.dll that ldd cliamp.exe shows next to cliamp.exe.
Clone and build:
git clone https://github.com/bjarneo/cliamp.git cd cliamp make && make install
Or without Make: go build -o cliamp .
make install places the binary in ~/.local/bin/.
A source build uses the same optional runtime dependencies as the other install methods. See Install.
Full documentation is hosted at whiterose.org.contextowl.co/docs/cliamp.
No audio output
cliamp reports audio output unavailable when it cannot open an output
device. On Linux systems that use PipeWire or PulseAudio, the cliamp ALSA
backend needs a bridge package to route audio through the sound server:
pipewire-alsapulseaudio-alsa (libasound2-plugins on Debian/Ubuntu)Install the package for your system:
# PipeWire (Arch) sudo pacman -S pipewire-alsa # PulseAudio (Arch) sudo pacman -S pulseaudio-alsa # Debian/Ubuntu (PipeWire) sudo apt install pipewire-alsa # Debian/Ubuntu (PulseAudio, including WSL2) sudo apt install libasound2-plugins
On WSL2 see WSL2 setup for the extra ALSA routing step.
Use this software at your own risk. The authors are not responsible for damage or issues that result from its use.