cliamp
Winamp for the shell. No browser tab required.
Use playlists, a 10-band EQ, visualizers, synced lyrics, remote control, and Lua plugins. Stream from Spotify, Qobuz, Tidal, YouTube Music, Plex, Jellyfin, Emby, Navidrome, Lyrion, Yandex Music, and about 58,000 radio stations.
Select a station to play it live in this browser.
$ cliamp https://radio.cliamp.stream/lofi/stream.pls
install.sh
HOME is not set, the config is in %APPDATA%\cliamp.
demo.mp4
sources
Use all providers with the same playlist, EQ, visualizer, and lyrics pipeline. Your config works across services. Run cliamp setup to configure Navidrome, Lyrion, Plex, Jellyfin, Emby, Audiobookshelf, Spotify, Qobuz, Tidal, Mixcloud, NetEase, and YouTube Music.
client_id to use a private Web API quota. Authorize playback separately. Search with Ctrl+F. The app handles Development Mode paging. Pre-built Windows releases support Spotify.[qobuz] enabled = true. Stream lossless FLAC from your subscription, up to 24-bit/192kHz. Browse favorites and playlists. Search with Ctrl+F. Sign in once with OAuth in your browser.[tidal] enabled = true. Stream lossless FLAC at CD quality from your subscription. Browse favorite tracks, artists, albums, and your playlists. Favorite artists and albums open the hierarchical browser, also reachable with N. Search tracks and albums with Ctrl+F. Album results appear first and expand to the full track list. Sign in once by approving a link.tidal.com device code.cookies_from in your config.[soundcloud] enabled = true. Search with Ctrl+F, browse curated genre playlists, or add user for your profile. cookies_from lets you play Go+ tracks from your browser session.[mixcloud] enabled = true. Browse account Stream and Favorites, followed Creators, recent and popular shows, collections, and creator Uploads and Favorites. Search shows and discover live genres and tags. View locally favorited style charts, restricted-show warnings, and resume. Press Shift+X to open. Browser cookies support signed-in playback.cliamp setup after you sign in at music.163.com. Then select your browser. Browse liked songs, account playlists, saved playlists, and charts. Use browser cookies for playback.[yandex] enabled = true with a personal OAuth token. Browse liked tracks and your playlists, search the catalog. Playback uses direct signed CDN URLs.cliamp --provider podcast. No account or API key. Discover Apple's top 100 shows and 19 genre categories. Use / to search shows or enter an RSS URL, Enter to load episodes, and f to subscribe locally. Ctrl+F also supports whole-feed playback and queueing. Feeds load up to 300 episodes. Optional [podcast] country = "no" selects the chart country (default us, no location detection). Podcasts guide.Browser session setup
Sign in at music.163.com. Then run cliamp setup. Select NetEase Cloud Music and the browser you used. The wizard checks the session before it writes the config.
[netease]
enabled = true
cookies_from = "chrome"
user_id = "your-account-user-id"After setup, press M to open NetEase and Ctrl+F to search. Playback uses yt-dlp and the same browser cookie source.
features
Use parametric EQ presets. The persistent Custom curve remains after preset changes and restarts.
Use 22 built-in themes with contrast checks. Select spectrum, mirrored spectrum, waveform, particle, and true-stereo modes. Wave, Scope, and Heartbeat run at 60 FPS. Use --visualizer-60fps for smoother animation in other modes. Stereo has separate L/R horizontal LED peak meters. Press t / v to change them. Set vis_rows for a taller spectrum, or press V for full screen.
Use TOML playlists and dynamic [[dir]] directory sources. In the playlist manager (D), add, remove, and turn recursive search on or off. Create, rename, delete, and fill playlists with folders or files in the manager (a/r/d). Use cross-playlist favorites (n). Import and export M3U/M3U8/PLS files. The app prevents duplicate writes and sorts in the TUI or CLI.
The app records listening history automatically. Browse it as a virtual playlist or run cliamp history.
Play URLs, internet radio, remote M3U playlists, and HLS (.m3u8) streams. The app uses decoded-audio jitter buffering for live radio.
Use embedded local lyrics first. The app uses LRCLIB/NetEase if needed. It auto-scrolls timestamped lyrics.
The app preloads the next track for seamless transitions.
The app integrates with the desktop. Use hardware media keys on Linux (MPRIS, playerctl), macOS (Control Centre, Lock Screen), and Windows. The app shows embedded local cover art.
Set the sample rate and buffering time (up to 5 seconds). Use resampling.
View ICY/Shoutcast metadata for the current internet-radio song. Get API-based now-playing data for FIP and NTS.
Cut 58,000 stations down by country, genre, or tag. Press N to browse 241 countries grouped by region, or open Browse genres & tags and use / to filter the directory's complete tag index; Enter loads up to 200 matching stations as a playlist. Pin the countries you listen to with f. cliamp only reads your country from the system timezone if you explicitly accept "Use my location," and never uses a geo-IP lookup. Radio guide.
Read ID3v2, Vorbis comments, and MP4 atoms: artist, album, genre, year, lyrics, and cover art.
Use flags to override volume, shuffle, repeat, theme, EQ, and sample rate for a session. Persisted boolean options support matching --no-* flags.
Generate completion scripts for Bash, Zsh, Fish, and PowerShell.
Write logs to ~/.config/cliamp/cliamp.log. Set log_level in the config or --log-level on the CLI: debug, info, warn, error.
Run cliamp upgrade for stable releases. Run cliamp upgrade --prerelease to test beta releases.
Read any string in config.toml from the environment with ${VAR} or $VAR. Keep passwords and tokens out of the file.
Start a song from a browser, a chat message, or a script. Open cliamp://play?url=... or cliamp://play?provider=navidrome&album=... and it plays. Links reach a running instance over IPC, or start the player. The installer registers the scheme on Linux; only http and https targets are accepted, and cliamp protocol unregister removes it. URL scheme guide.
Control a running instance or build a GUI with V2-only local-socket IPC. It provides complete state snapshots, jobs, live playlist and provider controls, and push NDJSON events. Run with --daemon for headless playback from scripts or a desktop widget. Upgrade guide.
Use sandboxed Lua 5.1 plugins. Handle events, add visualizers, and send data. Publish namespaced events with p:publish(). Retained events go to new subscribers, so local companion apps get the current state when they connect. Values convert to JSON up to 64 levels deep. Cyclic references become null.
Press Ctrl+S to save the current track to ~/Music.
Use full, compact, minimal, and simplified layouts in terminal splits and small SSH sessions. At 80x24 and up, the playlist and a Settings pane sit side by side below the seek bar; Ctrl+B closes the pane for a full-width playlist, keeping a source and volume row, and remembers the choice. In full and compact playback, Tab cycles from Playlist through Source, Volume, EQ, Shuffle, Repeat, and Speed, then back; Shift+Tab reverses the order, skipping hidden controls. Simplified mode shows artist and title, plus a time and seek-progress strip. It has no visualizer or playlist. Hide the key-binding hint bar with --no-help-bar, restore it with --help-bar, or toggle it with Ctrl+G, which remembers your choice.
Press Ctrl+I in playback to toggle read-only Metadata below Settings for the highlighted playlist song, podcast episode, or radio stream, not necessarily the item playing. Hidden by default (show_metadata = false), it remembers your choice and uses loaded fields without lookups. From the playlist, lowercase i opens full, scrollable info including Path. Enabling Metadata without room for the sidebar section opens that overlay instead. Ctrl+I needs enhanced keyboard reporting; legacy terminals keep treating it as Tab. Metadata guide.
Press Ctrl+Z to restore the last playlist removal or queue clear.
Use cursor movement, paste, word deletion, and clear-line editing in search, URL, playlist-name, and jump prompts.