cliamp

cliamp: A Retro Terminal Music Player for Modern Audiences

Image: cliamp banner or asset

Step into a world where a nix-terminal aesthetic meets modern music streaming magic. cliamp is a retro-inspired terminal music player that channels the spirit of Winamp while delivering a contemporary feature set that would make even the most enthusiastic streamaholic smile. It’s built to play local files, streams, podcasts, and a broad slate of online services—from classic sources to modern giants—through a clean, responsive interface that thrives in terminal environments. Its nucleus is a spectrum visualizer that dances in tandem with a responsive parametric equalizer, all wrapped in hands-on playlist management. If you crave a nostalgic UI with real-world connectivity, cliamp is designed to deliver.

What makes cliamp stand out

• Retro aesthetic, modern capabilities: A terminal-first player with a visualizer and EQ, yet capable of handling everything from local playlists to online services.
• Wide service integration: Play from local files, streams, and podcasts, plus YouTube, YouTube Music, SoundCloud, Bilibili, Spotify, NetEase Cloud Music, Xiaoyuzhou (小宇宙), Navidrome, Plex, Jellyfin, and more via remote providers.
• Rich playback features: Spectrum visualizer for live feedback, a powerful parametric EQ to sculpt sound, and robust playlist management to curate listening sessions.
• Modular, extensible architecture: Built with a modern stack but designed to feel like a fixed-in-time retro player, ensuring reliability and a pleasant learning curve.
• Open, transparent setup: Clear installation paths for macOS, Linux, and Arch, alongside options to build from source, all with sensible dependencies and helpful troubleshooting notes.

A quick tour of the platform and its core pieces

cliamp is constructed with a trio of modern, Go-based libraries and backends that blend old-school vibes with contemporary performance:

• Bubble Tea: The core terminal UI framework that provides a responsive, event-driven interface, enabling keyboard-driven navigation, smooth transitions, and clean state management.
• Lip Gloss: A styling layer that brings a polished, consistent look to terminal elements, ensuring that colors, borders, and typography feel cohesive and legible.
• Beep: A robust audio playback component that handles the diverse array of sources cliamp supports, including local files, streams, and remote services.
• go-librespot: An integration layer that enables streaming from Spotify, bridging the gap between the terminal client and Spotify’s streaming capabilities.

From the project’s own words, cliamp can act as a hub for your listening life—pulling from local storage, remote servers, and widely used streaming platforms—while preserving a distinctive, nostalgic user experience.

Install and get started

cliamp ships with multiple installation paths designed to fit typical user environments. The project emphasizes straightforward setup, minimal friction, and a safe path to exploring all features.

Install options

• curl-based installer: curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh
• Homebrew (macOS): brew install bjarneo/cliamp/cliamp
• Note: Homebrew will pull in all required runtime libraries automatically.
• Arch Linux (AUR): yay -S cliamp
• Pre-built binaries: Download from GitHub Releases
• macOS: binaries dynamically link against FLAC, Vorbis, and Ogg via Homebrew. If downloaded directly, you should first install dependencies:
  • brew install flac libvorbis libogg
• Linux: pre-built binaries statically link FLAC, Vorbis, and Ogg, so no extra codec packages are required. You may still need an ALSA bridge for your sound server.
• Optional runtime dependencies (across platforms)
• ffmpeg — for AAC, ALAC, Opus, and WMA playback
• yt-dlp — for YouTube, YouTube Music, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music
• macOS note: brew install ffmpeg yt-dlp
• Linux note: use your distribution’s package manager for these tools

Build from source (for the adventurous)

• Prerequisites:
• Go (1.25.5 or later)
• ALSA development headers (Linux only)
• Linux setup notes:
• 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 uses CoreAudio; no extra dependencies required
• Build steps:
• git clone https://github.com/bjarneo/cliamp.git
• cd cliamp
• make && make install
• Or without Make: go build -o cliamp .
• make install places the binary in ~/.local/bin/
• Optional runtime dependencies (repeat as needed):
• ffmpeg
• yt-dlp

Quick start commands

• Play a directory: cliamp ~/Music
• Play specific files: cliamp *.mp3 *.flac
• Play a URL: cliamp https://example.com/stream
• Discover keybindings: Press Ctrl+K to see all keybindings

Configuring remote providers (wizard-based)

cliamp includes a guided wizard to configure remote providers such as Navidrome, Plex, Jellyfin, Spotify, YouTube Music, NetEase Cloud Music, and more:

• Command: cliamp setup
• What it does: Walks through each provider, validates the connection, and writes the correct blocks to ~/.config/cliamp/config.toml
• Documentation: See docs/cli.md#setup-wizard for details

Radio and live stations

One of cliamp’s most distinctive features is its radio experience. By pressing R in the player, you can browse and search through more than 30,000 online radio stations sourced from the Radio Browser directory. It’s a living, breathing catalog of stations across genres and regions, ready to be added to your personal listening roster.

• Access and search experiences:
• Browse stations by genre, language, popularity, and country
• Save favorites and add them to your playlists
• Custom stations:
• You can add your own stations by editing ~/.config/cliamp/radios.toml
• Hosting your own radio:
• cliamp-server provides a way to host your own radio streams for consumption by cliamp
• Documentation:
• See docs/configuration.md#custom-radio-stations

Remote ecosystem and integrations

cliamp’s design acknowledges the reality of today’s music ecosystems. It is designed to connect to multiple services through a modular approach, enabling you to unify your listening experience in one place.

• Navidrome: A self-hosted music server that can plug into cliamp via a guided setup
• Plex: Integration to access your Plex library and playlists
• Jellyfin: Similar integration path to Plex for library access
• Spotify: Streaming via librespot-based integration
• YouTube Music, YouTube, SoundCloud, Bandcamp, Bilibili, NetEase Cloud Music: Access through yt-dlp-based workflows and dedicated streaming paths
• Xiaoyuzhou (小宇宙): Access to a popular indie podcast and audio storytelling space (where available)
• Media servers and catalogs:
• Plex, Jellyfin, Navidrome
• Remote control via IPC and SSH streaming options

Documentation ecosystem

cliamp ships with a broad set of documentation to help users explore every feature, tweak settings, and troubleshoot issues. The docs cover:

• Configuration
• Keybindings
• CLI flags
• Streaming
• Playlists
• YouTube, SoundCloud, Bandcamp, Bilibili
• YouTube Music
• NetEase Cloud Music
• SoundCloud
• Lyrics
• Spotify
• Navidrome
• Plex
• Jellyfin
• Themes
• SSH Streaming
• Remote Control (IPC)
• Headless Daemon Mode
• Audio Quality
• Media Controls
• Quickshell Now-Playing Widget (Omarchy)
• Lua Plugins and Community Plugins
• Soap Bubbles Visualizer plugin

Troubleshooting and common gotchas

No audio output can be caused by audio backend mismatches on Linux, especially when using PipeWire or PulseAudio. cliamp’s ALSA backend may need a bridge package to route audio through your sound server:

• PipeWire: install pipewire-alsa
• PulseAudio: install pulseaudio-alsa
• Debian/Ubuntu (PipeWire): sudo apt install pipewire-alsa
• Arch users: sudo pacman -S pipewire-alsa or pulseaudio-alsa depending on your setup

A note on dependencies and portability

• Linux builds may link to system libraries; where possible, pre-built binaries ship with static linking for core codecs to minimize external dependencies.
• macOS users should be mindful of library dependencies when downloading from Releases; Homebrew can simplify installation and ensure the required codecs are present.
• If you encounter library not loaded errors, verify that the corresponding libraries (flac, libvorbis, libogg) are installed and discoverable by your runtime linker.

A nostalgic but practical interface

cliamp’s visual design embraces the retro terminal vibe while delivering a polished, modern experience. Expect:

• A spectrum visualizer that responds to the music's dynamics
• A parametric EQ to shape tone and balance
• Intuitive playlist management that makes it easy to curate and reorder tracks
• Clear, keyboard-centric navigation that honors the era of command-line artistry
• A consistent, readable UI with tasteful color and border usage

Developer notes and project philosophy

cliamp is a confluence of open-source strategies and a celebration of minimalism in music playback. The project prioritizes:

• Modularity: Clear boundaries between UI, playback, and integrations to simplify maintenance and extension
• Accessibility: Keyboard-first controls and a straightforward configuration flow
• Extensibility: A robust plugin ecosystem (Lua plugins and community plugins) to enable feature expansion without destabilizing core
• Community: Documentation, tutorials, and a pathway to contribute through open issues and pull requests
• Documentation quality: A broad collection of docs that guide users from quick setup to advanced usage and troubleshooting

A practical, user-centric workflow

• Start small: Install cliamp with the method that suits your system
• Play local content first: Test with a directory and a handful of files to understand the UI and workflow
• Explore remote providers: Use the setup wizard to connect to Navidrome, Jellyfin, Plex, Spotify, or YouTube Music
• Branch into radio: Press R, browse Radio Browser, and curate a personal radio station slate
• Fine-tune audio: Adjust the parametric EQ and watch the spectrum respond to different tracks
• Expand gradually: Install optional dependencies like ffmpeg and yt-dlp to unlock more sources
• Tinker with configuration: Edit ~/.config/cliamp/config.toml to tailor behavior and providers
• Keep your play queue portable: Save and load playlists, then migrate between machines if desired

What to expect from usage

• Reliability: A compact yet capable backend designed to stay responsive even with multiple sources
• Rich media support: Local playback plus diverse streaming and podcast options
• Personalization: Playlists, radios, and remote provider blocks written to your config
• Extendability: A plugin and Lua ecosystem to tailor cliamp to your exact listening preferences

A closing thought

cliamp is more than a tool; it’s a compact, expressive media player that honors the retro terminal spirit while embracing the connected world of today. It’s built to be approachable for newcomers while offering depth for power users who want to blend nostalgia with modern convenience. If you crave a focused, keyboard-driven music experience that can manage local files, streams, podcasts, and a wide array of services—and you also want a lively, responsive visual experience—cliamp is ready to be your next everyday companion.

Appendix: quick references and commands

• Install (macOS, Linux): see the installation section above
• Quick start: cliamp ~/Music
• Play specific files: cliamp *.mp3 *.flac
• Play a URL: cliamp https://example.com/stream
• Quick setup wizard: cliamp setup
• Radio mode: Press R in the player
• Custom radios: ~/.config/cliamp/radios.toml
• Documentation: docs/ (various topics)
• Troubleshooting: See the no audio output guidance and ALSA bridge notes

Author and disclaimer

cliamp is authored by x.com/iamdothash. As with any software, use it at your own risk and be mindful of licensing and terms for streaming services.

Notes on visuals and media

• The included image (referenced above) illustrates cliamp’s retro aesthetic and visual emphasis, pairing the classic terminal vibe with a modern, feature-rich interface.

In closing, cliamp invites you to a listening experience that respects the past while delivering the flexibility and breadth required by today’s music lovers. It’s a thoughtfully engineered bridge between nostalgia and modern streaming, with a focus on clarity, accessibility, and a satisfying, visually engaging user experience.