A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Mixcloud, Bilibili, Spotify, Qobuz, Tidal, Bandcamp purchases, NetEase Cloud Music, Yandex Music, Xiaoyuzhou (小宇宙), Navidrome, Lyrion, Plex, Jellyfin, Emby, Audiobookshelf, and Telegram. Use the spectrum visualizer, parametric EQ, and playlists.
cliamp.stream | docs | android | discord
On a phone, run cliamp mobile. It is a native Android client for radio, podcasts, and the same servers this player talks to.
cliamp uses Bubbletea, Lip Gloss, Beep, and go-librespot.
https://github.com/user-attachments/assets/55e251f2-e13b-43d9-bb6a-7b1960e7d7d0
Install
curl -fsSL https://cliamp.stream/install.sh | sh
Homebrew
brew install bjarneo/cliamp/cliamp
The formula installs all required runtime libraries.
Arch Linux (AUR)
yay -S cliamp
Nix
nix run github:bjarneo/cliamp
For a declarative NixOS configuration, add github:bjarneo/cliamp as a flake
input. Install its default package:
inputs.cliamp.url = "github:bjarneo/cliamp";
environment.systemPackages = [
inputs.cliamp.packages.${pkgs.stdenv.hostPlatform.system}.default
];
Go
go install github.com/bjarneo/cliamp@latest
Install ALSA development headers before you build on Linux. See Building from source.
Pre-built binaries
Download from GitHub Releases.
macOS: Pre-built binaries link dynamically to FLAC, Vorbis, Ogg, and mpg123
from Homebrew. If you download from Releases or use install.sh, install these
libraries first. Otherwise, you can see errors such as
Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib:
brew install flac libvorbis libogg mpg123
brew install bjarneo/cliamp/cliamp installs these libraries.
Linux: Pre-built binaries link FLAC, Vorbis, Ogg, and mpg123 statically. No
extra codec packages are required. You can 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 that Spotify requires. On Windows, cliamp stores
its config under %APPDATA%\cliamp unless HOME names another directory.
Optional runtime dependencies for all platforms and install methods:
- ffmpeg for AAC, ALAC, Opus, and WMA playback
- yt-dlp for YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp, Bilibili, and NetEase Cloud Music
On macOS, run brew install ffmpeg yt-dlp. On Linux, use your distribution package manager.
On Windows, install ffmpeg and yt-dlp with your package manager. 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 such as Navidrome, Lyrion, Bandcamp, Plex, Jellyfin, Emby, Audiobookshelf, Spotify, Qobuz, Tidal, Mixcloud, YouTube Music, NetEase Cloud Music, and Telegram with the interactive wizard:
cliamp setup
The wizard guides you through each provider. It writes the provider keys into the section of that provider in your config file (~/.config/cliamp/config.toml, or %APPDATA%\cliamp\config.toml on Windows unless HOME names another directory). It keeps your other keys and comments. It validates supported server connections during setup. The OAuth providers Spotify, Qobuz and Tidal sign in later in the player, and Telegram offers the sign-in right after saving. Mixcloud checks optional browser-session or OAuth credentials when you use them. See docs/cli.md for details.
See the Mixcloud provider guide for discovery, account,
creator/show, genre search, local genre favorites, authentication, signed-in
playback, resume, seeking, and limitations.
For podcast discovery and subscriptions, run cliamp --provider podcast.
Browse Apple's top 100 shows and 19 categories, search with / then Enter,
and subscribe with f. No account or API key is needed.
See the Podcasts guide.
Remote Control
Control a running cliamp from a script, a status bar, or a key binding:
cliamp toggle
cliamp next
cliamp status --json
Media keys work through MPRIS on Linux, Now Playing on macOS, and global
hotkeys on Windows.
Run cliamp --daemon to play without a TUI. Headless mode runs the same
player as the TUI. It loads your Lua plugins, reports plays to Navidrome,
Jellyfin, and the other providers that take play reports, and adds each track
to Recently Played when the track starts. See
docs/headless.md and
docs/remote-control.md.
Radio
Press R in the player to browse about 58,000 online radio stations in the Radio Browser directory.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
