soundtouch-decloud

Bose 关停了 SoundTouch 云服务，导致音箱仅剩蓝牙、AUX、AirPlay 和多房间分区功能，却无法使用网络电台、预设、浏览和 Alexa。本仓库是一个 Claude Code 技能，引导用户将自己的音箱指向自托管的替代服务，从而恢复电台和预设。它面向非技术用户：该技能以询问而非命令的方式推进，可自由读取信息，并在对音箱做任何更改前要求确认。 替代服务是 gesellix 开发的 AfterTouch（Bose-SoundTouch），该技能将其视为权威依据；本仓库是一个技能，而非分支，安装的是已发布的容器镜像。前提条件是本地网络中有一台或多台 SoundTouch 音箱，同一网络中有一台支持 Docker 的机器（NAS、树莓派、小型 Linux 主机）并具有稳定地址，以及 Python 3.11+、uv 和带 compose 插件的 Docker。该技能的第一步会自行检查这些条件，并报告缺失项及安装命令。 安装通过 Claude Code 插件市场进行： /plugin marketplace add bitranox/soundtouch-decloud /plugin install soundtouch-decloud 也可以通过用通俗语言描述问题来触发，或按名称调用。工作流分阶段运行并设有确认点：前提条件检查与安装帮助、发现音箱、启动服务、在做出任何更改前备份每台音箱、重写四个服务 URL、等待电台源、恢复并验证电台、写入预设，最后通过实际聆听而非计数来证明播放正常。 该技能附带五个参考文件和四个脚本。每个脚本都会输出 JSON 封装结果，并使用一致的退出码（0 表示是，1 表示否，2 表示无法判断）；任何会更改音箱的操作都需要显式传入 --confirm，因此只读操作始终安全。脚本涵盖预检、Docker/compose 验证与服务健康检查、网络发现、通过诊断 SSH 端口进行引导并重写 URL 和重启，以及预设的备份/采集/验证/检查/恢复/相对化。 文档指出了容易被误诊的故障模式：桥接网络看似已安装却什么都发现不了（必须使用主机网络）；只重写账户 URL 会导致音箱能注册和同步但无法播放；URL 写入顺序至关重要，因为先持久化再写入会保存旧值，而命令仍会返回 OK；预设中的原始流 URL 会被接受但永远不会播放，因此预设使用 AfterTouch 的相对形式；复制来的服务会通过 settings.json 的 server_url 保留旧地址；由 DHCP 分配的服务地址日后会一次性破坏所有音箱。 电台恢复分四步：从迁移前的预设中采集流 URL（服务不会保留它们，因此必须先备份）、询问用户是否仍需要旧电台列表、为剩余电台查找当前可用的直接流端点，并从服务主机进行验证。验证会按按钮报告：audio、playlist、hls、not-audio、dead 或 missing。文档指出电台会迁移和失效，并且 .m3u 播放列表可能通过简单的音频检查却实际不含音频。 对于持续运行，该技能增加了每台音箱预设的服务外快照、一次性恢复，以及适合定时告警的只读检查。它刻意不安装任何会自行写入的内容，因为 AfterTouch v0.137.0 会在同一账户下的音箱之间共享预设。文档引用了实测数据：一个两分钟的恢复循环在 18.7 天内运行了 11692 次，仅写入预设一次；而一台休眠的 WiFi 音箱产生了 1303 次无法读取的读数，却从未缺少预设。该告警能区分预设缺失与音箱无响应。 脚本仅使用标准库，因此可在未安装任何内容的机器上运行；pytest 是唯一的测试依赖。仓库约定检查器会验证清单、技能 frontmatter、已发布脚本的测试覆盖率和行尾符，并在 Linux、Windows 和 macOS 上运行 CI。采用 MIT 许可证。