bjarneo
2885f4dfff
Lock the main goroutine to OS thread 1 in init() and defer MediaKeysInit to RunMainLoop so MPRemoteCommandCenter handlers are registered on the correct thread for CFRunLoop delivery.
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.
Built with Bubbletea, Lip Gloss, Beep, and go-librespot.
https://github.com/user-attachments/assets/fbc33d20-e3ac-4a62-a991-8a2f0243c8ea
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
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
- MPRIS
- Lua Plugins
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
Disclaimer
Use this software at your own risk. We are not responsible for any damages or issues that may arise from using this software.