Terminal Music Player · Winamp for your shell

Playlists, EQ, visualizers, lyrics, remote control, and a Lua plugin system. Streams from Spotify, YouTube Music, Plex, Jellyfin, Navidrome, and 30,000+ radio stations.

$ cliamp --provider radio tty1
C L I A M P [Playlist]
Lofi Hip Hop Radio
00:00 / 00:00 ■ Stopped (click to play) ◌ Buffering… ● Streaming


        
━━━━━━━━━━━━━━━━━━━━ STREAMING ━━━━━━━━━━━━━━━━━━━━
EQ [Rock] +5 +4 +2 -1 -2 +2 +4 +5 +5 +5 VOL +0dB
SRC [Local] [Navidrome] [Plex] [Jellyfin] [Spotify] [YouTube] [YT Music]
▸─ Playlist ── [Shuffle] [Repeat: Off] [1/3] ──
▶ 1. Lofi Hip Hop Radio
  2. EDM Pulse
  3. Synthwave Nights
↑↓ Scroll Enter Play Spc ▶❚❚ * Fav Tab Focus Ctrl+K Keys
SPD [1x] ↓ 0.7 MB  32 KB/s
$ cliamp https://radio.cliamp.stream/lofi/stream.pls
01 demo.mp4
02 install.sh
Direct
$ curl -fsSL …/install.sh | sh COPIED
Homebrew
$ brew install bjarneo/cliamp/cliamp COPIED
Arch (AUR)
$ yay -S cliamp COPIED
Or build from source — see the README.
03 sources

Stream from everywhere. Every provider runs through the same playlist, EQ, visualizer, and lyrics pipeline — your config follows you across services.

OAuth · cached
Spotify
Stream your Premium library. Search & add tracks with F.
yt-dlp
YouTube
Search and queue videos. Press f to search in-player.
OAuth · cached
YT Music
Browse your playlists with auto music/non-music classification.
Media server
Plex
Browse albums and stream from your Plex Media Server.
Media server
Jellyfin
Artists, albums, tracks — buffered gapless playback.
Subsonic API
Navidrome
Browse your self-hosted library with synced lyrics.
yt-dlp
SoundCloud
Paste SoundCloud URLs with u, or use cliamp search-sc from the shell.
yt-dlp
Bandcamp
Paste any Bandcamp URL and it just plays.
yt-dlp
Bilibili
Audio tracks from Bilibili videos via yt-dlp.
30k+ stations
Radio
Browse stations by country, tag, or name. ICY metadata.
RSS feeds
Podcasts
Pass any podcast RSS URL and listen in your terminal.
Local
Files
MP3, FLAC, OGG, Opus, WAV, AAC, ALAC, WMA. ID3 tags read.
04 features
10-Band Equalizer

Parametric EQ with presets: Rock, Jazz, Pop, Classical, and more.

Themes & Visualizers

17 built-in themes and multiple visualizer modes. Hot-swap with t / v.

Playlists

TOML playlists, M3U/M3U8/PLS support, built-in playlist manager.

HTTP Streaming

Play from URLs, internet radio, and remote M3U playlists.

Synced Lyrics

Auto-scrolling lyrics for local & Navidrome tracks. Press y.

Gapless Playback

Seamless transitions with preloaded next-track buffering.

MPRIS / Media Keys

Desktop integration. Hardware media keys and playerctl.

Audio Quality

Configurable sample rate (22kHz–192kHz), buffer size, resample.

Live Radio Metadata

ICY/Shoutcast metadata — current song on internet radio streams.

Embedded Tag Reading

ID3v2, Vorbis comments, MP4 atoms — artist, album, genre, year.

CLI Flags

Override volume, shuffle, repeat, theme, EQ, sample rate per-session.

Self-Update

Run --upgrade to update to the latest release in-terminal.

Remote Control

Control a running instance from another terminal via Unix-socket IPC.

Lua Plugins

Lua 5.1 sandboxed plugin system. Hook events, add visualizers, push data.

💾
Save to Disk

Press Ctrl+S to save the current track to ~/Music.

05 themes.toml

17 built-in themes. Press t to switch, or use --theme "name" from the CLI. Drop a .toml file in ~/.config/cliamp/themes/ to add your own.

Ayu Mirage Dark
██ ██ ██ ██ ██ ██
Catppuccin
██ ██ ██ ██ ██ ██
Catppuccin Latte
██ ██ ██ ██ ██ ██
Ethereal
██ ██ ██ ██ ██ ██
Everforest
██ ██ ██ ██ ██ ██
Flexoki Light
██ ██ ██ ██ ██ ██
Gruvbox
██ ██ ██ ██ ██ ██
Hackerman
██ ██ ██ ██ ██ ██
Kanagawa
██ ██ ██ ██ ██ ██
Matte Black
██ ██ ██ ██ ██ ██
Miasma
██ ██ ██ ██ ██ ██
Nord
██ ██ ██ ██ ██ ██
Osaka Jade
██ ██ ██ ██ ██ ██
Ristretto
██ ██ ██ ██ ██ ██
Rosé Pine
██ ██ ██ ██ ██ ██
Tokyo Night
██ ██ ██ ██ ██ ██
Vantablack
██ ██ ██ ██ ██ ██
Each swatch: accent · bright fg · fg · green · yellow · red
06 keybindings.conf
Transport
SpacePlay / Pause
sStop
> / <Next / Previous track
← →Seek −/+5s
Shift+← Shift+→Seek −/+30s (default)
N then jSeek to N×10% (e.g. 7j = 70%)
Ctrl+JJump to time
+ / −Volume up / down
] / [Speed ±0.25x
mToggle mono
r / zRepeat / Shuffle
Navigation
TabFocus: Playlist / EQ
j / kScroll or adjust EQ (wraps)
h / lEQ band left / right
PgUp / PgDnPage up / down
Ctrl+U / Ctrl+DHalf-page scroll
Home / EndJump to top / end
g / GVim-style top / bottom
EnterPlay selected
Shift+↑ Shift+↓Move track up / down
Esc / bBack to provider
Search & Browse
/Search playlist
Ctrl+FSearch (active provider or YouTube)
fToggle bookmark ★ / radio favorite
uLoad URL (stream / playlist)
oOpen file browser
a / AQueue (play next) / Queue manager
pPlaylist manager
LBrowse local playlists
Ctrl+XExpand playlist
Providers & UI
NNavidrome
SSpotify
PPlex
JJellyfin
YYouTube
RRadio
e / t / vEQ preset / Theme / Visualizer
VFull-screen visualizer
y / iLyrics / Track info
Ctrl+SSave to ~/Music
Ctrl+KShow keymap
qQuit
07 cli & remote control

CLI flags override any config option for a single session. Remote commands control a running instance over Unix-socket IPC — open another terminal and talk to cliamp directly.

Flags
--volume <dB>[-30, +6]
--shuffleEnable shuffle
--repeat <mode>off, all, one
--mono / --no-monoMono downmix
--auto-playStart immediately
--theme <name>UI theme
--eq-preset <name>EQ preset
--visualizer <mode>Bars, Wave, Matrix, Retro…
--sample-rate <Hz>Output sample rate
--buffer-ms <ms>Speaker buffer 50–500
--resample-quality <n>1–4
--bit-depth <n>PCM: 16 or 32
--compactCap width at 80 cols
--playlist <name>Load TOML playlist
--provider <name>Default provider
--upgradeUpdate in place
--help / --versionHelp & version
Remote
play / pause / togglePlayback control
stopStop playback
next / prevTrack navigation
status [--json]Current state
volume <dB>Set volume
seek <secs>Relative seek
load "Name"Load a playlist
queue /path/fileQueue a track
shuffle [on|off]Toggle or set shuffle
repeat [off|all|one]Set or cycle repeat
mono [on|off]Mono output
speed <ratio>0.25–2.0
eq <preset>Flat, Rock, Pop, Jazz…
eq --band <0-9> <dB>Set individual band
device listList output devices
device <name>Switch device
theme <name|list>Set or list themes
vis <name|next|list>Set or cycle visualizer
08 plugins.lua

Lua 5.1 plugin system. Hook into playback events, add custom visualizers, or push data to external services. Each plugin runs in an isolated sandbox — a crash in one cannot affect others or the player. Drop a .lua file in ~/.config/cliamp/plugins/ and restart.

now-playing.lua
-- ~/.config/cliamp/plugins/now-playing.lua
local p = plugin.register({
    name = "now-playing",
    type = "hook",
})

p:on("track.change", function(track)
    cliamp.fs.write("/tmp/cliamp-now-playing",
        track.artist .. " - " .. track.title)
end)

p:on("app.quit", function()
    cliamp.fs.remove("/tmp/cliamp-now-playing")
end)
webhook.lua
-- ~/.config/cliamp/plugins/webhook.lua
local p = plugin.register({
    name = "webhook",
    type = "hook",
})

local url = p:config("url")

p:on("track.change", function(track)
    if not url then return end
    cliamp.http.post(url, {
        json = { title = track.title, artist = track.artist }
    })
end)
simple-bars.lua (custom visualizer)
-- ~/.config/cliamp/plugins/simple-bars.lua
local p = plugin.register({
    name = "simple-bars",
    type = "visualizer",
})

-- Called ~20 FPS. bands: 10 values (0.0-1.0)
function p:render(bands, frame)
    local lines = {}
    for row = 5, 1, -1 do
        local line = ""
        for i = 1, 10 do
            if bands[i] > (row - 1) / 5 then
                line = line .. "██████ "
            else
                line = line .. "       "
            end
        end
        table.insert(lines, line)
    end
    return table.concat(lines, "\n")
end
Events
track.changeNew track starts playing
track.scrobbleTrack played ≥50% or ≥4 min
playback.statePlay, pause, stop, seek, volume change
app.startAfter all plugins loaded
app.quitBefore shutdown
API
player

Read-only state: state(), position(), volume(), shuffle(), eq_bands()

track

Current metadata: title(), artist(), album(), genre(), duration_secs()

http

HTTP client: get(), post(). JSON, form body, headers, 5s timeout.

fs

Sandboxed I/O: write(), read(), append(), remove(), exists()

json

encode() and decode() for JSON serialization.

crypto

md5(), sha256(), hmac_sha256() for hashing and signing.

notify

Desktop notifications via notify-send. Works with mako, dunst, etc.

message

message(text, secs) → transient message in the player's status bar.

timer

Schedule callbacks: after(), every(), cancel()

log

info(), warn(), error(), debug()plugins.log

config

Read per-plugin values from [plugins.name] in config.toml via p:config(key)

Community
Last.fm scrobbling
09 radio.stats
LIVE
-
listening now
-
total sessions
-
listen hours
Daily Activity
Listeners Around the World
Top Countries