cliamp

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, and Jellyfin with a spectrum visualizer, parametric EQ, and playlist management.

cliamp.stream

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

Pre-built binaries

Download from GitHub Releases.

macOS: the pre-built binaries dynamically link against FLAC, Vorbis, and Ogg 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

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

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

Windows: download cliamp-windows-amd64.exe from Releases. If HOME is not set, cliamp stores its config under %APPDATA%\cliamp. The Spotify provider is currently unavailable on Windows builds.

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, 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

Linux (Fedora):

sudo dnf install alsa-lib-devel libvorbis-devel flac-devel

Linux (Arch):

sudo pacman -S alsa-lib

macOS: No extra dependencies — CoreAudio is used.

Windows: No extra SDKs required for the core player. ffmpeg.exe and yt-dlp.exe remain optional runtime dependencies for the same formats/providers as on other platforms. Spotify is not available on Windows builds.

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

• Configuration
• Keybindings
• CLI Flags
• Streaming
• Playlists
• YouTube, SoundCloud, Bandcamp and Bilibili
• YouTube Music
• NetEase Cloud Music
• SoundCloud
• Lyrics
• Spotify
• Navidrome
• Plex
• Jellyfin
• Themes
• SSH Streaming
• Remote Control (IPC)
• Headless Daemon Mode
• Audio Quality
• Media Controls
• Quickshell Now-Playing Widget (Omarchy)
• Lua Plugins
  • Community Plugins
  • Soap Bubbles Visualizer

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.