Terminal music player

cliamp

Winamp for your shell.

Playlists, a 10-band EQ, visualizers, synced lyrics, remote control, and a Lua plugin system — streaming from Spotify, Qobuz, YouTube Music, Plex, Jellyfin, Emby, Navidrome, and 30,000+ radio stations.

Install→ Source↗

$ 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 [Radio] 1/9

▸─ Playlist ── [Shuffle] [Repeat: Off] [1/11] ──

▶ 1. Lofi Hip Hop Radio

▶ 2. EDM Pulse

▶ 3. Synthwave Nights

▶ 4. NCS Radio

▶ 5. NCS House

▶ 6. NCS Dubstep

▶ 7. NCS Drum & Bass

▶ 8. NCS Trap

▶ 9. NCS Phonk

▶10. NCS Pop

▶11. NCS Chill

↑↓ Scroll Enter Play Spc ▶❚❚ f Fav Tab Focus ? Keys

SPD [1x] ↓ 0.7 MB 32 KB/s

Click a station above to tune in live — right here in your browser.

$ cliamp https://radio.cliamp.stream/lofi/stream.pls

02install.sh

Direct

$ curl -fsSL …/install.sh | sh COPIED

Homebrew

$ brew install bjarneo/cliamp/cliamp COPIED

Arch (AUR)

$ yay -S cliamp COPIED

Nix

$ nix run github:bjarneo/cliamp COPIED

$ go install github.com/bjarneo/cliamp@latest COPIED

Or build from source — see the README. Windows builds are available from Releases; when HOME is unset, config lives under %APPDATA%\cliamp.

Next step · configure providers

Run the setup wizard

An interactive TUI walks you through Navidrome, Plex, Jellyfin, Emby, Spotify, Qobuz, NetEase, and YouTube Music. It links to each provider's credential page, validates the connection, and writes the right block to your config file.

Setup

$ cliamp setup COPIED

03sources

Stream from everywhere. Every provider runs through the same playlist, EQ, visualizer, and lyrics pipeline — your config follows you across services. Run cliamp setup for an interactive wizard that walks you through Navidrome, Plex, Jellyfin, Emby, Audiobookshelf, Spotify, Qobuz, NetEase, and YouTube Music.

OAuth · cached

Spotify

Stream your Premium library. Bring your own developer client_id for a private Web API quota; playback is authorized separately. Search with Ctrl+F; Development Mode paging is automatic. Pre-built Windows releases include Spotify support.

OAuth · lossless

Qobuz

Opt-in: set [qobuz] enabled = true. Stream lossless FLAC up to 24-bit/192kHz from your subscription. Browse favorites & playlists, search with Ctrl+F. Sign in once via OAuth in your browser.

yt-dlp

YouTube

Search videos with Ctrl+F, then play, append, or queue from a results list.

Cookies · OAuth

YT Music

Browse your playlists and Liked Music directly via browser cookies (zero OAuth setup) or custom Google Cloud credentials. Set cookies_from in your config.

Media server

Plex

Browse albums and stream from your Plex Media Server.

Media server

Jellyfin

Artists, albums, tracks — buffered gapless playback.

Media server

Emby

Browse your Emby music library with API key or username/password auth.

Subsonic API

Navidrome

Browse your self-hosted library with synced lyrics.

Media server

Audiobookshelf

Audiobooks and podcasts from your own server, with synced listening position and resume.

Provider · yt-dlp

SoundCloud

Opt-in: set [soundcloud] enabled = true. Search with Ctrl+F, browse curated genre playlists, or add user for your profile. cookies_from unlocks Go+ tracks via your browser session.

Provider · yt-dlp

NetEase

Opt-in: run cliamp setup after signing in at music.163.com, then choose your browser. Browse liked songs, account playlists, saved playlists, and charts with browser-cookie playback.

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.

NetEase Cloud Music

Browser-session setup

Sign in at music.163.com, then run cliamp setup. Choose NetEase Cloud Music, pick the browser you used, and the wizard validates the session before writing 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 with the same browser cookie source.

04features

≡

10-Band Equalizer

Parametric EQ presets plus a persistent Custom curve that survives preset changes and restarts.

◈

Themes & Visualizers

21 contrast-checked built-in themes and spectrum, waveform, particle, and true-stereo modes. Stereo provides dedicated L/R horizontal LED peak meters. Hot-swap with t / v.

☰

Playlists

TOML playlists with dynamic directory sources (--dir), M3U/M3U8/PLS import/export, duplicate-safe writes, and TUI/CLI sort tools.

⟲

Recently Played

Auto-recorded listening history. Browse it as a virtual playlist or run cliamp history from the shell.

→

HTTP Streaming

Play from URLs, internet radio, remote M3U playlists, and HLS (.m3u8) live streams via ffmpeg.

♪

Synced Lyrics

Embedded local lyrics first, then LRCLIB/NetEase fallback. Auto-scrolling for timestamped lyrics.

⇄

Gapless Playback

Seamless transitions with preloaded next-track buffering.

♬

MPRIS / Media Keys

Desktop integration. Hardware media keys, playerctl, and embedded local cover art.

▮

Quickshell Widget (Omarchy)

Drop-in Quickshell now-playing card with a Winamp 2-style spectrum, tracking your active Omarchy theme. Setup.

⚙

Audio Quality

Configurable sample rate (22kHz-192kHz), up to 5 seconds of buffering, and resampling.

⌀

Live Radio Metadata

ICY/Shoutcast metadata for the current song on internet radio, plus API-based now-playing for FIP and NTS.

✎

Embedded Tag Reading

ID3v2, Vorbis comments, MP4 atoms - artist, album, genre, year, lyrics, cover art.

▶

CLI Flags

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

⇥

Shell Completion

Generate completion scripts for Bash, Zsh, Fish, and PowerShell.

≡

Diagnostic Logging

File logs at ~/.config/cliamp/cliamp.log. Set log_level in config or --log-level on the CLI: debug, info, warn, error.

↑

Self-Update

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

Env-Interpolated Secrets

Reference any string in config.toml from the environment with ${VAR} or $VAR. Keep passwords and tokens out of the file.

⌁

Remote Control

Control a running instance from another terminal via local-socket IPC. Run with --daemon for headless playback driven entirely by scripts or Waybar. Subscribe to plugin events on the same socket for a push NDJSON stream instead of polling.

⎔

Lua Plugins

Lua 5.1 sandboxed plugin system. Hook events, add visualizers, push data. Publish namespaced events with p:publish(); retained events replay to new subscribers, so local companion apps get current state the moment they connect. Values convert to JSON up to 64 levels deep, and cyclic references become null.

▣

Save to Disk

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

↔

Responsive TUI

Full, compact, and minimal layouts keep playback usable in terminal splits and small SSH sessions.

⟲

Undo Queue Edits

Restore the last playlist removal or queue clear with Ctrl+Z.

⌨

Consistent Keyboard Input

Search, URLs, playlist names, and jump prompts support cursor movement, paste, word deletion, and clear-line editing.