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] [Local] [Navidrome] [Plex] [Jellyfin] [Emby] [Spotify] [YouTube] [YT Music]

▸─ 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 ▶❚❚ * 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

$ 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, Spotify, Qobuz, NetEase, and YouTube Music.

OAuth · cached

Spotify

Stream your Premium library. Bring your own developer client_id for a private quota, or use the built-in shared one. Search & add tracks with F. Currently unavailable on Windows builds.

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.

OAuth · cached

YT Music

Browse your playlists with auto music/non-music classification. Set cookies_from to play through your browser session and avoid YouTube bot blocks (keep yt-dlp current).

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.

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 with presets: Rock, Jazz, Pop, Classical, and more.

◈

Themes & Visualizers

17 built-in themes and multiple visualizer modes. Hot-swap with t / v.

☰

Playlists

TOML playlists, 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), buffer size, resample.

⌀

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.

≡

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.

⎔

Lua Plugins

Lua 5.1 sandboxed plugin system. Hook events, add visualizers, push data.

▣

Save to Disk

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