chrisuthe/squeezelitemultiroom

多房间音频控制器

核心概念

一台服务器。多个音频输出。搭配Music Assistant的全屋音频系统。

本项目允许您运行单个中央服务器（如NAS、树莓派或任何Docker主机），连接多个USB DAC或音频设备，在整个家庭中创建独立的音频区域。无需购买昂贵的多房间音频硬件，只需将经济实惠的USB DAC连接到中央机器，即可向每个房间流式传输同步音频。

┌─────────────────────────────────────────────────────────────────┐
│                     中央服务器 (Docker主机)                      │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │               多房间音频容器                            │    │
│  │                                                         │    │
│  │   ┌──────────┐  ┌──────────┐  ┌──────────┐              │    │
│  │   │ 播放器1  │  │ 播放器2  │  │ 播放器3  │  ...         │    │
│  │   │ (厨房)   │  │ (卧室)   │  │ (露台)   │              │    │
│  │   └────┬─────┘  └────┬─────┘  └────┬─────┘              │    │
│  └────────┼─────────────┼─────────────┼────────────────────┘    │
│           │             │             │                         │
│      ┌────▼────┐   ┌────▼────┐   ┌────▼────┐                    │
│      │USB DAC 1│   │USB DAC 2│   │声卡     │                    │
│      └─────────┘   └─────────┘   └─────────┘                    │
└─────────────────────────────────────────────────────────────────┘

!多房间音频控制器 !Docker !Music Assistant !.NET 8 !Sendspin

核心功能与特性

主要功能

• Sendspin协议：通过SendSpin.SDK原生集成Music Assistant
• 无限播放器：根据可用输出创建任意数量的音频区域
• 独立音量控制：单独调节每个区域的音量
• 实时监控：基于SignalR的实时状态更新
• 自动发现：播放器自动出现在Music Assistant中
• 持久化配置：容器重启和更新后配置保持不变
• 多架构支持：支持AMD64和ARM64（树莓派）
• REST API：完整的编程控制，带Swagger文档
• 健康监控：内置容器健康检查接口 /api/health
• 日志记录：全面的日志记录以便故障排除
• Home Assistant：HAOS原生插件

音频支持

• USB DAC：通过PortAudio自动检测
• 内置音频：支持主板音频输出
• HDMI音频：多通道HDMI音频输出支持
• 虚拟设备：用于测试的空设备，软件定义的ALSA设备

Docker Hub镜像

可直接部署的镜像地址：https://hub.docker.com/r/chrisuthe/squeezelitemultiroom

快速部署

bash
docker run -d \
  --name multiroom-audio \
  --network host \
  -p 8096:8096 \
  --device /dev/snd:/dev/snd \
  -v audio_config:/app/config \
  ghcr.io/chrisuthe/multiroom-audio:latest

通过 http://localhost:8096 访问Web界面

Docker Compose配置

yaml
services:
  multiroom-audio:
    image: ghcr.io/chrisuthe/multiroom-audio:latest
    container_name: multiroom-audio
    restart: unless-stopped
    network_mode: host
    ports:
      - "8096:8096"
    devices:
      - /dev/snd:/dev/snd
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      # - /etc/asound.conf:/etc/asound.conf:ro  # 可选：自定义ALSA配置
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8096/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

快速开始

先决条件

• Docker环境（推荐Linux系统用于音频支持）
• 运行中的Music Assistant
• 音频设备（USB DAC、内置音频等）

步骤1：部署容器

使用上述Docker run命令或Docker Compose配置部署容器。

步骤2：访问Web界面

导航至 http://your-host-ip:8096

步骤3：创建第一个播放器

1. 点击 "添加播放器"
2. 名称：输入描述性名称（例如"客厅"、"厨房"）
3. 音频设备：从自动检测的PortAudio设备中选择
4. 点击 "创建播放器"

配置选项

环境变量

卷挂载

yaml
volumes:
  - ./config:/app/config               # 播放器配置文件
  - ./logs:/app/logs                   # 应用程序日志
  - /etc/asound.conf:/etc/asound.conf  # 仅在需要访问软件定义设备时需要

音频设备访问

yaml
devices:
  - /dev/snd:/dev/snd    # 所有音频设备（Linux系统）

自定义ALSA配置

如果您有自定义ALSA配置（虚拟设备、软件混音、多通道路由等），可挂载您的asound.conf文件使这些设备在容器内可用：

yaml
volumes:
  - ./config:/app/config
  - ./logs:/app/logs
  - /etc/asound.conf:/etc/asound.conf:ro   # 自定义ALSA配置

这在以下场景中很有用：

• 软件混音（dmix）- 在应用程序间共享音频设备
• 虚拟设备 - 自定义设备别名和路由
• 多通道音频 - 配置环绕声或多输出设置
• 硬件特定设置 - 设备特定的采样率、格式或缓冲区大小

容器重启后，您的自定义ALSA设备将出现在设备列表中。

REST API

完整API文档可在 http://localhost:8096/docs（Swagger UI）查看。

快速示例

bash
# 列出所有播放器
curl http://localhost:8096/api/players

# 创建Sendspin播放器
curl -X POST http://localhost:8096/api/players \
  -H "Content-Type: application/json" \
  -d '{"name": "厨房", "device": "0"}'

# 设置音量
curl -X PUT http://localhost:8096/api/players/厨房/volume \
  -H "Content-Type: application/json" \
  -d '{"volume": 75}'

# 启动/停止播放器
curl -X POST http://localhost:8096/api/players/厨房/restart
curl -X POST http://localhost:8096/api/players/厨房/stop

# 健康检查
curl http://localhost:8096/api/health

故障排除

未检测到音频设备

Linux系统：确保音频设备可访问

bash
# 检查可用设备
aplay -l

# 验证设备权限
ls -la /dev/snd/

播放器无法启动

1. 检查音频设备可用性：

   bash
   docker exec multiroom-audio ls /dev/snd
   

2. 使用空设备测试：创建设备为null的播放器进行测试

3. 查看日志：

   bash
   docker logs multiroom-audio
   

播放器未出现在Music Assistant中

• 等待30-60秒让mDNS完成发现
• 重启Music Assistant
• 确保两个容器在同一网络中

技术栈

许可与致谢

许可：MIT许可 - 详见LICENSE文件

致谢：

• https://github.com/Sendspin/spec - Sendspin协议实现
• Music Assistant - 现代音乐库管理和多房间音频平台
• PortAudio - 跨平台音频I/O库

详细许可信息，请参见LICENSES.md。

支持与社区

• 问题反馈：通过https://github.com/chrisuthe/squeezelite-docker/issues%E6%8A%A5%E5%91%8A%E9%94%99%E8%AF%AF%E5%92%8C%E8%AF%B7%E6%B1%82%E5%8A%9F%E8%83%BD
• Docker Hub：预构建镜像位于https://hub.docker.com/r/chrisuthe/squeezelitemultiroom
• 文档：https://github.com/chrisuthe/squeezelite-docker/wiki

关于本项目

本项目在AI（Anthropic的Claude）的协助下通过Claude Code开发。人类提供指导、审查输出并做出决策，但实现过程是AI辅助的。

---