A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Bilibili, Spotify, NetEase Cloud Music, Xiaoyuzhou (小宇宙), Navidrome, Plex, Jellyfin, and Audiobookshelf with a spectrum visualizer, parametric EQ, and playlist management.

cliamp.stream · docs

Built with Bubbletea, Lip Gloss, Beep, and go-librespot.

https://github.com/user-attachments/assets/fbc33d20-e3ac-4a62-a991-8a2f0243c8ea

Install

curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh

Homebrew

brew install bjarneo/cliamp/cliamp

The formula pulls in all required runtime libraries automatically.

Arch Linux (AUR)

yay -S cliamp

Go

go install github.com/bjarneo/cliamp@latest

Linux builds need ALSA development headers installed first. See Building from source.

Pre-built binaries

Download from GitHub Releases.

macOS: the pre-built binaries dynamically link against FLAC, Vorbis, Ogg, and mpg123 from Homebrew. If you download directly from Releases (or use the install.sh script) you must install them first, otherwise you will see errors like Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib:

brew install flac libvorbis libogg mpg123

Installing via brew install bjarneo/cliamp/cliamp does this for you.

Linux: the pre-built binaries statically link FLAC, Vorbis, Ogg, and mpg123, so no extra codec packages are required. You may still need an ALSA bridge for your sound server — see Troubleshooting.

Windows: download and extract cliamp-windows-amd64.zip from Releases. It includes the codec DLLs required by Spotify. If HOME is not set, cliamp stores its config under %APPDATA%\cliamp.

Optional runtime dependencies (all platforms, all install methods):

• ffmpeg — for AAC, ALAC, Opus, and WMA playback
• yt-dlp — for YouTube, YouTube Music, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music

On macOS: brew install ffmpeg yt-dlp. On Linux, use your distribution's package manager.

On Windows, install ffmpeg and yt-dlp with your preferred package manager and keep both on PATH.

Build from source

git clone https://github.com/bjarneo/cliamp.git && cd cliamp && go build -o cliamp .

Quick Start

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 (Navidrome, Plex, Jellyfin, Audiobookshelf, Spotify, YouTube Music, NetEase Cloud Music) with the interactive wizard:

cliamp setup

It walks you through each provider, validates the connection, and writes the right block to your config file (~/.config/cliamp/config.toml, or %APPDATA%\cliamp\config.toml on Windows when HOME is unset). See docs/cli.md for details.

Radio

Press R in the player to browse and search 30,000+ online radio stations from the Radio Browser directory.

Add your own stations to ~/.config/cliamp/radios.toml (or %APPDATA%\cliamp\radios.toml on Windows when HOME is unset). See docs/configuration.md.

Want to host your own radio? Check out cliamp-server.

Building from source

Prerequisites:

• Go 1.25.5 or later
• ALSA development headers (Linux only — required by the audio backend)

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: No extra SDKs required for the core player — it uses pure-Go audio decoding. ffmpeg.exe and yt-dlp.exe remain optional runtime dependencies for the same formats/providers as on other platforms.

Spotify support uses go-librespot, which needs CGO and a MinGW toolchain:

1. Install MSYS2.
2. Open the MSYS2 MinGW64 terminal (not the plain MSYS2 terminal) and install the toolchain and codec libraries:

   pacman -S mingw-w64-x86_64-gcc 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
   

3. From that same MinGW64 terminal (so gcc/pkg-config are on PATH), build with CGO enabled:

   CGO_ENABLED=1 go build -o cliamp.exe .
   

   Some MSYS2 libogg builds ship a libogg-0.dll whose export table is missing ogg_stream_iovecin, even though it's present in the static libogg.a. If the link fails with undefined reference to 'ogg_stream_iovecin', force static linking of just that library:

   CGO_LDFLAGS="-Wl,-Bstatic -logg -Wl,-Bdynamic" CGO_ENABLED=1 go build -o cliamp.exe .
   

4. cliamp.exe dynamically links codec and MinGW runtime DLLs. Either keep C:\msys64\mingw64\bin on PATH at runtime, or copy every /mingw64/bin/*.dll shown by ldd cliamp.exe 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/.

Optional runtime dependencies:

• ffmpeg — for AAC, ALAC, Opus, and WMA playback
• yt-dlp — for YouTube, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music

Docs

Full documentation is hosted at whiterose.org.contextowl.co/docs/cliamp.

Troubleshooting

No audio output (silence with no errors)

On Linux systems using PipeWire or PulseAudio, cliamp's ALSA backend needs a bridge package to route audio through your sound server:

• PipeWire: pipewire-alsa
• PulseAudio: pulseaudio-alsa

Install the appropriate 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

Author

x.com/iamdothash

Disclaimer

Use this software at your own risk. We are not responsible for any damages or issues that may arise from using this software.