核心用法
sonos-announce 是一个基于 Python SoCo 库的 Sonos 智能音响控制技能，核心功能是实现音频播报与播放状态智能恢复。其主要工作流程为：启动本地 HTTP 服务器提供音频文件 → 将目标音频推送至 Sonos 群组播放 → 结束后自动恢复先前的播放状态。
关键特性：
- 智能状态捕获：保存播放 URI、进度位置、队列索引、播放状态等完整信息
- 精准续播：对 Spotify 曲目/播放列表可 seek 到秒级精确位置；网络电台类则从起始恢复
- 外部输入处理：自动识别 Line-In、TV/HDMI、蓝牙等不可暂停输入，直接重连而非尝试恢复
- 跨平台支持：macOS、Linux、Windows 全平台兼容，自动适配系统命令
API 设计简洁：announce(audio_file_path, wait_for_audio=True, media_dir=None)，支持默认媒体目录、自定义目录或完整路径三种调用模式。
显著优点
1. 无损用户体验：避免传统 TTS 播报后丢失播放进度的问题，特别适合背景音乐场景
2. 零配置发现：自动检测局域网 IP 和 Sonos 设备，无需手动指定 speaker IP
3. 群组感知：正确处理 Sonos 群组（coordinator）机制，避免重复控制
4. 流式服务兼容：针对 Spotify、TuneIn、Pandora、Tidal 等不同服务优化恢复策略
潜在局限
- 网络依赖：HTTP 服务器需要稳定的局域网连接，WiFi 波动可能导致播报失败
- 端口占用：默认 8888 端口可能被占用，需手动配置
SONOS_HTTP_PORT - 格式限制：依赖 ffprobe 检测时长，部分音频格式可能无法识别
- 非官方协议：基于 SoCo 逆向工程实现，Sonos 固件更新可能破坏兼容性
- 单播报场景：设计为短暂插播，不适合长时间音频（如播客）的"恢复"场景
适合人群
- 智能家居自动化开发者（Home Assistant、OpenClaw 等框架用户）
- 需要集成语音播报的企业/家庭场景（门铃、通知、警报系统）
- 娱乐场景开发者（音效板、游戏化互动）
常规风险
- 局域网暴露：HTTP 服务器监听 0.0.0.0，同一网络内其他设备可访问音频文件
- 状态竞态：若在播报期间用户手动操作 Sonos，恢复可能不准确
- 资源泄漏：异常退出时可能遗留 HTTP 后台进程（虽有
taskkill保护） - 版本锁定：SoCo 库更新可能引入 API 变更，建议固定版本部署