adn182/node-sonos-http-api

Sonos HTTP API Docker镜像

镜像概述

本镜像封装了Sonos HTTP API，提供基于HTTP请求的Sonos音频系统控制能力。通过该API，您可以轻松管理Sonos设备的播放状态、音量、分组、预设等功能，适用于家庭自动化或自定义控制场景。

核心功能

• 播放控制: 支持播放、暂停、切换曲目（上一曲/下一曲）、调整播放模式（重复、随机、交叉淡入）。
• 音量管理: 调整单个设备或群组的音量，支持绝对/相对音量控制，以及静音/取消静音。
• 设备分组: 实现设备的加入/离开群组操作。
• 文本转语音（TTS）: 支持Google（默认）、VoiceRSS、Microsoft Cognitive Services、AWS Polly、macOS Say等多种TTS服务，可向指定设备或所有设备发送语音通知。
• 预设管理: 通过预设文件定义设备群组、音量、播放模式等配置，快速应用场景设置。
• 队列与收藏: 管理播放队列，支持播放Sonos收藏和播放列表。
• 高级设置: 调整SUB低音炮（增益、分频、相位）、PLAYBAR夜间模式、语音增强等。

使用场景

• 家庭自动化: 与Home Assistant、OpenHAB等智能家居系统集成，实现语音控制或自动化场景（如开门时播放欢迎语）。
• 自定义控制: 通过脚本或自定义应用远程控制Sonos设备。
• 批量操作: 一键暂停所有设备（如来电时）或恢复播放。
• 语音通知: 发送定时提醒、门铃通知等语音消息。

配置说明

1. 基础配置（settings.json）

通过settings.json文件自定义API行为，支持以下配置：

• port: API监听端口（默认5005）。
• ip: 监听IP地址（默认0.0.0.0）。
• https: 启用HTTPS（需提供证书文件）。
• auth: 启用基本认证（用户名/密码）。
• announceVolume: TTS通知的默认音量（默认40%）。
• TTS服务配置: 如VoiceRSS的API密钥、Microsoft Cognitive Services的密钥等。

示例settings.json片段：

json
{
  "port": 5005,
  "ip": "0.0.0.0",
  "voicerss": "your_voicerss_api_key",
  "microsoft": {
    "key": "your_microsoft_api_key",
    "name": "ZiraRUS"
  }
}

2. 预设管理

• presets文件夹: 将预设文件（JSON5格式）放入presets文件夹，文件名将作为预设名称。示例：

  json
  {
    "players": [
      {"roomName": "Living Room", "volume": 15},
      {"roomName": "Kitchen", "volume": 10}
    ],
    "playMode": {"shuffle": true},
    "favorite": "My Playlist"
  }
  

• 应用预设: 发送http://localhost:5005/preset/[预设名称]请求。

Docker部署示例

1. Docker Run命令

bash
docker run -d \
  --name sonos-api \
  --network host \
  -v ./settings.json:/app/settings.json \
  -v ./presets:/app/presets \
  docker.xuanyuan.run/adn182/node-sonos-http-api

注意: 使用--network host以确保API能发现Sonos设备（依赖UPnP协议）。

2. Docker Compose配置

yaml
version: '3'
services:
  sonos-api:
    image: docker.xuanyuan.run/adn182/node-sonos-http-api
    network_mode: host
    volumes:
      - ./settings.json:/app/settings.json
      - ./presets:/app/presets
    restart: unless-stopped

使用示例

• 获取所有Sonos区域: http://localhost:5005/zones
• 设置Living Room音量为15%: http://localhost:5005/Living%20Room/volume/15
• 暂停所有设备: http://localhost:5005/pauseall
• 发送TTS通知到所有设备: http://localhost:5005/sayall/Hello%20from%20Sonos%20API