GitHub - bjarneo/cliamp: cliamp - Terminal music player inspired by winamp

A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Bilibili, Spotify, 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.

Radio

Tune in to our radio channel:

cliamp https://radio.cliamp.stream/lofi/stream.pls

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. See docs/configuration.md.

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

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)

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.

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

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

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

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.

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

Linux (Arch):

macOS: No extra dependencies — CoreAudio is used.

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

Docs

• Configuration
• Keybindings
• CLI Flags
• Streaming
• Playlists
• YouTube, SoundCloud, Bandcamp and Bilibili
• YouTube Music
• Lyrics
• Spotify
• Navidrome
• Plex
• Jellyfin
• Themes
• SSH Streaming
• Remote Control (IPC)
• Audio Quality
• Media Controls
• 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

Omarchy

Add this keybind to launch cliamp with Super+Shift+M:

bindd = SUPER SHIFT, M, Music, exec, omarchy-launch-tui cliamp

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.