cliamp

command module

v1.60.0 Latest Latest Go to latest Published: Jul 16, 2026 License: MIT Imports: 43 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

Links

README ¶

A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Bilibili, Spotify, NetEase Cloud Music, Xiaoyuzhou (小宇宙), Navidrome, Plex, and Jellyfin with a spectrum visualizer, parametric EQ, and playlist management.

cliamp.stream

Built with Bubbletea, Lip Gloss, Beep, and go-librespot.

https://github.com/user-attachments/assets/fbc33d20-e3ac-4a62-a991-8a2f0243c8ea

Install

curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh

Homebrew

brew install bjarneo/cliamp/cliamp

The formula pulls in all required runtime libraries automatically.

Arch Linux (AUR)

yay -S cliamp

Go

go install github.com/bjarneo/cliamp@latest

Linux builds need ALSA development headers installed first. See Building from source.

Pre-built binaries

Download from GitHub Releases.

macOS: the pre-built binaries dynamically link against FLAC, Vorbis, and Ogg from Homebrew. If you download directly from Releases (or use the install.sh script) you must install them first, otherwise you will see errors like Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib:
brew install flac libvorbis libogg
Installing via brew install bjarneo/cliamp/cliamp does this for you.

Linux: the 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 — see Troubleshooting.

Windows: download cliamp-windows-amd64.exe from Releases. If HOME is not set, cliamp stores its config under %APPDATA%\cliamp. The Spotify provider is currently unavailable on Windows builds.

Optional runtime dependencies (all platforms, all install methods):

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

On macOS: brew install ffmpeg yt-dlp. On Linux, use your distribution's package manager.

On Windows, install ffmpeg and yt-dlp with your preferred package manager and keep both on PATH.

Build from source

git clone https://github.com/bjarneo/cliamp.git && cd cliamp && go build -o cliamp .

Quick Start

cliamp ~/Music                     # play a directory
cliamp *.mp3 *.flac               # play files
cliamp https://example.com/stream  # play a URL

Press Ctrl+K to see all keybindings.

Configure remote providers (Navidrome, Plex, Jellyfin, Spotify, YouTube Music, NetEase Cloud Music) with the interactive wizard:

cliamp setup

It walks you through each provider, validates the connection, and writes the right block to your config file (~/.config/cliamp/config.toml, or %APPDATA%\cliamp\config.toml on Windows when HOME is unset). See docs/cli.md for details.

Radio

Press R in the player to browse and search 30,000+ online radio stations from the Radio Browser directory.

Add your own stations to ~/.config/cliamp/radios.toml (or %APPDATA%\cliamp\radios.toml on Windows when HOME is unset). See docs/configuration.md.

Want to host your own radio? Check out cliamp-server.

Building from source

Prerequisites:

Go 1.25.5 or later
ALSA development headers (Linux only — required by the audio backend)

Linux (Debian/Ubuntu):

sudo apt install libasound2-dev

Linux (Fedora):

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

Linux (Arch):

sudo pacman -S alsa-lib

macOS: No extra dependencies — CoreAudio is used.

Windows: No extra SDKs required for the core player. ffmpeg.exe and yt-dlp.exe remain optional runtime dependencies for the same formats/providers as on other platforms. Spotify is not available on Windows builds.

Clone and build:

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:

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

Docs

Troubleshooting

No audio output (silence with no errors)

On Linux systems using PipeWire or PulseAudio, cliamp's ALSA backend needs a bridge package to route audio through your sound server:

PipeWire: pipewire-alsa
PulseAudio: pulseaudio-alsa

Install the appropriate package for your system:

# PipeWire (Arch)
sudo pacman -S pipewire-alsa

# PulseAudio (Arch)
sudo pacman -S pulseaudio-alsa

# Debian/Ubuntu (PipeWire)
sudo apt install pipewire-alsa

Author

x.com/iamdothash

Disclaimer

Use this software at your own risk. We are not responsible for any damages or issues that may arise from using this software.

Documentation ¶

Rendered for

There is no documentation for this package.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
applog Package applog provides logging for cliamp.	Package applog provides logging for cliamp.
cmd Package cmd implements CLI subcommands for cliamp.	Package cmd implements CLI subcommands for cliamp.
config Package config handles loading user configuration from ~/.config/cliamp/config.toml.	Package config handles loading user configuration from ~/.config/cliamp/config.toml.
external
emby Package emby adapts the shared Emby/Jellyfin client (internal/embyapi) to an Emby server and exposes it as a playlist provider.	Package emby adapts the shared Emby/Jellyfin client (internal/embyapi) to an Emby server and exposes it as a playlist provider.
jellyfin Package jellyfin adapts the shared Emby/Jellyfin client (internal/embyapi) to a Jellyfin server and exposes it as a playlist provider.	Package jellyfin adapts the shared Emby/Jellyfin client (internal/embyapi) to a Jellyfin server and exposes it as a playlist provider.
local Package local implements a playlist.Provider backed by TOML files in ~/.config/cliamp/playlists/.	Package local implements a playlist.Provider backed by TOML files in ~/.config/cliamp/playlists/.
navidrome
netease Package netease implements a playlist.Provider for NetEase Cloud Music.	Package netease implements a playlist.Provider for NetEase Cloud Music.
plex Package plex implements a playlist.Provider for Plex Media Server.	Package plex implements a playlist.Provider for Plex Media Server.
qobuz Package qobuz implements a cliamp music provider for Qobuz.	Package qobuz implements a cliamp music provider for Qobuz.
radio catalog.go provides a client for the Radio Browser API (radio-browser.info), a free community-maintained directory of internet radio stations.	catalog.go provides a client for the Radio Browser API (radio-browser.info), a free community-maintained directory of internet radio stations.
radiometa Package radiometa pulls now-playing metadata for radio stations that do not carry inline ICY StreamTitle metadata and instead publish the current track (or show) via a separate JSON API.	Package radiometa pulls now-playing metadata for radio stations that do not carry inline ICY StreamTitle metadata and instead publish the current track (or show) via a separate JSON API.
soundcloud Package soundcloud implements a playlist.Provider backed by yt-dlp.	Package soundcloud implements a playlist.Provider backed by yt-dlp.
spotify Package spotify integrates Spotify playback into cliamp via go-librespot.	Package spotify integrates Spotify playback into cliamp via go-librespot.
ytmusic
history Package history persists the user's recently played tracks to a TOML file in the cliamp config directory.	Package history persists the user's recently played tracks to a TOML file in the cliamp config directory.
internal
appdir
appmeta
browser
embyapi Package embyapi implements the shared Emby/Jellyfin HTTP client.	Package embyapi implements the shared Emby/Jellyfin HTTP client.
fileutil Package fileutil provides file operation utilities.	Package fileutil provides file operation utilities.
fuzzy Package fuzzy provides lightweight case-insensitive fuzzy subsequence matching with relevance scoring.	Package fuzzy provides lightweight case-insensitive fuzzy subsequence matching with relevance scoring.
httpclient Package httpclient provides a shared HTTP client configured for audio streaming.	Package httpclient provides a shared HTTP client configured for audio streaming.
netdiag Package netdiag decorates network errors with platform-specific hints.	Package netdiag decorates network errors with platform-specific hints.
playback
plugintrust Package plugintrust persists approvals for Lua plugin content.	Package plugintrust persists approvals for Lua plugin content.
resume Package resume persists the last-played track and position so playback can be resumed on the next launch.	Package resume persists the last-played track and position so playback can be resumed on the next launch.
sshurl Package sshurl parses ssh:// URLs into components for use with the ssh binary.	Package sshurl parses ssh:// URLs into components for use with the ssh binary.
tomlutil Package tomlutil provides shared helpers for minimal TOML parsing used by the local and radio providers.	Package tomlutil provides shared helpers for minimal TOML parsing used by the local and radio providers.
ipc Package ipc provides Unix socket IPC for remote playback control of cliamp.	Package ipc provides Unix socket IPC for remote playback control of cliamp.
luaplugin Package luaplugin provides a Lua 5.1 scripting engine for cliamp plugins.	Package luaplugin provides a Lua 5.1 scripting engine for cliamp plugins.
lyrics
mediactl
player Package player provides the audio engine for MP3 playback with a 10-band parametric EQ, volume control, and sample capture for visualization.	Package player provides the audio engine for MP3 playback with a 10-band parametric EQ, volume control, and sample capture for visualization.
playlist Package playlist manages an ordered track list with shuffle and repeat support.	Package playlist manages an ordered track list with shuffle and repeat support.
pluginmgr Package pluginmgr implements the `cliamp plugins` CLI subcommands: list, install, and remove.	Package pluginmgr implements the `cliamp plugins` CLI subcommands: list, install, and remove.
provider Package provider defines optional capability interfaces for music providers.	Package provider defines optional capability interfaces for music providers.
resolve Package resolve converts CLI arguments (files, directories, globs, URLs, M3U playlists, and RSS feeds) into a flat list of playlist tracks.	Package resolve converts CLI arguments (files, directories, globs, URLs, M3U playlists, and RSS feeds) into a flat list of playlist tracks.
theme Package theme handles loading and parsing color themes from TOML files.	Package theme handles loading and parsing color themes from TOML files.
ui
model Package ui implements the Bubbletea TUI for the CLIAMP terminal music player.	Package ui implements the Bubbletea TUI for the CLIAMP terminal music player.
upgrade Package upgrade implements self-upgrade by downloading the latest release binary from GitHub, mirroring the install.sh mechanism.	Package upgrade implements self-upgrade by downloading the latest release binary from GitHub, mirroring the install.sh mechanism.