Ctrlable/ha-ctrlable-snapcast-tts

# 可控的 Snapcast TTS 流媒体服务器 将 Home Assistant Assist 的 TTS 响应路由到特定的 Snapcast 客户端——实现低延迟、按房间定向，且路由更改时无需修改固件。 ## 为什么需要 Home Assistant 的 `media_player.play_media` 在 HAOS 2026.5.x 中无法保持流式 TTS 行为。当 Piper 流式传输 TTS 输出时，标准路径会等待完整音频生成完毕才开始播放，从而产生明显的延迟。本项目通过 ESPHome 的 `on_intent_progress` 事件将 TTS 直接路由到 Snapcast 客户端——完全绕过 `media_player.play_media`——因此第一个音频字节在最后一部分生成前就会播放。 本项目解决的其他痛点： - 音乐助手广播路由需要逐卫星配置，当音箱移动时配置会失效。 - ESPHome 原生 TTS 仅在卫星设备上播放，无法在房间整体音箱上播放。 - 更改语音命令定向的房间通常需要刷新固件。 ## 架构 ``` ┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐ │ ESPHome Satellite │ │ HA Custom Integ. │ │ HAOS Add-on │ │ (Atom Echo etc.) │ │ ctrlable_snapcast_ │ │ ctrlable-snapcast- │ │ │ │ tts │ │ streamer │ │ on_intent_progress │──┬──▶│ │ │ │ │ fires homeassistant│ │ │ Service: │ │ HTTP endpoint: │ │ .service call with │ │ │ .announce │─────▶│ POST /announce │ │ url + satellite_id │ │ │ Owns mapping: │ │ │ │ + wake_word │ │ │ (sat_id, wake) → │ │ Snapcast JSON-RPC │ │ │ │ │ target snapclient │ │ topology mgmt │ │ on_tts_end (fallbk)│──┘ │ + UI config flow │ │ │ └─────────────────────┘ └──────────────────────┘ │ Per-client lock │ │ Stream PCM/MP3 to │ │ Snapcast TCP port │ │ Move client to │ │ announce group, │ │ play, restore │ └─────────┬───────────┘ │ ┌─────────▼───────────┐ │ Snapcast Server │ │ (existing LXC) │ │ Per-client streams │ │ + announce groups │ └─────────────────────┘ ``` 三个组件，一个安装链接： | 组件 | 功能 | |-----------|-------------| | **HAOS 插件** (`ctrlable-snapcast-streamer`) | 管理 Snapcast 拓扑，流式传输音频，暴露 HTTP API 和入口界面 | | **HA 集成** (`ctrlable_snapcast_tts`) | 管理卫星到 snapclient 的映射，暴露 `announce` 服务，提供配置界面 | | **ESPHome YAML 包** | 参考卫星配置（每设备 3 行替换内容） | ## 安装 ### 安装插件 1. 在 Home Assistant 中：**设置 → 插件 → 插件商店 → ⋮ → 仓库** 2. 粘贴地址：`https://github.com/Ctrlable/ha-ctrlable-snapcast-tts` 3. 在商店中找到 **Ctrlable Snapcast TTS Streamer** 并安装。 4. 配置插件的 Snapcast 服务器地址，然后启动。 5. 从插件的入口界面复制 Bearer 令牌。 ### 安装集成（通过 HACS） 1. 在 HACS 中：**⋮ → 自定义仓库** 2. 粘贴地址：`https://github.com/Ctrlable/ha-ctrlable-snapcast-tts`，分类：**集成** 3. 安装 **Ctrlable Snapcast TTS** 4. 重启 Home Assistant 5. 进入 **设置 → 设备与服务 → 添加集成** → 搜索 "Ctrlable Snapcast TTS" 6. 输入插件地址 (`http://localhost:8765`) 和上述步骤获取的 Bearer 令牌。 两者使用相同的仓库地址。一个链接，两种安装流程。 ## 配置 完整设置说明请参阅[安装文档](docs/installation.md)，包括： - Snapcast 服务器前置条件 - SSH 访问设置（用于文件编辑模式） - 卫星 ESPHome YAML - 映射配置 ## 刷写卫星设备 为每个卫星创建 YAML 配置（3 行替换内容）： ``` # 客厅卫星.yaml substitutions: name: ctrlable-living-room friendly_name: "Ctrlable Living Room" micro_wake_word_model: okay_nabu packages: ctrlable_base: !include packages/ctrlable_atom_echo_base.yaml ``` `name` 字段将成为路由映射中使用的 `satellite_id`。基础包和示例请参阅 [esphome/packages/](esphome/packages/)。 ## 与其他方案对比 | 功能 | 本项目 | 音乐助手 | ESPHome 原生 TTS | |---------|-------------|----------------|---------------------| | 低延迟流式 TTS | 是（绕过 play_media） | 否（缓冲） | 否（缓冲） | | 路由到 Snapcast 客户端 | 是 | 否 | 否 | | 无需刷写即可更改路由 | 是（界面映射） | 不适用 | 否 | | 多房间同步 | 是 (M4) | 通过 MA 房间 | 否 | | 无需音乐助手即可工作 | 是 | 必需 | 是 | ## 兼容性 | 组件 | 最低版本 | |-----------|----------------| | Home Assistant OS | 2026.5.1 | | Home Assistant | 2026.5.0 | | Snapcast 服务器 | 0.27+ | | ESPHome | 2025.5.0 | | ESP32 开发板 | M5Stack Atom Echo 或任何兼容板 | ## 许可证 Apache 2.0 — 详见 [LICENSE](LICENSE)。 由 [Ctrlable](https://ctrlable.com) 构建 — 面向酒店和商业空间的智能楼宇自动化解决方案。

标签：ESPHome开发, Home Assistant插件, Python脚本, Snapcast集成, UI可配置, 低延迟音频, 实时音频, 家庭自动化, 房间定向播放, 插件开发, 文本到语音, 无线扬声器, 智能家居, 智能音箱, 流媒体技术, 自定义集成, 语音助手, 语音命令处理, 路由系统, 逆向工具, 音频播放优化, 音频流