核心功能
sonos-announce 是一款针对 Sonos 智能音箱系统的 Python 自动化工具，核心能力在于智能音频播报与状态恢复。它通过本地 HTTP 服务器向 Sonos 推送音频文件，播放完成后自动恢复之前的播放状态——包括精确 seek 到 Spotify 曲目的秒级位置、重新连接 Line-In/TV/蓝牙等外部输入。
显著优点
1. 智能状态保存与恢复：完整记录播放位置、队列状态、输入源类型，支持 Spotify/Apple Music/本地队列等主流源的精确恢复
2. 外部输入自动处理：自动识别并跳过无法暂停的 Line-In、TV(HDMI)、蓝牙等输入，播放结束后重新连接
3. 零配置发现：自动检测局域网 IP、Sonos 设备拓扑，支持多房间协调器(coordinator)管理
4. 跨平台支持：macOS/Linux/Windows 全平台兼容，自适应处理进程管理
5. 低延迟本地服务：内置轻量 HTTP 服务器(默认 8888 端口)，避免云端依赖
潜在局限
- 网络依赖：要求运行设备与 Sonos 处于同一局域网，跨 VLAN 或复杂网络架构可能失效
- 端口占用：HTTP 服务器需要独占端口，冲突时需手动配置
SONOS_HTTP_PORT - seek 限制：Spotify Radio、TuneIn、Pandora 等流式电台不支持精确位置恢复，只能从起始播放
- Python 生态依赖：需维护
soco库兼容性，Sonos API 变更可能导致 breakage - 无内置 TTS：仅为音频播放器，语音合成需外接 ElevenLabs、edge-tts 等服务
适合人群
- 智能家居自动化爱好者（Home Assistant、Node-RED 用户）
- 需要家庭广播/通知系统的多房间 Sonos 用户
- 开发语音助手、门铃提醒、日程播报等场景的技术人员
- 追求"播放不中断体验"的高级用户
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 网络暴露 | HTTP 服务绑定在 LAN IP，但仍存在局域网内未授权访问可能 | 建议结合防火墙规则限制访问源 |
| 状态竞争 | 高频调用时可能出现状态捕获与恢复的竞争条件 | 避免并发调用，添加调用间隔 |
| 音频劫持 | 恶意音频文件可被推送至全屋播放 | 严格校验 `media_dir` 路径，避免目录遍历 |
| 依赖失效 | `soco` 库维护状态或 Sonos API 变更 | 锁定依赖版本，关注上游更新 |