Dicklesworthstone/frankensonos · 上手攻略

  • 仓库：Dicklesworthstone/frankensonos
  • 链接：https://github.com/Dicklesworthstone/frankensonos
  • 分类：智能家居 · 音乐播放
  • 作者：Jay
  • 更新：2026-10-10

一、是什么

FrankenSonos 是一个用纯 Rust 编写的 Sonos 音箱本地控制器（fsonos 守护进程），通过 Sonos 音箱原生协议（SSDP 发现、UPnP/SOAP、GENA 事件）直接与音箱通信，支持 S1 和 S2 两代设备同时运行。它提供 CLI、HTTP API 和 MCP Server 三种接口，让 AI Agent 或任何能发 HTTP 请求的工具都能操控你的 Sonos 家庭音响系统。

核心特点：内存安全（#![forbid(unsafe_code)]）、不装任何东西到音箱上、不改音箱固件、Tailscale 网络下全球可访问。

⚠️ 当前为 pre-release（0.1.0 之前），接口可能变化，生产环境使用前请确认版本。

二、解决什么问题

Sonos 官方 App 长期体验不佳（App 丢音箱、分组冲突、自动化门槛高、S1 产品线已冻结）；S2 推进但两代设备无法统一管理。更关键的是 Spotify Web API 根本无法在 Sonos 上启动播放——官方 Spotify Connect 不支持按需播放。

FrankenSonos 直接绕过这些问题：用音箱自己说的协议（port 1400 上的 SOAP + GENA）来驱动它，不依赖官方 App，也不依赖 Spotify Connect，做到了 Spotify 真正的"点哪播哪"。

三、快速安装

前置依赖

  • Rust 工具链（如用 cargo 安装）：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Tailscale（如需远程访问）：已在运行的 Tailscale 网络
  • Spotify 账号（DJ 功能）：Spotify 开发者应用（免费创建）
  • espeak-ng / Piper（Announcements 离线语音，可选）
  • macOS say（macOS 平台可选）

安装方式一：下载预编译二进制（推荐）

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/frankensonos/main/install.sh | bash

# 或手动下载（GitHub Releases 页面查找最新版本）
# https://github.com/Dicklesworthstone/frankensonos/releases

安装方式二：cargo install（需 Rust）

cargo install fsonos

安装方式三：Docker（已有镜像）

# 参见 GitHub README 的 Docker 章节
docker run -d --network host uozi/nginx-ui:latest  # 注：frankensonos 本身无官方 Docker，但项目结构支持自建

📌 frankensonos 尚未发布正式 Release，二进制需从源码构建或等 pre-release 产出。

四、核心用法

4.1 首次配置

# 首次运行，引导式配置（音箱发现 + Spotify 登录 + Tailscale）
fsonos setup

# 检查音箱状态、Spotify 连接、监听器、Tailscale 链路，并给出问题修复建议
fsonos doctor

4.2 基础播放控制

# 播放 Spotify 链接（曲目、专辑、播放列表均可）
fsonos play spotify:track:xxxx Kitchen

# 暂停/恢复
fsonos pause Kitchen
fsonos resume Kitchen

# 音量调节
fsonos volume Kitchen 45        # 设为 45
fsonos volume Kitchen +5        # 增加 5
fsonos volume Kitchen -10       # 减少 10

# 静音
fsonos mute Kitchen

# 分组/取消分组
fsonos group Kitchen:Office     # 把 Office 加入 Kitchen 所在的组
fsonos ungroup Kitchen

4.3 Spotify DJ（核心亮点功能）

# 启动 DJ（从 Spotify 已点赞曲目中智能选曲播放）
fsonos dj start Kitchen --mood bright

# 查看当前 DJ 状态和选曲理由
fsonos dj status
fsonos dj why

# 调整风格（关键词、艺术家、年代、能量级别）
fsonos dj steer Kitchen --genre jazz --decade 1970s --energy high

# 古典音乐完整播放（每个乐章顺序播放）
fsonos dj steer Kitchen --composer mozart --period classical

# 点赞/踩（影响后续选曲）
fsonos dj like
fsonos dj dislike

# 跳过/停止
fsonos dj skip
fsonos dj stop

4.4 场景（Scenes）

# 保存当前状态（分组、音量、播放中内容）
fsonos scene save dinner

# 恢复场景（只推送实际需要的变更）
fsonos scene apply dinner

# 撤销上一步操作
fsonos undo

4.5 定时任务

# 添加定时任务（工作日早上 7:30 启动 bright 风格 DJ）
fsonos schedule add "weekdays 07:30" dj start Kitchen --mood bright

# 列出所有定时任务
fsonos schedule list

# 删除定时任务
fsonos schedule remove <id>

4.6 语音播报（Announcements）

# 文字转语音播报（支持 espeak-ng / Piper / macOS say）
fsonos say "Dinner is ready" --rooms Kitchen,Office

# 响铃提示
fsonos chime bell --rooms Kitchen

# 播放本地音频文件
fsonos announce --file /path/to/clip.wav --rooms Kitchen

4.7 MCP Server（AI Agent 接入）

# 启动 MCP Server（stdio 模式，供 AI Agent 调用）
fsonos mcp

# HTTP 模式（需配合 Tailscale Serve）
fsonos serve

MCP 工具有：sonos_play、sonos_pause、sonos_volume、sonos_mute、sonos_group、sonos_dj_* 等系列。

4.8 HTTP API（OpenAPI 文档自述）

# 启动 HTTP API（默认监听 localhost + Tailscale 地址）
fsonos serve

# 访问 OpenAPI 文档（浏览器打开）
open http://localhost:1407/docs

4.9 模拟环境（无音箱也能玩）

# 启动虚拟 S1 + S2 家庭（loopback 上的模拟音箱）
fsonos sim

# 然后所有命令照常运行，只是目标变为虚拟音箱

五、典型适用场景

  1. Sonos 家庭背景音乐自动化：定时启动 DJ、场景切换（"电影模式"把客厅分组+降音量、"晚餐模式"分区播放）
  2. AI Agent 语音控制家居：接入 MCP 的 AI 助手（Claude、GPT 等）直接用自然语言控制音箱
  3. Tailscale 远程控制：在公司/外地用手机 App 连上 Tailscale 网络，控制家里或办公室的 Sonos
  4. Spotify 播客式播放：从 Spotify 已点赞曲库中持续播放，不依赖 Sonos 官方 App 的算法
  5. 古典音乐完整播放：Sonos 官方 App 古典音乐常切乐章，FrankenSonos 按乐章顺序完整播放

六、坑与注意（§八 工程节）

  1. Tailscale 是远程访问唯一方式：没有 Tailscale 只能在局域网内使用（fsonos serve 默认只监听 loopback + Tailscale 地址，不暴露到公网）。如果没有 Tailscale 就别想了。

  2. DJ 只支持 Spotify（Apple Music/QQ 音乐等不支持）：项目明确只接入了 Spotify。Sonos 官方 Spotify Connect 根本无法"点哪播哪"，FrankenSonos DJ 的核心价值就是 Spotify 播控，但如果你用 Apple Music 就完全没用。

  3. pre-release 接口可能变化：文档注明 0.1.0 前接口可能修改，fsonos setup 配置格式、~/.config/fsonos/ 目录结构都可能随版本更新重建。建议锁定一个 commit SHA 使用。

  4. 真实硬件无 CI 覆盖：README 明确说"Live tests against real players exist but are opt-in; there is no real-hardware CI yet"。模拟器测试全覆盖，但实机只有用户自愿提交测试报告。

  5. 静默音量钳位（volume clamp）：音箱有 policy 音量上限，发送超过上限的音量命令会被静默钳位而不是报错——如果发现音量达不到你设的值，检查 policy.toml 配置。

  6. 分组协调者（Coordinator）语义：所有分组命令发送到组的协调音箱，不是子音箱；发到非协调者会被拒绝。fsonos group 文档要求指定协调者，先用 fsonos status 确认哪个是协调者。

  7. S1 和 S2 同时使用时 Room 名需加后缀：Room@S1 / Room@S2 区分同名音箱，配置别名（fsonos rooms alias add）可以简化命名。

  8. say 命令依赖系统 TTS 引擎：Linux 上需要 espeak-ng 或 Piper，macOS 用自带 say。安装后如播报无声，先 fsonos doctor 排查 TTS 依赖。

  9. Announcements 播报结束后音量/音乐状态恢复：policy 控制恢复逻辑，但若音箱在播报期间被手动操作，恢复行为可能不符合预期。

七、与同类对比

工具 语言 协议 Spotify 播放 MCP 远程访问 成熟度
FrankenSonos Rust 直接 SOAP/GENA ✅ 完整 ✅ Tailscale Pre-release
SoCo（Python） Python 直接 SOAP ✅ ❌ 需反向代理 成熟稳定
soco-ms익스프레스 — — 部分 ❌ 受限 停更
Sonos 官方 App — 云 ✅（Spotify Connect） ❌ ✅（官方云） 官方，App 体验差

SoCo 是最成熟的 Python 替代品，生态丰富；但 FrankenSonos 的 Rust 内存安全保证、DJ 功能深度集成（不只是播歌，是"智能选曲+学习"）、MCP Server 原生支持是差异化亮点。

八、一句话推荐结论

如果你在 Tailscale 网络下使用 Sonos、需要 AI Agent 控制或 Spotify 深度 DJ 功能，FrankenSonos 是目前唯一一个内存安全、原生 MCP、DJ 智能化全做到的本地方案——pre-release 阶段有小变动风险，但技术选型值得押注。