~/audio/cliamp

cliamp

A full music player that lives in your terminal. No browser tab required.

Playlists, a 10-band equalizer, 34 visualizers, synced lyrics, podcasts, remote control, and Lua plugins. Stream from Spotify, Qobuz, Tidal, Bandcamp, YouTube Music, SoundCloud, Mixcloud, NetEase Cloud Music, Yandex Music, Plex, Jellyfin, Emby, Navidrome, Lyrion, Audiobookshelf — plus podcast feeds and about 58,000 internet radio stations.

Linux · macOS · Windows Android ↗ cliamp mobile MIT licensed Go 1.26
$ cliamp --provider radioplays live in your browser
tty1 C L I A M P
♫Lofi
pick a station below and press play
00:00 ■ stopped live stream
EQ [Rock]
SRC [Radio] 1/14
▸─ Playlist[Shuffle: Off][Repeat: All]
$ cliamp https://radio.cliamp.stream/lofi/stream.plsspace · < >

Install

One line. Click any command to copy it.

then just run cliamp — cliamp setup walks you through streaming services and media servers. Optional: ffmpeg for AAC, ALAC, Opus, WMA, and the audio streams of MP4 and WebM, yt-dlp for YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp, Bilibili and NetEase. GNOME Keyring browser cookies also require Python secretstorage on Linux. Behind a proxy? cliamp reads HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY, and SOCKS5 proxies work (proxy docs). Windows builds are in Releases. Windows source builds need CGO and MSYS2 MinGW64 even when Spotify is not configured; see the source-build instructions.

Every source, one interface

Streaming services, self-hosted libraries, local files, podcasts, and radio — all through the same playlist, EQ, visualizer, and lyrics pipeline.

Setup steps and limits for each source are in the docs ↗. Guides: radio favorites, track favorites, download directory, Navidrome transcoding, Jellyfin, Spotify.

What's inside

10-BAND EQ

Parametric equalizer with 16 presets — Rock, Jazz, Classical, Bass Boost, Vocal, Podcast and more — or dial in your own curve. The Custom preset survives restarts.

VISUALIZERS

34 built-in modes rendered in the terminal from live FFT data: spectrum bars, scope, wave, matrix, flame, and a true-stereo LED peak meter. ClassicPeak uses smooth bars and floating peak caps, with sampling aligned to audible playback and adaptive redraws for smooth motion. ClassicLED redraws at 30 FPS during playback. Neighboring bands are averaged into each bar. YinYang koi chase each other across a wide strip, leaving on the right and coming back on the left; taller panels have them circle a lily pad whose lotus follows recent bass levels, including after silence or time in the strip. Ethereal brings Omarchy's cosmic wallpaper to life with Flame-style Braille pixels and an untouched background: bass swells drifting clouds, mids lift bright highlights, and treble brightens twinkling stars. Its colors follow the terminal palette by default and the selected cliamp theme, with no Omarchy installation required. v cycles, V goes full screen.

SYNCED LYRICS

Embedded LRC first, then Spotify for signed-in Spotify tracks, with LRCLIB and NetEase fallback. Time-aligned lines scroll with song playback; fine-tune timing with [/] if a source is slightly off. Live radio refreshes on every ICY track change and uses manual scrolling, even with timestamped lyrics. Press y.

PLAYLISTS & QUEUE

TOML playlists with live [[dir]] folder sources, M3U/M3U8/PLS import and export, cross-playlist favorites, a play-next queue that reads like the playlist and toggles in place with A, a shuffle view that lists tracks in the order they play, saved playlists you can append to what is playing or put the current track at the front of, and undo.

Folder scans skip files and subdirectories whose names start with ., including macOS AppleDouble sidecars. Explicit file arguments still work.

REMOTE CONTROL

Newline-delimited JSON over a local Unix socket, with full state snapshots and push events for scripts, status bars, and GUIs. Media keys via MPRIS on Linux, Now Playing on macOS, and global hotkeys on Windows (registered with and without Win held, so keyboard remappers that reach media keys through a held Win layer still work). Run --daemon for headless playback with the same plugins, scrobbling, and history as the TUI.

THEMES

22 built-in color schemes that pass contrast checks — catppuccin, dracula, gruvbox, nord, tokyo-night, winamp and more — or drop a TOML file in ~/.config/cliamp/themes. Press t.

PODCASTS

Apple's top charts and 19 genre categories, or any RSS feed. Browse episodes, subscribe locally with f, and, with ffmpeg installed, seek anywhere in an episode; the real length is measured from the file, not the feed. Episodes resume where you left off and are ticked once finished. F lists your subscriptions and pulls the newest episode of any show, or of all of them, without replacing the queue. No account or API key.

GAPLESS & STREAMS

Preloads the next track for seamless transitions. Plays URLs, HLS (.m3u8) and internet radio with jitter buffering and live ICY metadata, and cliamp:// links from a browser or chat.

cliamp radio

Fourteen channels we run ourselves — always on, no account. Play any of them in the player above, or pipe the URL straight into cliamp or any player of your choice. In cliamp, a channel with a song library opens as a playlist of its songs.

read the radio docs ↗

Who's listening right now

Live connections to the cliamp radio channels and their playlists, by country. Drag the globe to spin it, or hover a country for its count.

–
LISTENERS
–
ON PLAYLISTS
–
COUNTRIES

$ cliamp radio --stats --globe● live
TOP COUNTRIESLISTENERS

Keyboard first

Everything is one keystroke away — no mouse, no menus. Vim-style j/k movement, Tab cycles the controls, and ? or Ctrl+K shows the full keymap for the screen you are on. Select a command and press Enter to run it. All keybindings ↗

Extend it with Lua

Hook playback events, add commands and key bindings, scrobble, post to a status bar, or draw a visualizer — plugins drop into ~/.config/cliamp/plugins/ and run in sandboxed Lua 5.1 VMs. A crashing plugin never takes the player down.

plugins/now-playing.lua
-- write the current track for Waybar, Polybar, tmux…
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)
track.change · playback.state · queue.end
12 events to subscribe to: track changes, scrobbles, seeks, volume, EQ, shuffle and repeat, queue edits, end of queue, explicit stops, start and quit. Each plugin gets its events in the order they happen. Track-change events fire after playback starts successfully, including YouTube, SoundCloud, and gapless transitions. Buffering, failed, or superseded starts do not emit a track change. End-of-queue events report the last track that started playing; a manual stop, a stream still buffering, or a failed start does not emit one. Playback-state events fire once for each change, and once per second while a track plays. A hook reads the state that includes the change its event reports. Ask cliamp.track.is_live() before treating a track as one that ends.
cliamp.queue.has_next()
Reports whether another playable track exists, honoring the play-next queue, repeat, and shuffle.
cliamp.queue.add({ path, title, artist, … })
Queue a track exactly as described, such as a Spotify track with its title and artist, without resolving its path.
cliamp.queue.move(from, to) · cliamp.queue.remove(i)
Edit the queue by the rules of the keys and IPC. While shuffle is on, a move changes nothing. A loaded saved playlist gets the same edit.
p:bind("ctrl+n", fn) · p:command("name", fn)
Register your own key bindings and shell-invokable commands.
cliamp.http · cliamp.fs · cliamp.store · cliamp.timer
Talk to any API, write files for status bars, persist state and schedule work — inside a sandbox with declared permissions.
cliamp.layout · cliamp.image · cliamp.vis
Add panes to any region, read an image file for terminal graphics and blend your own canvas frame with the built-in visualizer.
cliamp.ui.select · cliamp.track.album_art_url()
Open a picker modal with your own options and callbacks, and resolve the current cover as a ready-to-use URL.
type = "visualizer" → p:render(bands, frame, rows, cols)
Draw your own visualizer from the smoothed spectrum bands. Optional p:init and p:destroy run when the mode is selected and left. Plugin API reference ↗
COMMUNITY PLUGINScliamp plugins install user/cliamp-plugin-name

Close the tab. Play the music.

star on github