cliamp: A Retro Terminal Music Player

Home

Retro, Winamp 2.x-inspired TUI music player written in Go (Bubbletea, Lip Gloss, Beep). Plays local files, internet radio, podcasts, and streams from YouTube, YouTube Music, Spotify, SoundCloud, Bilibili, NetEase Cloud Music, Navidrome, Plex, Jellyfin, Qobuz, and more.

Site: https://cliamp.stream
Repo: https://github.com/bjarneo/cliamp

Install

curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh

# Homebrew
brew install bjarneo/cliamp/cliamp

# Arch (AUR)
yay -S cliamp

# Go
go install github.com/bjarneo/cliamp@latest

Optional runtime deps: ffmpeg (AAC/ALAC/Opus/WMA playback), yt-dlp (YouTube/SoundCloud/Bandcamp/Bilibili/NetEase).

Quick start

cliamp ~/Music                     # play a directory
cliamp *.mp3 *.flac                # play files
cliamp https://example.com/stream  # play a URL
cliamp setup                       # wizard for Navidrome/Plex/Jellyfin/Spotify/etc.

Config: ~/.config/cliamp/config.toml. Custom radio stations: ~/.config/cliamp/radios.toml.

Core features

Real-time spectrum visualizer, 20+ styles (v cycle, Ctrl+V picker w/ live preview, V fullscreen)
10-band parametric EQ with presets (e cycle)
Playlist and queue manager, undo support
Radio browser — 30,000+ stations via Radio Browser directory (R)
Lyrics lookup (y)
Remote provider integration: Navidrome, Plex, Jellyfin, Emby, Spotify, Qobuz, YouTube Music, NetEase
Themes (t), Lua plugin system, MPRIS/media-key support
Headless daemon mode, remote control via local-socket IPC
Bookmarks/favorites (f), track metadata view (i)

Key shortcuts

Playback

Key	Action
`Space`	Play / Pause
`s`	Stop
`>` `.`	Next track
`<` `,`	Previous track
`Left` `Right`	Seek ±5s
`Shift+Left/Right`	Seek ±30s
`N` then `j`	Seek to N×10% (e.g. `7j` → 70%)
`+` `-`	Volume up/down
`]` `[`	Speed ±0.25x
`m`	Toggle mono
`Ctrl+J`	Jump to time

Key	Action
`Tab`	Cycle visible controls (Playlist/EQ/Source/Speed)
`j` `k` / `↑` `↓`	Playlist scroll / EQ band adjust
`PageUp/Down`, `Ctrl+U/D`	Scroll by page
`Home` `End` / `g` `G`	Top/end of list
`Shift+↑` `Shift+↓`	Move track in playlist/queue
`Enter`	Play selected track
`/`	Search playlist
`Ctrl+X`	Expand/collapse playlist
`Ctrl+Z`	Undo last removal/clear
`o`	Open file browser
`b` `Esc`	Back to provider

EQ & Appearance

Key	Action
`e`	Cycle EQ preset
`t`	Choose theme
`v`	Cycle visualizer
`Ctrl+V`	Visualizer picker (live preview)
`V`	Fullscreen visualizer
`Ctrl+H`	Toggle album headers

Features

Key	Action
`f`	Bookmark track / favorite station
`Ctrl+F`	Provider search (or YouTube fallback)
`u`	Load URL (stream/playlist)
`y`	Show/close lyrics
`i`	Track metadata
`Ctrl+S`	Save track to `~/Music/cliamp`
`w`	Write track to local playlist
`L`	Browse local playlists
`R`	Radio provider
`S` `P` `J` `E` `Y` `C` `M` `Q`	Spotify / Plex / Jellyfin / Emby / YouTube / SoundCloud / NetEase / Qobuz

Playlist & Queue

Key	Action
`a`	Toggle queue (play next)
`A`	Queue manager
`x`	Remove highlighted track
`p`	Playlist manager
`r`	Cycle repeat (Off/All/One)
`z`	Toggle shuffle

General

Key	Action
`?` / `Ctrl+K`	Show full keymap
`q`	Quit

Full docs (playlists, streaming, plugins, themes, remote control, headless mode): https://github.com/bjarneo/cliamp/tree/main/docs

Tags: CliMusicLinuxCheatsheet