Terminal music player

NERDWORKScliamp

Winamp for your shell.

Play music straight from a terminal window. 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 --playlist mixtape.m3u tty1
C L I A M P[Playlist]
♫Midnight City — M83
01:24 / 04:03 ● Playing 

            

              ━━━━━━━━━━━━━━━━━━━━
              SEEK
              ━━━━━━━━━━━━━━━━━━━━
            

            

            

              
                EQ
                [Rock]
                +5 +4 +2 -1 -2 +2 +4 +5 +5 +5
              
              
                VOL
                
                -6dB
              
            

            

              SRC
              [Local Files]
              3/12
            

            

            

              ▸− Playlist −
              [Shuffle]
              [Repeat: Off]
              [3/12]
              ——
            

            
▶ 1. Nightcall — Kavinsky

            
▶ 2. Technolover — Carpenter Brut

            
▶ 3. Midnight City — M83

            
▶ 4. Resonance — Home

            
▶ 5. Space Song — FM-84

            

            

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

            

              SPD [1x]
              FLAC · 24-bit/96kHz · 2.7 MB/s
            

          

        

        
One command and the music starts — no browser tab required.

        
$ cliamp ~/Music/playlists/mixtape.m3u

      

    

  










  

    

      01install.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

        $ 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
      

    

  







  

    

      02sources
      
    

    

      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.

      
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.

      
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.

      
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, and charts.

      
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.

    

  







  

    

      03features
      
    

    

      
≡
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) streams, with decoded-audio jitter buffering for live radio.

      
♪
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.

      
⚙
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 cliamp upgrade for stable releases, or cliamp upgrade --prerelease to test betas.

      
$
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 or build a GUI with local-socket IPC. Run with --daemon for headless playback driven by scripts or a desktop widget.

      
⌜
Lua Plugins
Lua 5.1 sandboxed plugin system. Hook events, add visualizers, push data. Publish namespaced events with p:publish().

      
▣
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.