tsirysndr/rockbox-zig 源代码: https://github.com/tsirysndr/rockbox-zig # Rockbox Zig 🎵 ⚡ GPL-2.0 许可证 ci (https://github.com/tsirysndr/rockbox-zig/actions/workflows/ci.yml) Docker 拉取次数 (https://hub.docker.com/r/tsiry/rockbox) GitHub 下载量 (所有资产，所有发布版本) discord (https://discord.gg/tXPrgcPKSt) storybook (https://master–670ceec25af685dcdc87c0df.chromatic.com/?path=/story/components-albums–default) Rockbox UI 这是 Rockbox (https://www.rockbox.org) 开源音频播放器的现代重构版，并通过 Rust 和 Zig 进行了扩展。Rockbox Zig 通过 gRPC、GraphQL、HTTP 和 MPD API 暴露完整的 Rockbox 音频引擎——包括无缝播放、DSP、20+ 种编解码器、标签数据库——并通过 AirPlay、Snapcast 和 Squeezelite 增加多房间输出功能。 预览 桌面 macOS 媒体控制 macOS 预览 — ## ✨ 功能 ### 音频输出 - [x] 内置 CPAL (https://github.com/RustAudio/cpal) 音频 - [x] AirPlay (https://en.wikipedia.org/wiki/AirPlay) (RAOP) — 单房间或多房间扇出至 Apple TV、HomePod、Airport Express、shairport-sync - [x] Snapcast (https://github.com/snapcast/snapcast) — 通过 snapserver 实现同步多房间播放（FIFO/管道 以及 带有 mDNS 自动发现的直接 TCP） - [x] Squeezelite (https://github.com/ralph-irving/squeezelite) (Slim 协议 + HTTP 广播) — 同步多房间 - [x] Chromecast (https://developers.google.com/cast) - [x] 无缝播放和交叉淡入淡出 - [x] 支持 20+ 种编解码器：MP3、OGG、FLAC、WAV、AAC、Opus 等 ### APIs & 集成 - [x] gRPC API (https://buf.build/tsiry/rockboxapis/docs/main:rockbox.v1alpha1) - [x] GraphQL API - [x] HTTP REST API - [x] MPD (https://mpd.readthedocs.io/en/stable/protocol.html) 服务器 — 兼容所有 MPD 客户端 - [x] MPRIS (https://specifications.freedesktop.org/mpris-spec/) — 桌面媒体键和任务栏集成 - [x] 由 Typesense (https://typesense.org) 驱动的快速搜索 - [x] 按文件夹或标签数据库浏览 - [x] UPnP/DLNA - [x] Android 库 ### 客户端 - [x] Web 客户端 (React) - [x] 桌面客户端 (原生 MacOS / GPUI / GTK4) - [x] 移动应用 (React Native) - [x] 终端客户端 (TUI) - [x] Rockbox REPL ### 计划中 - [ ] 从 YouTube / Spotify / Tidal 流式传输 - [ ] TuneIn 电台 - [ ] Kodi 输出 - [ ] TypeScript (Deno (https://deno.com)) 插件 API - [ ] Wasm 扩展 — ## 🚀 快速开始 ### 🐳 Docker 最快的入门方式——无需安装，无需配置文件： sh docker run -v $HOME/Music:/root/Music \ -p 6062:6062 \ -p 1704:1704 \ -p 1705:1705 \ -p 1780:1780 \ tsiry/rockbox 在第二个终端中，连接 Snapcast (https://github.com/snapcast/snapcast) 客户端以进行音频输出： sh snapclient tcp://localhost 打开 http://localhost:6062 的 Web UI 并开始播放！ — ### 手动安装 1. 安装（见下方的安装）。 2. 创建 ~/.config/rockbox.org/settings.toml： toml music_dir = "/path/to/your/Music" audio_output = "builtin" # CPAL 音频——见音频输出部分了解其他选项 playlist_shuffle = false repeat_mode = 1 bass = 0 treble = 0 bass_cutoff = 0 treble_cutoff = 0 crossfade = 5 fade_on_stop = false fade_in_delay = 2 fade_in_duration = 7 fade_out_delay = 4 fade_out_duration = 0 fade_out_mixmode = 2 balance = 0 stereo_width = 100 stereosw_mode = 0 surround_enabled = 0 surround_balance = 0 surround_fx1 = 0 surround_fx2 = 0 party_mode = true channel_config = 0 player_name = "" eq_enabled = true [[eq_band_settings]] cutoff = 0 q = 64 gain = 10 [[eq_band_settings]] cutoff = 3 q = 125 gain = 10 [[eq_band_settings]] cutoff = 19 q = 250 gain = 10 [[eq_band_settings]] cutoff = 5 q = 500 gain = 10 [[eq_band_settings]] cutoff = -16 q = 1000 gain = 10 [[eq_band_settings]] cutoff = -66 q = 2000 gain = 10 [[eq_band_settings]] cutoff = -31 q = 4000 gain = 10 [[eq_band_settings]] cutoff = 9 q = 8000 gain = 10 [[eq_band_settings]] cutoff = 32 q = 16000 gain = 7 [[eq_band_settings]] cutoff = 34 q = 0 gain = 0 [replaygain_settings] noclip = true type = 0 preamp = 0 [compressor_settings] threshold = -24 makeup_gain = 0 ratio = 4 knee = 1 release_time = 300 attack_time = 5 3. 启动 Rockbox： sh rockbox 4. 打开 Web UI 访问 http://localhost:6062 或连接任何 MPD 客户端到 localhost:6600。 — ## 🔌 端口 | 服务 | 默认端口 | 协议 | | ———————————— | ———— | ————— | | gRPC | 6061 | gRPC / gRPC-Web | | GraphQL + Web UI | 6062 | HTTP | | HTTP REST API | 6063 | HTTP | | MPD 服务器 | 6600 | MPD 协议 | | Slim 协议 (squeezelite) | 3483 | TCP | | HTTP PCM 流 (squeezelite) | 9999 | HTTP | | Chromecast WAV 流 | 7881 | HTTP | | UPnP 媒体服务器 (ContentDirectory) | 7878 | HTTP / SSDP | | UPnP WAV 广播 (PCM 接收器) | 7879 | HTTP | | UPnP 媒体渲染器 (AVTransport) | 7880 | HTTP / SSDP | — ## ⚙️ 音频输出配置 Rockbox 在启动时读取 ~/.config/rockbox.org/settings.toml。music_dir 始终必填。如果省略 audio_output，则默认为 "builtin"。 ### 内置 CPAL — 默认 toml music_dir = "/path/to/Music" audio_output = "builtin" 使用 CPAL (https://github.com/RustAudio/cpal) — 通过操作系统默认设备播放。无需额外设置。 ### Snapcast Rockbox 支持两种方式向 Snapcast (https://github.com/snapcast/snapcast) 提供数据以实现同步多房间播放。两者都将原始 S16LE 立体声 44100 Hz PCM 写入 snapserver。 #### TCP（推荐 — 自动发现） toml music_dir = "/path/to/Music" audio_output = "snapcast_tcp" snapcast_tcp_host = "192.168.1.x" # 运行 snapserver 的机器 IP snapcast_tcp_port = 4953 # 默认 snapserver TCP 源端口 直接连接到 snapserver 的 TCP 源端口。无需命名 FIFO 或文件系统依赖。 ini # /etc/snapserver.conf (macOS 上为 /usr/local/etc/snapserver.conf) [stream] source = tcp://0.0.0.0:4953?name=default&sampleformat=44100:16:2 > 启动顺序：先启动 snapserver，以便在 rockboxd 开始播放时它已在监听。如果连接断开（例如 snapserver 重启），它将在下一次播放调用时自动重新建立。 > 自动发现：rockboxd 在启动时通过 mDNS 扫描 _snapcast._tcp.local.。发现的服务器将出现在 Web UI 和桌面应用的设备选择器中——只需单击即可连接，无需编辑配置文件。 #### FIFO / 管道 toml music_dir = "/path/to/Music" audio_output = "fifo" fifo_path = "/tmp/snapfifo" # snapserver 的命名 FIFO；使用 "-" 表示 stdout 写入命名 FIFO。在需要 stdout 管道或偏好传统管道模型时使用此选项。 ini # /etc/snapserver.conf (macOS 上为 /usr/local/etc/snapserver.conf) [stream] source = pipe:///tmp/snapfifo?name=default&sampleformat=44100:16:2 > 启动顺序：在 snapserver 之前启动 rockboxd。Rockbox 在 FIFO 上保持永久写引用，因此 snapserver 永远不会在曲目之间看到提前的 EOF。将管道传输到任何 PCM 消费者： sh rockboxd | ffplay -f s16le -ar 44100 -ac 2 - 有关两种模式的详细比较、连接生命周期、重连行为以及 macOS 怪癖，请参阅 SNAPCAST.md。 ### AirPlay (RAOP) — 单房间或多房间 单接收器： toml music_dir = "/path/to/Music" audio_output = "airplay" airplay_host = "192.168.1.50" # AirPlay 接收器的 IP airplay_port = 5000 # 可选，默认 5000 多房间（同时扇出到 N 个接收器）： toml music_dir = "/path/to/Music" audio_output = "airplay" [[airplay_receivers]] host = "192.168.1.50" # 客厅 port = 5000 # 可选，默认 5000 [[airplay_receivers]] host = "192.168.1.51" # 卧室 # 端口默认为 5000 通过 RTP 向任何兼容 RAOP 的接收器流式传输 ALAC 编码的音频——Apple TV、HomePod、Airport Express 或 shairport-sync (https://github.com/mikebrady/shairport-sync)。所有接收器共享相同的 initial_rtptime，因此局域网内的 RTP 级播放同步精度在一个帧（~8 毫秒）以内。 ### Squeezelite (Slim 协议 — 多房间) toml music_dir = "/path/to/Music" audio_output = "squeezelite" squeezelite_port = 3483 # Slim 协议 TCP 端口，默认 3483 squeezelite_http_port = 9999 # HTTP PCM 广播端口，默认 9999 Rockbox 充当最小化的 Logitech Media Server。任意数量的 squeezelite (https://github.com/ralph-irving/squeezelite) 客户端可以同时连接；Rockbox 每秒向每个客户端发送一个 sync 数据包，使它们都与相同的播放时钟对齐： sh squeezelite -s localhost -n "客厅" squeezelite -s localhost -n "厨房" squeezelite -s localhost -n "卧室" 选择特定的输出设备： sh squeezelite -s localhost -l # 列出可用设备 squeezelite -s localhost -o "" # 系统默认 squeezelite -s localhost -o "内置输出" ### Chromecast toml music_dir = "/path/to/Music" audio_output = "chromecast" chromecast_host = "192.168.1.60" # 目标 Chromecast 的局域网 IP chromecast_port = 8009 # 可选，默认 8009 (Cast 协议) chromecast_http_port = 7881 # 可选，默认 7881 (WAV HTTP 流) Rockbox 向任何兼容 Google Cast 的设备流式传输音频——Google Home、Chromecast Audio、带有 Google TV 的 Chromecast、Nest Hub 或第三方 Cast 接收器。它同时使用两个通道： - Cast 协议 (TCP 8009, TLS + Protobuf) — 发送播放命令并告知设备从哪里获取音频流。 - HTTP 上的 WAV (端口 7881) — 提供带有有限 Content-Length 的实时 audio/wav 流，以便 Chromecast 可以显示进度条并在曲目边界自动推进队列。 曲目元数据（标题、艺术家、专辑、时长）和专辑封面会在每次曲目更改时推送到设备上。局域网上的 Chromecast 设备也会通过 mDNS (_googlecast._tcp.local.) 自动发现，并出现在 UI 设备选择器中；通过选择器连接会在无需在配置文件中设置 audio_output = "chromecast" 的情况下按需启动 Cast 会话。 > 网络要求：Chromecast 设备必须能够访问运行 rockboxd 的机器上的端口 7881。如果 rockboxd 位于虚拟机或容器中，请将端口转发到主机。有关架构、协议和 FFI 接口的详细描述，请参阅 crates/chromecast/README.md。 ### UPnP / DLNA Rockbox 具有三种独立的 UPnP/DLNA 模式，可以随意组合。 #### PCM 接收器 — 向 UPnP 渲染器（Kodi、VLC 等）流式传输实时音频 toml music_dir = "/path/to/Music" audio_output = "upnp" # 目标渲染器的 AVTransport controlURL（元数据推送必需） upnp_renderer_url = "http://192.168.1.x:7777/AVTransport/control" # WAV HTTP 广播服务器端口（默认：7879） upnp_http_port = 7879 Rockbox 将实时 PCM 编码为连续的 HTTP 上的 WAV 流，并通过 AVTransport SOAP 命令渲染器播放它。曲目元数据（标题、艺术家、专辑、专辑封面、时长）作为 DIDL-Lite XML 在 SetAVTransportURI 中发送，并在每次曲目更改时自动刷新，以保持渲染器“正在播放”显示的准确性。 > 查找 upnp_renderer_url：使用 RUST_LOG=info 启动 rockboxd — 它 > 在启动时扫描局域网，并为每个发现的渲染器记录 upnp scan: found renderer "..." av=http://... >。 #### 媒体服务器 — 向控制点（BubbleUPnP、Kodi 等）暴露库 toml upnp_server_enabled = true upnp_server_port = 7878 # 默认 upnp_friendly_name = "Rockbox" # 在应用中显示的名称 启动 ContentDirectory 服务，以便控制点可以浏览艺术家、专辑和曲目，并直接从 Rockbox 拉取音频。 #### 媒体渲染器 — 允许控制点向 Rockbox 推送媒体 toml upnp_renderer_enabled = true upnp_renderer_port = 7880 # 默认 upnp_friendly_name = "Rockbox" Rockbox 注册为 MediaRenderer:1。任何 DLNA 控制点（BubbleUPnP、Foobar2000 等）都可以向 Rockbox 推送 URI 并远程控制播放。传入的 DIDL-Lite 元数据（标题、艺术家、专辑、专辑封面、时长）会被解析并显示。 #### 所有 UPnP 设置 | 键 | 默认值 | 描述 | | ———————– | ———– | ——————————————— | | audio_output = "upnp" | — | 启用 PCM → WAV 流式传输接收器 | | upnp_renderer_url | — | 目标渲染器的 AVTransport controlURL | | upnp_http_port | 7879 | WAV 广播 HTTP 端口 | | upnp_server_enabled | false | 启动 ContentDirectory 媒体服务器 | | upnp_server_port | 7878 | 媒体服务器 HTTP 端口 | | upnp_renderer_enabled | false | 启动 MediaRenderer 端点 | | upnp_renderer_port | 7880 | MediaRenderer HTTP 端口 | | upnp_friendly_name | "Rockbox" | 向控制点显示的显示名称 | — ## 🚚 安装 ### Ubuntu / Debian sh echo "deb [trusted=yes] https://apt.fury.io/tsiry/ /" | sudo tee /etc/apt/sources.list.d/fury.list sudo apt-get update sudo apt-get install rockbox ### Fedora 将以下内容添加到 /etc/yum.repos.d/fury.repo： ini [fury] name=Gemfury Private Repo baseurl=https://yum.fury.io/tsiry/ enabled=1 gpgcheck=0 然后运行： sh dnf install rockbox ### Arch Linux sh paru -S rockbox-zig-bin ### macOS/Linux (Homebrew) sh brew install tsirysndr/tap/rockbox ### 通用 (curl 安装程序) sh curl -fsSL https://raw.githubusercontent.com/tsirysndr/rockbox-zig/HEAD/install.sh | bash — ## 📦 下载 最新版本的预构建二进制文件可在 Releases 页面 (https://github.com/tsirysndr/rockbox-zig/releases/latest) 上获得。 | 平台 | 架构 | 包 | | –––– | ———————– | ——— | | Linux | x86_64 | .tar.gz | | Linux | aarch64 | .tar.gz | | macOS | x86_64 | .pkg | | macOS | aarch64 (Apple Silicon) | .pkg | — ## 🧙♂️ Systemd 服务 sh rockbox service install # 启用并启动 rockbox 服务 service uninstall # 停止并禁用 rockbox 服务 service status # 检查状态 Systemd 服务截图 — ## 🏗️ 从源代码编译 ### 依赖项 Ubuntu / Debian sh sudo apt-get install libsdl2-dev libfreetype6-dev libdbus-1-dev libunwind-dev zip protobuf-compiler cmake libxkbcommon-dev libxkbcommon-x11-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev Fedora sh sudo dnf install SDL2-devel freetype-devel libunwind-devel zip protobuf-compiler cmake libxkbcommon-devel libxkbcommon-x11-devel libxcb-devel macOS sh brew install sdl2 freetype cmake protobuf 您还需要 Zig (https://ziglang.org/download/) ≥ 0.16 和最近的稳定版 Rust 工具链 (rustup update stable)。 ### 构建 sh # 1. 克隆 git clone https://github.com/tsirysndr/rockbox-zig.git cd rockbox-zig git submodule update --init --recursive # 2. 构建 Web UI cd webui/rockbox deno install deno run build cd ../.. # 3. 配置并构建 C 固件（一次性设置） mkdir -p build-lib && cd build-lib ../tools/configure --target=sdlapp --type=N --lcdwidth=320 --lcdheight=240 --prefix=/usr/local cp ../autoconf/autoconf.h . make lib cd .. # 4. 构建 Rust crates cargo build --release -p rockbox-cli -p rockbox-server # 5. 使用 Zig 链接所有内容 cd zig && zig build 二进制文件位于 zig/zig-out/bin/rockboxd。 > 更改后重新构建：编辑 C 代码后，在 build-lib 中运行 make lib；编辑 Rust 后运行 cargo build --release。然后重新运行 zig build。只有当 .a 文件比二进制文件新时，Zig 才会重新链接。 ### 构建 GTK4 桌面应用 ``sh sudo apt-get install flatpak flatpak remote-add –if-not-exists –user flathub https://dl.flathub.org/repo/flathub.flatpakrepo flatpak install –user flathub org.flatpak.Builder flatpak install –user flathub org.gnome.Sdk/x86_64/47 flatpak install –user flathub org.gnome.Platform/x86_64/47 flatpak install –user org.freedesktop.Sdk.Extension.rust-stable flatpak install –user org.freedesktop.Sdk.Extension.llvm18 cd gtk flatpak run org.flatpak.Builder –user –disable-rofiles-fuse –repo=repo flatpak_app build-aux/io.github.tsirysndr.Rockbox.json –force-clean flatpak run org.flatpak