ggoussard/spotifyd

Spotifyd Docker镜像文档

镜像概述和主要用途

Spotifyd是一个作为UNIX守护进程运行的开源Spotify客户端。它能像官方客户端一样流式播放音乐，但更轻量级且支持更多平台。该镜像特别适用于Raspberry Pi和x86_64架构设备，通过Spotify Connect协议可被官方客户端（Android/iOS/桌面版）发现和控制。

注意：使用Spotifyd需要Spotify Premium账户。

核心功能和特性

• 轻量级设计：相比官方客户端资源占用更低
• 跨平台支持：支持Linux（AMD64和ARMv6架构，适用于所有Raspberry Pi型号）
• Spotify Connect协议：作为可被官方客户端控制的设备显示
• 多种音频后端：默认ALSA，支持PulseAudio和PortAudio（适用于macOS等平台）
• D-Bus MPRIS支持：可通过通用媒体播放控制器（如playerctl）控制（实验性）
• 配置灵活性：支持用户级和系统级配置文件，可通过命令行参数调整

使用场景和适用范围

• 家庭音频系统：在Raspberry Pi等嵌入式设备上运行，作为家庭音响的Spotify播放终端
• 轻量级音乐播放：在资源受限的设备上提供Spotify服务
• 多房间音频：通过Spotify Connect实现多设备同步播放
• 自动化场景：结合脚本或智能家居系统控制音乐播放

安装与构建

从二进制文件安装

Travis CI为Linux系统（AMD64和ARMv6架构）构建二进制文件，可在https://github.com/Spotifyd/spotifyd/releases/latest获取。其他系统需从源码构建，需安装ALSA包（如Ubuntu的`libasound2-dev`）。详细安装说明见https://github.com/Spotifyd/spotifyd/wiki。

从源码构建

需安装https://www.rust-lang.org/zh-CN/：

bash
cargo build --release

生成的二进制文件位于target/release/spotifyd。默认构建ALSA后端，可通过以下方式构建其他后端：

bash
# 禁用默认特性，指定其他后端
cargo build --release --no-default-features --features <backend>

配置说明

配置文件

Spotifyd会在XDG配置目录中搜索spotifyd.conf文件：

• 用户级配置：~/.config/spotifyd/spotifyd.conf
• 系统级配置：/etc/spotifyd.conf 或 /etc/xdg/spotifyd/spotifyd.conf

配置文件格式示例：

ini
[global]
username = 用户名
password = 密码
backend = alsa  # 音频后端：alsa/pulseaudio/portaudio
device = alsa_audio_device  # 由`aplay -L`命令获取
mixer = PCM  # 混音器名称
volume-control = alsa  # 音量控制方式：alsa/alsa_linear/softvol
#onevent = 播放事件触发命令
device_name = 连接显示名称  # 不能包含空格
bitrate = 320  # 比特率：96|160|320
cache_path = 缓存目录路径
volume-normalisation = true  # 是否启用音量归一化
normalisation-pregain = -10  # 归一化预增益

所有字段均为可选，Spotifyd可无配置文件运行。[spotifyd] section的配置优先级高于[global]，适用于共享部分配置的相关应用。值可使用双引号包围（如包含#时）。

命令行参数

运行spotifyd --help获取最新参数列表，支持设置PID文件、 verbose模式、非守护进程模式等。

音频后端配置

ALSA（默认）

无需额外配置，系统通常默认安装。

PulseAudio

需编译时启用特性：

bash
cargo build --release --features pulseaudio_backend

需安装PulseAudio开发包和构建工具（如build-essential）。

PortAudio（适用于macOS）

需编译时启用特性：

bash
cargo build --release --no-default-features --features portaudio_backend

需安装PortAudio开发包（如macOS使用brew install portaudio）。

使用方法

通过Spotify Connect控制

Spotifyd通过Spotify Connect协议通信，可直接从官方Spotify客户端（Android/iOS/桌面版）发现并控制。

D-Bus MPRIS控制（实验性）

Spotifyd实现了https://specifications.freedesktop.org/mpris-spec/latest/，可被通用媒体控制器（如https://github.com/acrisci/playerctl）控制。需编译时启用`dbus_mpris`特性：

bash
cargo build --release --features dbus_mpris

作为systemd服务运行

提供systemd服务单元文件contrib/spotifyd.service，复制到以下路径：

• 系统级：/etc/systemd/user/
• 用户级：~/.config/systemd/user/

控制命令：

bash
# 启动服务
systemctl --user start spotifyd.service
# 设置开机自启
systemctl --user enable spotifyd.service

作为Docker服务运行

构建镜像

bash
docker build -t spotifyd:local -f Dockerfile .

运行容器

bash
docker run -d \
  --net host \  # 允许本地网络发现（无此选项时Spotify Connect使用云端链接）
  --group-add $(getent group audio | cut -d: -f3) \  # 授予音频设备访问权限（如主机音频组ID非29）
  --device /dev/snd:/dev/snd \  # 挂载音频设备
  -v /usr/share/alsa:/usr/share/alsa \  # 挂载ALSA配置
  -v $PWD/contrib/spotifyd.conf:/etc/spotifyd.conf \  # 挂载配置文件
  --name spotifyd \
  spotifyd:local

后续启动

bash
docker start spotifyd

日志

• --no-daemon模式：日志输出到标准输出
• 守护进程模式：日志写入syslog，可通过系统日志配置调整输出位置

提交bug报告时建议启用verbose模式（增加日志详细度）。

常见问题

• 必须使用Spotify Premium账户：免费账户无法使用
• 设备名称不能包含空格：配置文件中的device_name字段不支持空格

鸣谢

本项目基于https://github.com/plietar/librespot的***工作，特别感谢https://github.com/plietar的贡献。