██████ ██ ██ █████ ███ ███ ██████ ██ ██ ██ ██ ██ ████ ████ ██ ██ ██ ██ ██ ███████ ██ ████ ██ ██████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████ ███████ ██ ██ ██ ██ ██ ██
$ cliamp https://radio.cliamp.stream/lofi/stream.pls
$ curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh
COPIED
$ brew install bjarneo/cliamp/cliamp
COPIED
$ yay -S cliamp
COPIED
MP3, WAV, FLAC, OGG, AAC, ALAC, Opus, and WMA
Parametric EQ with presets: Rock, Jazz, Pop, Classical, and more
Multiple color themes and visualizer modes to match your vibe
TOML playlists, M3U/M3U8/PLS support, built-in playlist manager
Play from URLs, internet radio stations, and remote M3U playlists
YouTube, SoundCloud, Bandcamp, and Bilibili playback via yt-dlp. Search YouTube with cliamp search "query" or SoundCloud with cliamp search-sc "query". Press f / F to search in-player
Pass an RSS feed URL and listen to any podcast in your terminal
Browse and stream your self-hosted Navidrome music library
Synced lyrics with auto-scroll for local & Navidrome tracks, manual scroll for streams. Press y to view
Seamless track transitions with preloaded next-track buffering
Linux desktop integration. Control playback with hardware media keys and playerctl
Configurable sample rate (22kHz–192kHz), buffer size, and resample quality
ICY/Shoutcast metadata. See the current song title on internet radio streams
ID3v2, Vorbis comments, and MP4 atoms. Reads artist, album, genre, year, and track number
Override volume, shuffle, repeat, mono, theme, EQ, sample rate, and more per-session
Run --upgrade to update to the latest release directly from your terminal
Stream your Spotify Premium library. Playlists, EQ, visualizer, and all effects apply. OAuth login with cached credentials
Browse and play your YouTube Music playlists via OAuth. Automatic music/non-music classification with cached login
Stream music from your Plex Media Server. Browse albums and play directly. No extra software required
Stream music from your Jellyfin server. Browse artists, albums, and tracks with buffered gapless playback
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.
Override any config option for a single session. Flags can appear before, after, or between file arguments.
Control a running cliamp instance from another terminal via Unix socket IPC.
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.
-- ~/.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)
-- ~/.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)
-- ~/.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
Read-only playback state: state(), position(), volume(), shuffle(), eq_bands(), and more
Current track metadata: title(), artist(), album(), genre(), duration_secs()
HTTP client with get() and post(). JSON, form body, custom headers. 5s timeout
Sandboxed file I/O: write(), read(), append(), remove(), exists()
encode() and decode() for JSON serialization
md5(), sha256(), hmac_sha256() for hashing and signing
Desktop notifications via notify-send. Works with mako, dunst, etc.
Schedule callbacks: after(), every(), cancel()
info(), warn(), error(), debug() → ~/.config/cliamp/plugins.log
Read per-plugin values from [plugins.name] in config.toml via p:config(key)