cliamp README

The project's README from github.com/bjarneo/cliamp. As one markdown file: README.md.

Docs on contextowl.co

A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Mixcloud, Bilibili, Spotify, NetEase Cloud Music, Yandex Music, Xiaoyuzhou (小宇宙), Navidrome, Lyrion, Plex, Jellyfin, and Audiobookshelf. Use the spectrum visualizer, parametric EQ, and playlist manager.

cliamp.stream | docs

cliamp uses Bubbletea, Lip Gloss, Beep, and go-librespot.

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

Proudly sponsored by contextowl.co

Install

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

Homebrew

brew install bjarneo/cliamp/cliamp

The formula installs all required runtime libraries.

Arch Linux (AUR)

yay -S cliamp

Nix

nix run github:bjarneo/cliamp

For a declarative NixOS configuration, add github:bjarneo/cliamp as a flake input. Install its default package:

inputs.cliamp.url = "github:bjarneo/cliamp";

environment.systemPackages = [
  inputs.cliamp.packages.${pkgs.stdenv.hostPlatform.system}.default
];

Go

go install github.com/bjarneo/cliamp@latest

Install ALSA development headers before you build on Linux. See Building from source.

Pre-built binaries

Download from GitHub Releases.

macOS: Pre-built binaries link dynamically to FLAC, Vorbis, Ogg, and mpg123 from Homebrew. If you download from Releases or use install.sh, install these libraries first. Otherwise, you can see errors such as Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib:

brew install flac libvorbis libogg mpg123

brew install bjarneo/cliamp/cliamp installs these libraries.

Linux: Pre-built binaries link FLAC, Vorbis, Ogg, and mpg123 statically. No extra codec packages are required. You can still need an ALSA bridge for your sound server. See Troubleshooting.

Windows: Download and extract cliamp-windows-amd64.zip from Releases. It includes the codec DLLs that Spotify requires. If HOME is not set, cliamp stores its config under %APPDATA%\cliamp.

Optional runtime dependencies for all platforms and install methods:

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

On Windows, install ffmpeg and yt-dlp with your package manager. 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 such as Navidrome, Lyrion, Plex, Jellyfin, Audiobookshelf, Spotify, Mixcloud, YouTube Music, and NetEase Cloud Music with the interactive wizard:

cliamp setup

The wizard guides you through each provider. It writes the required block to your config file (~/.config/cliamp/config.toml, or %APPDATA%\cliamp\config.toml on Windows when HOME is unset). It validates supported server connections during setup. It checks optional Mixcloud browser-session or OAuth credentials when you use them. See docs/cli.md for details.

See the Mixcloud provider guide for discovery, account, creator/show, genre search, local genre favorites, authentication, signed-in playback, resume, seeking, and limitations.

For podcast discovery and subscriptions, run cliamp --provider podcast. Browse Apple's top 100 shows and 19 categories, search with / then Enter, and subscribe with f. No account or API key is needed. See the Podcasts guide.

Radio

Press R in the player to browse about 58,000 online radio stations in the Radio Browser directory.

Cut that down by location or genre: N browses by country, Browse genres & tags opens the directory's complete tag index, and / filters either list. f pins the countries you listen to, and Enter on a country or tag loads its stations as a playlist. cliamp does not work out where you are unless you pick "Use my location" and accept; it then reads your country from the system timezone, never from a geo-IP service. See docs/radio.md.

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

To host a radio station, use cliamp-server.

Building from source

Prerequisites:

Linux (Debian/Ubuntu):

sudo apt install libasound2-dev libflac-dev libvorbis-dev libogg-dev libmpg123-dev

Linux (Fedora):

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

Linux (Arch):

sudo pacman -S alsa-lib flac libvorbis libogg mpg123

macOS: brew install flac libvorbis libogg mpg123 pkg-config

Windows: The core player needs no extra SDKs. It uses pure-Go audio decoding. ffmpeg.exe and yt-dlp.exe remain optional runtime dependencies for the same formats and providers as other platforms.

Spotify support uses go-librespot. It needs CGO and a MinGW toolchain:

  1. Install MSYS2.
  2. Open the MSYS2 MinGW64 terminal, not the standard MSYS2 terminal. Install the toolchain and codec libraries:
    pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-pkg-config \
  mingw-w64-x86_64-libogg mingw-w64-x86_64-libvorbis \
  mingw-w64-x86_64-flac mingw-w64-x86_64-mpg123
  3. In that MinGW64 terminal, build with CGO enabled. This keeps gcc and pkg-config on PATH:
    CGO_ENABLED=1 go build -o cliamp.exe .
    Some MSYS2 libogg builds provide libogg-0.dll without ogg_stream_iovecin in its export table. The static libogg.a has this symbol. If linking fails with undefined reference to 'ogg_stream_iovecin', use static linking for this library only:
    CGO_LDFLAGS="-Wl,-Bstatic -logg -Wl,-Bdynamic" CGO_ENABLED=1 go build -o cliamp.exe .
  4. cliamp.exe links dynamically to codec and MinGW runtime DLLs. Keep C:\msys64\mingw64\bin on PATH at runtime, or copy each /mingw64/bin/*.dll that ldd cliamp.exe shows next to cliamp.exe.

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:

Docs

Full documentation is hosted at whiterose.org.contextowl.co/docs/cliamp.

Troubleshooting

No audio output

cliamp reports audio output unavailable when it cannot open an output device. On Linux systems that use PipeWire or PulseAudio, the cliamp ALSA backend needs a bridge package to route audio through the sound server:

Install the 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

# Debian/Ubuntu (PulseAudio, including WSL2)
sudo apt install libasound2-plugins

On WSL2 see WSL2 setup for the extra ALSA routing step.

Author

x.com/iamdothash

Disclaimer

Use this software at your own risk. The authors are not responsible for damage or issues that result from its use.

cliamp (bjarneo/cliamp)

Searching Database…

4.5K ·GitHub
Cliamp
Что это такое?cliamp — ретро-музыкальный плеер для терминала, вдохновлённый Winamp. Он проигрывает локальные файлы и потоки из таких сервисов, как YouTube, Spotify, SoundCloud, Navidrome, Jellyfin, Plex и интернет-радио, — и всё это в интерфейсе терминала.
Это приложение с графическим интерфейсом или оно работает в терминале?Это терминальное (TUI) приложение, которое запускается в шелле, а не оконный GUI: интерфейс построен на Bubbletea и Lip Gloss, а за воспроизведение звука отвечают Beep и go-librespot.
Как установить cliamp?Установите через Homebrew (brew install bjarneo/cliamp/cliamp), из Arch AUR, через Nix flake, командой go install, готовым бинарником из GitHub Releases либо соберите из исходников: go build -o cliamp .
Что нужно установить, кроме самого cliamp?В Linux для сборки нужны dev-заголовки ALSA, а чтобы действительно слышать звук, — ALSA-мост (pipewire-alsa или pulseaudio-alsa). Опциональный ffmpeg обрабатывает AAC/ALAC/Opus/WMA, а yt-dlp подтягивает аудио с YouTube, SoundCloud, Bilibili и других площадок.
Есть ли подводные камни при установке?Готовые бинарники для macOS динамически линкуют FLAC, Vorbis, Ogg и mpg123 из Homebrew, поэтому их нужно установить заранее, иначе воспроизведение упадёт с ошибкой 'Library not loaded'. Сборка поддержки Spotify в Windows требует CGO и полного тулчейна MSYS2 MinGW.
Отслеживает ли cliamp моё местоположение для функции радио?cliamp определяет страну только по часовому поясу вашей системы и лишь если вы явно согласились на 'Use my location' для просмотра радиостанций по странам.
Поддерживает ли cliamp подкасты?Да — запустите cliamp --provider podcast, чтобы просматривать топ-100 шоу Apple в 19 категориях, искать и подписываться; аккаунт или API-ключ не нужны.
Сколько радиостанций можно просматривать?Нажатие R в плеере открывает около 58 000 онлайн-станций из каталога Radio Browser, которые можно фильтровать по стране или жанру и искать.
Какие функции воспроизведения есть у самого плеера?В плеере есть спектр-визуализатор, параметрический эквалайзер и менеджер плейлистов в дополнение к обычным кнопкам управления.
Как подключить такие сервисы, как Navidrome или Spotify?Интерактивный мастер настройки проведёт вас по каждому удалённому провайдеру (Navidrome, Plex, Jellyfin, Spotify, Mixcloud и другие), запишет блок конфига и проверит соединение прямо при настройке.
What are similar projects?spotatui, spotify-tui, spotify-downloader, openspot-music-app, Levyra-deepsound, ISpotify, moji, cli
Which topics is it in?soundcloud, bubbletea, stream, audio-streaming, radio, m3u, podcast, spotify, yt-dlp, music-player, youtube, music
Creator
bjarneo
Size
10.4 MB
Stars
4.5K
Updated
CommitOct 11Releasev2.3.0Sep 28
Age
7mo
Commits · 90 Days