██████ ██      ██  █████  ███    ███ ██████
██      ██      ██ ██   ██ ████  ████ ██   ██
██      ██      ██ ███████ ██ ████ ██ ██████
██      ██      ██ ██   ██ ██  ██  ██ ██
 ██████ ███████ ██ ██   ██ ██      ██ ██

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

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

cliamp_whips_tty_ass_compressed.mp4

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

Arch Linux (AUR)

yay -S cliamp

Pre-built binaries

Download from GitHub Releases.

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):

sudo pacman -S alsa-lib

macOS: No extra dependencies — CoreAudio is used.

Clone and build:

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

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
• Themes
• Audio Quality
• MPRIS
• Lua 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.