<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/bjarneo/cliamp) · [上游 README](https://github.com/bjarneo/cliamp/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

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

**[cliamp.stream](https://cliamp.stream)**

基于 [Bubbletea](https://github.com/charmbracelet/bubbletea), [Lip Gloss](https://github.com/charmbracelet/lipgloss), [Beep](https://github.com/gopxl/beep), 与 [go-librespot](https://github.com/devgianlu/go-librespot). 构建


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


## 安装

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

**Homebrew**

```sh
brew install bjarneo/cliamp/cliamp
```

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

**Arch Linux (AUR)**

```sh
yay -S cliamp
```

**Go**

```sh
go install github.com/bjarneo/cliamp@latest
```

Linux 构建需先安装 ALSA 开发头文件。请参阅[从源码构建](#building-from-source)。

**预编译二进制文件**

从 [GitHub Releases](https://github.com/bjarneo/cliamp/releases/latest). 下载

> **macOS：** 预编译二进制文件会通过 Homebrew 动态链接 FLAC、Vorbis 和 Ogg。若直接从 Releases 下载（或使用 `install.sh` 脚本），须先安装这些库，否则会出现类似 `Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib` 的错误：
>
> ```sh
> brew install flac libvorbis libogg
> ```
>
> 通过 `brew install bjarneo/cliamp/cliamp` 安装可自动完成上述步骤。
>
> **Linux：** 预编译二进制文件静态链接 FLAC、Vorbis 和 Ogg，因此无需额外安装编解码器包。你可能仍需要为声音服务器配置 ALSA 桥接——请参阅[故障排除](#troubleshooting)。
>
> **Windows：** 从 Releases 下载 `cliamp-windows-amd64.exe`。若未设置 `HOME`，cliamp 会将配置保存在 `%APPDATA%\cliamp` 下。Windows 构建目前不支持 Spotify 提供商。

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

- [ffmpeg](https://ffmpeg.org/) — 用于播放 AAC、ALAC、Opus 和 WMA
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — 用于 YouTube、YouTube Music、SoundCloud、Bandcamp、Bilibili 和网易云音乐

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

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

**从源码构建**

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

## 快速开始

```sh
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、网易云音乐）可使用交互式向导进行配置：

```sh
cliamp setup
```

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

## 电台

在播放器中按 `R`，可浏览并搜索来自 [Radio Browser](https://www.radio-browser.info/) 目录的 30,000+ 个在线电台。

将自定义电台添加到 `~/.config/cliamp/radios.toml`（在 Windows 上若未设置 `HOME`，则使用 `%APPDATA%\cliamp\radios.toml`）。详见 [docs/configuration.md](docs/configuration.md#custom-radio-stations)。

想自建电台？可查看 [cliamp-server](https://github.com/bjarneo/cliamp-server).

## 从源码构建

**前置条件：**

- [Go](https://go.dev/dl/) 1.25.5 或更高版本
- ALSA 开发头文件（仅 Linux — 音频后端需要）

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

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

**克隆并构建：**

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

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

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

**可选运行时依赖：**

- [ffmpeg](https://ffmpeg.org/) — 用于播放 AAC、ALAC、Opus 和 WMA
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — 用于 YouTube、SoundCloud、Bandcamp、Bilibili 和网易云音乐

## 文档

- [配置](docs/configuration.md)
- [按键绑定](docs/keybindings.md)
- [CLI 参数](docs/cli.md)
- [流媒体](docs/streaming.md)
- [播放列表](docs/playlists.md)
- [YouTube、SoundCloud、Bandcamp 与 Bilibili](docs/yt-dlp.md)
- [YouTube Music](docs/youtube-music.md)
- [网易云音乐](docs/netease.md)
- [SoundCloud](docs/soundcloud.md)
- [歌词](docs/lyrics.md)
- [Spotify](docs/spotify.md)
- [Navidrome](docs/navidrome.md)
- [Plex](docs/plex.md)
- [Jellyfin](docs/jellyfin.md)
- [主题](docs/themes.md)
- [SSH 流媒体](docs/ssh-streaming.md)
- [远程控制（IPC）](docs/remote-control.md)
- [无界面守护进程模式](docs/headless.md)
- [音频质量](docs/audio-quality.md)
- [媒体控制](docs/mediactl.md)
- [Quickshell 正在播放组件（Omarchy）](docs/quickshell.md)
- [Lua 插件](docs/plugins.md)
  - [社区插件](docs/community-plugins.md)
  - [肥皂泡可视化器](https://github.com/bjarneo/cliamp-plugin-soap-bubbles)

## 故障排除

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

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

- **PipeWire：** `pipewire-alsa`
- **PulseAudio：** `pulseaudio-alsa`

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

```sh
# 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](https://x.com/iamdothash)

## 免责声明

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