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.
$ 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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
-- 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)
cliamp.track.is_live() before treating a track as one that ends.p:init and p:destroy run when the mode is selected and left. Plugin API reference ↗cliamp plugins install user/cliamp-plugin-name