cliamp.stream

cliamp is a full music player that runs inside your terminal instead of a browser tab or desktop app. It plays local files, podcasts, streaming services (Spotify, Qobuz, Tidal, YouTube Music, SoundCloud, Mixcloud, NetEase, Yandex Music), self-hosted libraries (Plex, Jellyfin, Emby, Navidrome, Lyrion), and roughly 58,000 internet radio stations — all through one playlist, equalizer, visualizer, and lyrics interface. It's MIT licensed, written in Go, and available for Linux, macOS, and Windows, plus an Android mobile app. It fits you if you already work in a terminal and want your music there too, or if you want a single player that unifies streaming services and self-hosted libraries without switching apps.

What you actually get

The core promise is one interface for every source. Instead of separate apps for Spotify, your Jellyfin library, and radio, cliamp routes them all through the same playback pipeline:

• Playlists with shuffle and repeat modes
• 10-band equalizer with presets (the demo shows an "EQ [Rock]" state)
• 31 visualizers
• Synced lyrics
• Podcast feeds
• Remote control and Lua plugins for extending behavior
• Radio catalog browsable by country and genre, with favorites saved locally

The header shows playback state, source, volume, and playlist position, so you can see what's playing at a glance.

How to install it

Installation is one line, and the site offers several package-manager routes:

Windows builds are distributed through Releases. After installing, run cliamp — the cliamp setup flow walks you through connecting streaming services and media servers.

Optional dependencies matter here:

• ffmpeg is needed for AAC, ALAC, Opus, and WMA playback.
• yt-dlp is needed for YouTube, SoundCloud, Mixcloud, Bandcamp, Bilibili, and NetEase.

If a source won't play, check whether the matching optional tool is installed before troubleshooting anything else.

A concrete example: playing a radio station

The site's own demo shows the radio workflow:

$ cliamp --provider radio

Then pick a station from the catalog and press play. You can browse by country or genre, and press f in the Catalog, in search results, or in the playback playlist to favorite a station. Favorites are stored locally under Radio → Favorites by URL, keyed by station name rather than the current song, and station details (including region) survive a restart. If you have a direct stream URL, you can pass it too — the demo uses cliamp https://radio.cliamp.stream/lofi/stream.pls.

A few behaviors worth knowing if you favorite a lot of stations:

• The header's star badge counts all starred rows, including ones scrolled offscreen.
• Playlists with no favorited stations don't reserve a star column.
• M3U/PLS wrappers keep their original station URL after playback resolution.
• Toggling a favorite doesn't interrupt an in-progress station load or fetch more catalog pages.
• On Linux and macOS, favorite changes from multiple cliamp instances are preserved through a shared file lock.

Who it's for — and when to look elsewhere

cliamp makes sense if you're comfortable in a terminal, want streaming services and self-hosted servers under one roof, and value keyboard-driven control over a graphical UI. The plugin system and remote control suggest it's aimed at people who like to tinker.

It's a weaker fit if you want a polished graphical interface, or if you'd rather not manage optional dependencies like ffmpeg and yt-dlp for certain formats and sources. The site doesn't publish pricing details, so check the install and source pages directly if licensing or cost matters to your decision — the project is listed as MIT licensed, but confirm current terms yourself.

To try it, install with one of the commands above, run cliamp setup to connect your sources, and start with a single provider (radio is the lowest-friction entry point) before wiring in streaming accounts.

cliamp treats internet radio as a first-class source: you can browse roughly 58,000 stations by country or genre, press f to favorite the highlighted station, and your favorites persist locally by station URL and name — including region details — across restarts. On Linux and macOS, favorite changes are also shared between running cliamp instances through a file lock, so two terminals won't overwrite each other's edits.

Browsing and playing radio

Radio is one of the providers cliamp ships with, alongside streaming services, self-hosted libraries, local files, and podcasts. The site's own example shows the direct route:

cliamp --provider radio

You can also pass a station playlist URL directly:

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

Inside the app, the Catalog is where you browse stations by country or genre, and search results are another place stations appear. Once you pick a station and press play, it joins the same playback pipeline as everything else — playlist, 10-band EQ, visualizers, and synced lyrics — so radio isn't a separate mode with its own controls.

Favoriting a station

The action is a single key: press f while a station is selected in the Catalog, in search results, or in the playback playlist after browsing countries or genres. The page evidence describes this as "radio favorites follow the station," which matters for a live stream: what gets saved is the station itself, not whatever song happens to be playing at that moment.

A few behaviors worth knowing before you rely on it:

• Saved by URL and name. Favorites live locally under Radio → Favorites, keyed by the station URL and labeled with the station name. Region and other station details are retained after a restart.
• M3U/PLS wrappers keep the original station URL after playback resolution, so favoriting a wrapped stream doesn't save a temporary resolved link.
• Toggling is non-destructive. Turning a favorite on or off preserves your selected station and any catalog pages you've already loaded, including while a page is still loading.
• Favoriting doesn't trigger extra work. It won't fetch more catalog stations or interrupt a station load in progress.

The star badge and what it counts

The header's star badge counts all starred rows, including rows currently offscreen — so the number reflects your full set of favorites, not just what's visible in the current view. It uses the same meaning as the row markers next to individual stations.

One layout detail: radio favorites don't reserve a star column in playlists that contain no favorited stations, so a playlist with no favorites won't show an empty column.

Multiple instances and sync behavior

On Linux and macOS, favorite mutations preserve other cliamp instances' changes through a shared file lock. In practice, if you have cliamp open in two terminals and star a station in one, the other instance's write won't clobber it.

If you're scripting against cliamp rather than using the TUI, note the documented constraint: IPC clients use the stable URL-based favorite IDs returned by provider.playlists; positional favorite IDs are not supported. Build your integration around the URL ID, not the row position.

Practical checklist

If a station won't play, the likely gap is a missing optional dependency rather than a favorites problem: the install notes list ffmpeg for AAC, ALAC, Opus, and WMA, and yt-dlp for sources like YouTube, SoundCloud, Mixcloud, Bandcamp, Bilibili, and NetEase. Install cliamp itself with the one-line script (curl -fsSL https://cliamp.stream/install.sh | sh), Homebrew, AUR, Nix, or go install; Windows builds are in Releases.

Install cliamp with the one-line script on Linux/macOS (curl -fsSL https://cliamp.stream/install.sh | sh), or use Homebrew, AUR, Nix, or Go. Windows users get builds from Releases. After installing, run cliamp setup to connect streaming services and media servers, and add ffmpeg and yt-dlp if you need the extra codecs and sources they unlock.

Install cliamp

Pick the method that matches your system. Each command below is the one published on cliamp.stream.

The site describes the install as "one line," and the script route is the shortest path on Linux and macOS. If you already manage packages with Homebrew, AUR, or Nix, use that instead so upgrades stay in your normal workflow. The Go route builds from source via the module path.

Expected result: the cliamp binary is on your PATH. Verify by running cliamp — the player should start in your terminal.

Run first-time setup

After install, run:

cliamp setup

The setup walkthrough guides you through configuring streaming services and media servers. This is where you connect the sources you actually use — for example Spotify, Qobuz, Tidal, YouTube Music, Plex, Jellyfin, Emby, Navidrome, Lyrion, or Yandex Music — rather than configuring everything at once.

What to expect: setup is interactive, so have your account details or server addresses ready for the services you plan to use. Sources you skip can be added later; setup is not a one-shot gate.

Add optional dependencies

Two external tools extend what cliamp can play. They are optional — install them only if you need the formats or sources they cover.

ffmpeg — extra audio codecs

Install ffmpeg if you play AAC, ALAC, Opus, or WMA files. Without it, those codecs are the gap; the rest of the player works normally.

yt-dlp — additional streaming sources

Install yt-dlp for YouTube, SoundCloud, Mixcloud, Bandcamp, Bilibili, and NetEase. If your library is local files plus a self-hosted server, you can skip this.

A quick check after installing either tool: start cliamp and play a file or source in the relevant format. If playback starts, the dependency is wired up correctly.

Try a first stream

Once setup is done, you can confirm everything works with a radio stream, which needs no account:

cliamp --provider radio

The site's own example uses a station playlist URL:

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

Expected result: the terminal UI opens with a playlist, transport controls, EQ, and volume indicators, and the stream begins playing. From there, browse stations by country or genre in the Catalog and press f to favorite one — favorites are saved locally by station URL and keep the station name and region after a restart.

Common snags

• Command not found after install: the binary's directory isn't on your PATH. With the Go route, that's usually $(go env GOPATH)/bin; with Homebrew or AUR, reopen your shell.
• A file won't play: check whether it's AAC, ALAC, Opus, or WMA and install ffmpeg if so.
• YouTube or SoundCloud fails: yt-dlp is missing or outdated — update it first.
• A streaming service isn't listed: rerun cliamp setup and add it there rather than expecting it to appear automatically.
• Windows: there is no script or package-manager line on the site; use the Releases page.

What you get once it's running

All sources — streaming services, self-hosted libraries, local files, podcasts, and roughly 58,000 radio stations — run through the same playlist, 10-band equalizer, 31 visualizers, synced lyrics, and Lua plugin pipeline. That single-interface design is the reason setup matters: connect your sources once, and the rest of the player behaves the same regardless of where the audio comes from.

cliamp connects to streaming services (Spotify, Qobuz, Tidal, YouTube Music, SoundCloud, Mixcloud, NetEase, Yandex Music), self-hosted media servers (Plex, Jellyfin, Emby, Navidrome, Lyrion), local audio files, podcast feeds, and roughly 58,000 internet radio stations. Every source feeds the same playlist, 10-band equalizer, visualizer, and synced-lyrics pipeline, so you don't learn a different interface per service. It runs on Linux, macOS, and Windows, with an Android build linked from the site, and is MIT licensed.

Streaming services

The site also names Bandcamp and Bilibili as sources that rely on yt-dlp. Running cliamp setup walks you through connecting streaming services and media servers, so credentials are handled there rather than through flags you have to memorize.

Self-hosted libraries

If you already run a media server, cliamp can act as a terminal front end for it:

• Plex
• Jellyfin
• Emby
• Navidrome
• Lyrion

These are listed alongside the streaming services as first-class sources, meaning your own library gets the same playlist, EQ, and lyrics treatment as a commercial service.

Local files, podcasts, and radio

• Local files: point cliamp at your own audio. The site notes that AAC, ALAC, Opus, and WMA playback requires ffmpeg installed.
• Podcasts: podcast feeds are supported directly, so episodes sit in the same queue as music.
• Internet radio: about 58,000 stations, browsable by country or genre. You can also pass a stream URL directly, e.g. cliamp https://radio.cliamp.stream/lofi/stream.pls, or launch straight into radio with cliamp --provider radio.

How radio favorites behave

Radio favorites are saved locally under Radio → Favorites, keyed by station URL and stored under the station name rather than the currently playing song. Station details, including region, survive a restart. Press f in the Catalog, in search results, or in the playback playlist to favorite a station. A few details worth knowing before you rely on them:

• The header's star badge counts all starred rows, including ones scrolled offscreen.
• Playlists with no favorited stations don't reserve a star column.
• M3U/PLS wrappers keep their original station URL after playback resolution.
• Toggling a favorite preserves your selected station and loaded catalog pages, even mid-load, and doesn't trigger extra catalog fetches.
• On Linux and macOS, a shared file lock keeps favorite changes from multiple cliamp instances from clobbering each other.

What stays consistent across sources

The point of supporting this many sources is that the surrounding player doesn't change: one playlist model, a 10-band equalizer, 31 visualizers, synced lyrics, remote control, and Lua plugins. The site's own framing is "every source, one interface" — switching from a Tidal album to a Jellyfin track to a radio station doesn't change how you shuffle, EQ, or read lyrics.

Choosing based on your setup

• You pay for a streaming service: connect it through cliamp setup and keep your existing library and playlists.
• You self-host: Plex, Jellyfin, Emby, Navidrome, or Lyrion covers most home-server setups; pick whichever you already run.
• You want zero accounts: local files plus the ~58,000-station radio catalog work without a streaming subscription.
• You listen to YouTube-adjacent sources: install yt-dlp first, or YouTube Music, SoundCloud, Mixcloud, Bandcamp, Bilibili, and NetEase won't play.
• You have lossless or niche codecs locally: install ffmpeg for AAC, ALAC, Opus, and WMA.

Install and verify

One-line install on Linux/macOS:

curl -fsSL https://cliamp.stream/install.sh | sh

Alternatives listed on the site: brew install bjarneo/cliamp/cliamp (Homebrew), yay -S cliamp (AUR), nix run github:bjarneo/cliamp, or go install github.com/bjarneo/cliamp@latest. Windows builds are in Releases.

After installing, run cliamp and let cliamp setup configure your services. To confirm a source works, start playback from it and check that the header shows the expected source (e.g. SRC [Radio]) and that the EQ and lyrics panels respond — if a yt-dlp-backed source fails, the missing dependency is the usual cause.