cliamp: Why Developers Are Ditching GUI Music Players for This Terminal Beast

cliamp: Why Developers Are Ditching GUI Music Players for This Terminal Beast

Your music player is eating your RAM for breakfast. That shiny Electron app hogging 400MB? The bloated streaming client with its endless animations and telemetry? It's a resource nightmare wrapped in pretty pixels. But what if I told you there's a secret weapon that turns your terminal into a nostalgia-drenched audio powerhouse—complete with a dancing spectrum visualizer, parametric equalizer, and support for everything from Spotify to obscure Chinese streaming services?

Meet cliamp, the terminal music player that makes Winamp look like a fond memory and modern GUI players look like resource-hungry dinosaurs. Built by developer bjarneo and powered by Go's finest TUI frameworks, cliamp isn't just another cmus clone. It's a complete audio ecosystem that runs where developers already live: the command line. Whether you're SSH'd into a headless server, tiling windows in i3, or simply refusing to leave your keyboard, cliamp delivers an experience that's equal parts retro cool and technically impressive. Ready to reclaim your system resources and look like a hacker from a 90s movie while doing it? Let's dive in.

What is cliamp? The Terminal Audio Revolution Explained

cliamp is a terminal-based music player explicitly inspired by the legendary Winamp, reimagined for the modern developer workflow. Created by bjarneo and hosted at github.com/bjarneo/cliamp, this open-source project harnesses Go's ecosystem to deliver something genuinely rare: a text-based user interface (TUI) that doesn't sacrifice visual flair or audio fidelity.

The project sits at the intersection of multiple exploding trends. Terminal productivity tools are experiencing a renaissance—think Lazygit, Btop, and Zellij. Simultaneously, developer disillusionment with Electron-based applications has reached fever pitch. cliamp capitalizes on both movements while adding a crucial ingredient missing from most TUI tools: legitimate audio processing.

Under the hood, cliamp leverages four powerhouse libraries:

• Bubble Tea — The Elm-inspired TUI framework from Charmbracelet that makes complex terminal interfaces feel native
• Lip Gloss — CSS-style styling for terminal applications, enabling that gorgeous Winamp aesthetic
• Beep — Go's premier audio processing library, handling playback, mixing, and effects
• go-librespot — A native Go Spotify client library, no official API required

The result? A player that streams from Spotify, YouTube, YouTube Music, SoundCloud, Bilibili, NetEase Cloud Music, Xiaoyuzhou, Navidrome, Plex, and Jellyfin—plus 30,000+ internet radio stations—while rendering real-time spectrum analysis in your terminal. It's not just trending because it's cool. It's trending because it solves real problems for developers who live in terminal environments.

Key Features: What Makes cliamp Insanely Powerful

cliamp packs features that embarrass players with hundred-person engineering teams. Here's the technical breakdown:

Spectrum Visualizer & Parametric EQ

The headline feature isn't cosmetic—it's computational. cliamp performs real-time Fast Fourier Transform (FFT) analysis on audio output, rendering frequency bands directly in your terminal using Unicode block characters. The parametric equalizer lets you sculpt frequencies with precision, not just crude bass/treble sliders. This is DSP in your terminal, not ASCII art pretending to be functional.

Universal Streaming Support

Through clever abstraction layers, cliamp unifies disparate APIs into a consistent interface. Spotify via go-librespot (no premium API needed). YouTube/YouTube Music via yt-dlp extraction. Chinese platforms like NetEase and Bilibili through reverse-engineered endpoints. Self-hosted Navidrome/Plex/Jellyfin via their respective APIs. Each provider implements the same internal interface, so your playlists mix sources seamlessly.

Advanced Playlist Management

Create, edit, and persist playlists across sessions. The TUI supports vim-style navigation, search, and manipulation. Playlists survive restarts, stored in human-readable TOML format at ~/.config/cliamp/.

Radio Browser Integration

Press R for instant access to 30,000+ verified internet radio stations. The Radio Browser directory is queried live, with search and filtering. Add custom stations via ~/.config/cliamp/radios.toml.

Remote Control & Daemon Mode

Run cliamp headless on a server, control it via IPC from another machine. SSH streaming support means your remote server becomes an audio hub. The quickshell integration even provides desktop widgets for non-terminal control.

Lua Plugin System

Extend functionality without recompiling. The plugin architecture includes community contributions like the Soap Bubbles Visualizer—because why stop at spectrum analysis?

Theme Engine

Full color customization via Lip Gloss. Recreate Winamp's classic skins or forge your own dark-mode masterpiece. Themes are declarative and hot-reloadable.

Use Cases: Where cliamp Absolutely Dominates

1. The Headless Server Audio Hub

Running Plex or Navidrome on a home server? cliamp transforms that same machine into a playback endpoint. SSH in, launch in daemon mode, control remotely. No X11 forwarding, no web interface vulnerabilities—just pure terminal audio.

2. The Minimalist Developer's Daily Driver

You use Neovim, tiling WMs, and refuse to touch a mouse. cliamp fits your workflow like a glove. Same keyboard-driven philosophy, same resource restraint. Your music player finally matches your editor.

3. The Cross-Platform Streaming Unifier

Tired of five apps for five services? cliamp normalizes Spotify, YouTube Music, NetEase, and your local FLAC collection into one searchable, playlistable library. The abstraction layer means you stop thinking about where music lives.

4. The Retro Computing Aesthetician

Let's be honest: spectrum analyzers are cool. The visualizer turns mundane playback into a minor event. Pair with a CRT filter or actual vintage hardware for maximum nostalgia points. It's functional eye candy that impresses coworkers during screen shares.

5. The Bandwidth-Constrained Remote Worker

GUI streaming clients buffer, pre-cache, and sync aggressively. cliamp streams efficiently, works over SSH tunnels, and won't saturate your connection with album art and video thumbnails. Essential for satellite or metered connections.

Step-by-Step Installation & Setup Guide

Getting cliamp running takes under two minutes. Choose your path:

One-Line Install (Recommended)

# Automatic installation—downloads correct binary for your platform
curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh

Homebrew (macOS/Linux)

# Automatically pulls all runtime dependencies
brew install bjarneo/cliamp/cliamp

Arch Linux (AUR)

yay -S cliamp

Pre-Built Binaries

Download directly from GitHub Releases.

Critical macOS Note: Pre-built binaries dynamically link FLAC, Vorbis, and Ogg libraries. Install these first unless using Homebrew:

brew install flac libvorbis libogg

The Homebrew formula handles this automatically.

Linux Advantage: Pre-built binaries statically link these codecs. Zero extra packages needed. You may need an ALSA bridge for PipeWire/PulseAudio—see troubleshooting below.

Optional Runtime Dependencies (All Platforms)

# macOS
brew install ffmpeg yt-dlp

# Linux (Debian/Ubuntu)
sudo apt install ffmpeg yt-dlp

# Linux (Fedora)
sudo dnf install ffmpeg yt-dlp

• ffmpeg — Enables AAC, ALAC, Opus, and WMA playback
• yt-dlp — Powers YouTube, YouTube Music, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music

Build from Source

# Clone repository
git clone https://github.com/bjarneo/cliamp.git && cd cliamp

# Build binary directly
go build -o cliamp .

# Or use Make (installs to ~/.local/bin/)
make && make install

Prerequisites for source builds:

• Go 1.25.5+
• ALSA development headers (Linux only):

# Debian/Ubuntu
sudo apt install libasound2-dev

# Fedora
sudo dnf install alsa-lib-devel libvorbis-devel flac-devel

# Arch
sudo pacman -S alsa-lib

macOS builds use CoreAudio directly—no extra dependencies.

REAL Code Examples: cliamp in Action

Let's examine actual usage patterns from the repository, with detailed technical breakdowns.

Example 1: Basic Playback Commands

# Play entire directory—recursive file discovery with automatic format detection
cliamp ~/Music

# Play specific files with glob expansion—supports MP3, FLAC, OGG, WAV, and more
cliamp *.mp3 *.flac

# Stream from any HTTP/HTTPS URL—handles redirects and chunked transfer
cliamp https://example.com/stream

Technical insight: cliamp's playback engine uses Beep's speaker package for audio output, with automatic format detection via file headers (not extensions). The URL streaming path supports Icecast/Shoutcast metadata injection for track identification. Multiple file arguments create an implicit playlist with gapless playback preparation.

Example 2: Interactive Provider Configuration

# Launch the TUI setup wizard for remote services
cliamp setup

This walks through each supported provider—Spotify, YouTube Music, Navidrome, Plex, Jellyfin, NetEase Cloud Music—prompting for credentials, testing connectivity, and writing validated configuration to ~/.config/cliamp/config.toml.

Sample generated configuration structure:

# ~/.config/cliamp/config.toml
[spotify]
username = "your_username"
# Password stored via system keyring, not plaintext

[navidrome]
server = "https://navidrome.yourdomain.com"
username = "admin"

[youtube_music]
# Uses yt-dlp's authentication cookies or OAuth

The wizard validates each connection before writing, preventing broken configurations. See docs/cli.md for provider-specific authentication flows.

Example 3: Custom Radio Station Configuration

# ~/.config/cliamp/radios.toml
[[stations]]
name = "SomaFM Groove Salad"
url = "https://ice4.somafm.com/groovesalad-128-mp3"
tags = ["ambient", "electronic"]

[[stations]]
name = "Local College Radio"
url = "http://radio.university.edu:8000/stream"

Stations appear in the R radio browser alongside the 30,000+ Radio Browser directory entries. The TOML format supports tagging for personal organization—cliamp doesn't enforce tag schemas, leaving categorization to user preference.

Example 4: Linux Audio Troubleshooting (PipeWire/PulseAudio)

# PipeWire systems need the ALSA compatibility layer
sudo pacman -S pipewire-alsa      # Arch
sudo apt install pipewire-alsa    # Debian/Ubuntu

# Legacy PulseAudio systems
sudo pacman -S pulseaudio-alsa    # Arch

Why this matters: cliamp's Beep backend uses ALSA directly on Linux. Modern distributions default to PipeWire, which provides superior routing but requires this bridge for ALSA-only applications. Without it, playback initializes successfully but produces silence—no error messages, just void. This is the most common support issue, and the fix is a single package installation.

Advanced Usage & Best Practices

Daemon Mode for Server Deployment

Run cliamp headless for remote control scenarios:

# Start headless daemon
cliamp --daemon

# Control from another terminal or machine via IPC
cliamp --remote play
cliamp --remote next
cliamp --remote "playlist add ~/Music/new-album"

See docs/headless.md and docs/remote-control.md for complete IPC protocol documentation.

SSH Streaming Setup

Stream from remote servers without local file access:

# On remote server
cliamp --daemon --bind 0.0.0.0:8080

# Local forwarding through SSH tunnel
ssh -L 8080:localhost:8080 server.example.com

Documented in docs/ssh-streaming.md.

Audio Quality Optimization

# Force specific sample rate for DAC compatibility
cliamp --sample-rate 48000 ~/Music

# Enable exclusive mode (prevents system mixer resampling)
cliamp --exclusive ~/Music

Reference docs/audio-quality.md for bit-perfect playback configurations.

Media Key Integration

# Register as default MPRIS player for desktop environment integration
cliamp --mediactl

Enables system media keys, lock screen widgets, and notification area control. See docs/mediactl.md.

Performance Tip: Pre-generate yt-dlp Cache

For YouTube/NetEase-heavy users, warm the extraction cache:

# Background cache population for frequently accessed playlists
cliamp --cache-warm "https://youtube.com/playlist?list=..."

Eliminates playback startup latency on slow connections.

Comparison with Alternatives

Why cliamp wins: It's the only player combining genuine audio processing (visualizer, EQ), broad streaming support without official API requirements, and deliberate retro design. cmus is efficient but stagnant. Spotify TUI is Spotify-only. MPD ecosystems are powerful but fragmented. cliamp unifies what previously required three separate tools.

FAQ: Your Burning Questions Answered

Does cliamp require Spotify Premium?

No. The go-librespot integration connects as a Spotify Connect device without official API approval. Free-tier limitations (shuffle-only on mobile) don't apply to this playback path.

Can I use cliamp on Windows?

Currently Linux and macOS only. Windows support would require ALSA/CoreAudio abstraction layers not yet implemented. WSL2 works with audio passthrough configured.

How does the visualizer impact CPU usage?

Minimal. FFT analysis uses Go's efficient goroutine scheduling; typical overhead is 2-5% of one core at 60fps rendering. Disable with --no-visualizer if needed.

Is my streaming password secure?

Credentials are stored via your OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). The config.toml never contains plaintext passwords.

Can I import playlists from Spotify/YouTube Music?

Yes. The cliamp setup wizard includes playlist import for configured providers. Local M3U/PLS files are also supported natively.

Why no album art display?

Terminal graphics (sixel, kitty protocol) are on the roadmap. Currently, visualizer bandwidth is prioritized. The quickshell widget provides desktop album art integration.

How do I report bugs or request features?

Open an issue at github.com/bjarneo/cliamp/issues. The project is actively maintained with responsive triage.

Conclusion: Your Terminal Deserves Better Audio

cliamp isn't nostalgia for nostalgia's sake. It's a technically sophisticated audio platform that happens to wear Winamp's aesthetic proudly. The combination of Bubble Tea's fluid TUI, Beep's robust audio pipeline, and go-librespot's unofficial Spotify access creates something genuinely unprecedented: a unified streaming client that respects your system resources, your keyboard-driven workflow, and your desire for visual feedback that doesn't require a GPU.

For developers spending hours in terminal environments, switching contexts to a bloated music application is friction we shouldn't tolerate. cliamp eliminates that friction while adding capabilities—spectrum analysis, parametric EQ, universal streaming—that most GUI players lack entirely.

The installation is one command. The learning curve is minutes. The payoff is a music experience that feels like it was built specifically for how you already work. Stop letting your music player fight your workflow. Embrace the terminal. Embrace the spectrum.

Install cliamp now — your RAM will thank you, and your coworkers will ask how you made your terminal look so cool.