bjarneo--cliamp/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

一款受 Winamp 启发的复古终端音乐播放器。可播放本地文件、流媒体、播客，以及 YouTube、YouTube Music、SoundCloud、Bilibili、Spotify、网易云音乐（NetEase Cloud Music）、小宇宙（Xiaoyuzhou）、Navidrome、Plex 和 Jellyfin，并配有频谱可视化器、参数均衡器（parametric EQ）和播放列表管理功能。

cliamp.stream

基于 Bubbletea, Lip Gloss, Beep, 与 go-librespot. 构建

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

安装

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

Homebrew

brew install bjarneo/cliamp/cliamp

该 formula 会自动拉取所有必需的运行时库。

Arch Linux (AUR)

yay -S cliamp

Go

go install github.com/bjarneo/cliamp@latest

Linux 构建需先安装 ALSA 开发头文件。请参阅从源码构建。

预编译二进制文件

从 GitHub Releases. 下载

macOS： 预编译二进制文件会通过 Homebrew 动态链接 FLAC、Vorbis 和 Ogg。若直接从 Releases 下载（或使用 install.sh 脚本），须先安装这些库，否则会出现类似 Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib 的错误：

brew install flac libvorbis libogg

通过 brew install bjarneo/cliamp/cliamp 安装可自动完成上述步骤。

Linux： 预编译二进制文件静态链接 FLAC、Vorbis 和 Ogg，因此无需额外安装编解码器包。你可能仍需要为声音服务器配置 ALSA 桥接——请参阅故障排除。

Windows： 从 Releases 下载 cliamp-windows-amd64.exe。若未设置 HOME，cliamp 会将配置保存在 %APPDATA%\cliamp 下。Windows 构建目前不支持 Spotify 提供商。

可选运行时依赖（全平台、所有安装方式均适用）：

• ffmpeg — 用于播放 AAC、ALAC、Opus 和 WMA
• yt-dlp — 用于 YouTube、YouTube Music、SoundCloud、Bandcamp、Bilibili 和网易云音乐

在 macOS 上：brew install ffmpeg yt-dlp。在 Linux 上，请使用发行版的包管理器。

在 Windows 上，请通过你偏好的包管理器安装 ffmpeg 和 yt-dlp，并确保二者均位于 PATH。

从源码构建

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

快速开始

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

按 Ctrl+K 可查看所有按键绑定。

配置远程提供商（Navidrome、Plex、Jellyfin、Spotify、YouTube Music、网易云音乐）可使用交互式向导进行配置：

cliamp setup

向导会逐步引导你配置各提供商，验证连接，并将相应配置块写入配置文件（~/.config/cliamp/config.toml；在 Windows 上若未设置 HOME，则为 %APPDATA%\cliamp\config.toml）。详见 docs/cli.md。

电台

在播放器中按 R，可浏览并搜索来自 Radio Browser 目录的 30,000+ 个在线电台。

将自定义电台添加到 ~/.config/cliamp/radios.toml（在 Windows 上若未设置 HOME，则使用 %APPDATA%\cliamp\radios.toml）。详见 docs/configuration.md。

想自建电台？可查看 cliamp-server.

从源码构建

前置条件：

• Go 1.25.5 或更高版本
• ALSA 开发头文件（仅 Linux — 音频后端需要）

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： 无需额外依赖 — 使用 CoreAudio。

Windows： 核心播放器无需额外 SDK。ffmpeg.exe 和 yt-dlp.exe 仍是可选运行时依赖，支持的格式/提供商与其他平台相同。Windows 构建不支持 Spotify。

克隆并构建：

git clone https://github.com/bjarneo/cliamp.git
cd cliamp
make && make install

或不使用 Make：go build -o cliamp .

make install 会将二进制文件置于 ~/.local/bin/。

可选运行时依赖：

• ffmpeg — 用于播放 AAC、ALAC、Opus 和 WMA
• yt-dlp — 用于 YouTube、SoundCloud、Bandcamp、Bilibili 和网易云音乐

文档

• 配置
• 按键绑定
• CLI 参数
• 流媒体
• 播放列表
• YouTube、SoundCloud、Bandcamp 与 Bilibili
• YouTube Music
• 网易云音乐
• SoundCloud
• 歌词
• Spotify
• Navidrome
• Plex
• Jellyfin
• 主题
• SSH 流媒体
• 远程控制（IPC）
• 无界面守护进程模式
• 音频质量
• 媒体控制
• Quickshell 正在播放组件（Omarchy）
• Lua 插件
  • 社区插件
  • 肥皂泡可视化器

故障排除

无音频输出（无错误但静默）

在使用 PipeWire 或 PulseAudio 的 Linux 系统上，cliamp 的 ALSA 后端需要桥接包才能将音频路由至声音服务器：

• PipeWire： pipewire-alsa
• PulseAudio： pulseaudio-alsa

请为你的系统安装相应软件包：

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

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

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

作者

x.com/iamdothash

免责声明

使用本软件风险自负。我们对因使用本软件可能产生的任何损害或问题不承担责任。