wehub-resource-sync
205 lines
6.4 KiB
Markdown
205 lines
6.4 KiB
Markdown
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](https://cliamp.stream)**
|
|
|
|
Built with [Bubbletea](https://github.com/charmbracelet/bubbletea), [Lip Gloss](https://github.com/charmbracelet/lipgloss), [Beep](https://github.com/gopxl/beep), and [go-librespot](https://github.com/devgianlu/go-librespot).
|
|
|
|
|
|
https://github.com/user-attachments/assets/fbc33d20-e3ac-4a62-a991-8a2f0243c8ea
|
|
|
|
|
|
## Install
|
|
|
|
```sh
|
|
curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh
|
|
```
|
|
|
|
**Homebrew**
|
|
|
|
```sh
|
|
brew install bjarneo/cliamp/cliamp
|
|
```
|
|
|
|
The formula pulls in all required runtime libraries automatically.
|
|
|
|
**Arch Linux (AUR)**
|
|
|
|
```sh
|
|
yay -S cliamp
|
|
```
|
|
|
|
**Go**
|
|
|
|
```sh
|
|
go install github.com/bjarneo/cliamp@latest
|
|
```
|
|
|
|
Linux builds need ALSA development headers installed first. See [Building from source](#building-from-source).
|
|
|
|
**Pre-built binaries**
|
|
|
|
Download from [GitHub Releases](https://github.com/bjarneo/cliamp/releases/latest).
|
|
|
|
> **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`:
|
|
>
|
|
> ```sh
|
|
> 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](#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](https://ffmpeg.org/) — for AAC, ALAC, Opus, and WMA playback
|
|
- [yt-dlp](https://github.com/yt-dlp/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**
|
|
|
|
```sh
|
|
git clone https://github.com/bjarneo/cliamp.git && cd cliamp && go build -o cliamp .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](docs/cli.md#setup-wizard) for details.
|
|
|
|
## Radio
|
|
|
|
Press `R` in the player to browse and search 30,000+ online radio stations from the [Radio Browser](https://www.radio-browser.info/) 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](docs/configuration.md#custom-radio-stations).
|
|
|
|
Want to host your own radio? Check out [cliamp-server](https://github.com/bjarneo/cliamp-server).
|
|
|
|
## Building from source
|
|
|
|
**Prerequisites:**
|
|
|
|
- [Go](https://go.dev/dl/) 1.25.5 or later
|
|
- ALSA development headers (Linux only — required by the audio backend)
|
|
|
|
**Linux (Debian/Ubuntu):**
|
|
|
|
```sh
|
|
sudo apt install libasound2-dev
|
|
```
|
|
|
|
**Linux (Fedora):**
|
|
|
|
```sh
|
|
sudo dnf install alsa-lib-devel libvorbis-devel flac-devel
|
|
```
|
|
|
|
**Linux (Arch):**
|
|
|
|
```sh
|
|
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:**
|
|
|
|
```sh
|
|
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](https://ffmpeg.org/) — for AAC, ALAC, Opus, and WMA playback
|
|
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — for YouTube, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music
|
|
|
|
## Docs
|
|
|
|
- [Configuration](docs/configuration.md)
|
|
- [Keybindings](docs/keybindings.md)
|
|
- [CLI Flags](docs/cli.md)
|
|
- [Streaming](docs/streaming.md)
|
|
- [Playlists](docs/playlists.md)
|
|
- [YouTube, SoundCloud, Bandcamp and Bilibili](docs/yt-dlp.md)
|
|
- [YouTube Music](docs/youtube-music.md)
|
|
- [NetEase Cloud Music](docs/netease.md)
|
|
- [SoundCloud](docs/soundcloud.md)
|
|
- [Lyrics](docs/lyrics.md)
|
|
- [Spotify](docs/spotify.md)
|
|
- [Navidrome](docs/navidrome.md)
|
|
- [Plex](docs/plex.md)
|
|
- [Jellyfin](docs/jellyfin.md)
|
|
- [Themes](docs/themes.md)
|
|
- [SSH Streaming](docs/ssh-streaming.md)
|
|
- [Remote Control (IPC)](docs/remote-control.md)
|
|
- [Headless Daemon Mode](docs/headless.md)
|
|
- [Audio Quality](docs/audio-quality.md)
|
|
- [Media Controls](docs/mediactl.md)
|
|
- [Quickshell Now-Playing Widget (Omarchy)](docs/quickshell.md)
|
|
- [Lua Plugins](docs/plugins.md)
|
|
- [Community Plugins](docs/community-plugins.md)
|
|
- [Soap Bubbles Visualizer](https://github.com/bjarneo/cliamp-plugin-soap-bubbles)
|
|
|
|
## 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:
|
|
|
|
```sh
|
|
# 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](https://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.
|