Home Assistant tts.speak 动作完全指南在媒体播放器上用 TTS 播报任意消息【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文聚焦 Home Assistant 官方文档中tts.speak动作Speak即 TTS 域的核心服务它把一段文本转成语音并在你指定的媒体播放器上播放。文档主体说明该动作的 UI 配置步骤、YAML 参数media_player_entity_id、message、cache、language、options、目标Target机制与实战自动化示例结合 TTS 集成文档 的缓存机制、首选音频格式preferred audio settings与 REST API 等实现细节进一步展开帮你从能发声走到稳定、快速地发声。动作定位文本变语音指定设备播放tts.speak是 Home Assistant 中面向媒体播放器的 TTS 播报动作。它的模型可以概括为两个实体各司其职TTS 实体target每个 text-to-speech 实体代表一个语音提供方speech provider代表一种声音。你选用哪个tts.xxx实体就用哪种音色/引擎合成语音。媒体播放器data真正发声的设备如media_player.kitchen。因此调用该动作时先用target选定 TTS 实体再在data里告诉它播到哪台播放器上。与之对应的旧式动作tts.say仅适用于通过 YAML 配置的遗留 TTS 平台通过 UI 配置 TTS 时一律使用tts.speak见 tts.say 文档。TTS 实体本身也有状态其 state 是文本转语音上次使用的时间戳可在Settings Tools States中查看通过用户界面使用 tts.speakHome Assistant 的 UI 会分步引导你完成该动作的配置无需编写 YAML进入Settings Automations scenes。打开一个已存在的自动化或脚本或选择Create automationCreate new automation。若是新建自动化在When部分添加触发器脚本不需要触发器由别的实体调用时运行。在Then do部分选择Add action。选择要控制的对象在By target下选择要使用的 text-to-speech 实体见下文动作的 Target。从该目标展示的动作列表中选择Speak。选择播放消息的Media player entity填写Message及其他可选项。点击Save。UI 中的选项选项说明是否必填Media player entity播放消息的媒体播放器。是Message要转换为语音的文本。是Cache将该消息缓存在本地下次请求相同文本时可更快生成输出。否Language播报消息所用的语言格式以 TTS 实体的要求为准。否Options特定于该 TTS 实体的附加设置如音色voice或音频格式。否在 YAML 中使用 tts.speak在 YAML 中该动作以tts.speak之名调用。一个基本示例如下action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen message: May the force be with you.这条动作使用tts.example实体合成语音并在media_player.kitchen上播放。YAML 参数说明参数类型必填默认值说明media_player_entity_idstring是—播放消息的媒体播放器。messagestring是—要转换为语音的文本。cacheboolean否true将合成结果缓存到本地相同文本再次请求时更快输出。languagestring否—播报所用语言格式须符合该 TTS 实体的要求。optionsmap否—该 TTS 实体支持的附加设置如音色、语速以及首选音频设置preferred audio settings。注意cache的默认值是true与旧式tts.say动作其cache默认false不同tts.speak默认开启缓存。options 中的首选音频设置options除了可以传该 TTS 集成自身支持的参数voice、speed 等具体要看你所用 TTS 集成的文档还可以包含一组首选音频设置用来解决播放器不支持 TTS 生成的音频格式这一常见问题。Home Assistant 会借助 FFmpeg 集成完成转码详见 TTS 集成的 Preferred audio settings 一节preferred_format音频格式。目标平台不支持时取值为文件扩展名如wav、mp3、ogg。preferred_sample_rate采样率Hz取 FFmpeg-ar参数支持的数值。preferred_sample_channels声道数取 FFmpeg-ac参数支持的数值。preferred_sample_bytes位深目前只能设为216 位采样其他值会被忽略。preferred_bitrate比特率kbps仅对 MP3 输出生效。默认以可变比特率编码 MP3指定该值后改为恒定比特率编码部分硬件解码器有这一要求。例如让消息以 MP3、22050Hz 输出action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen message: May the force be with you. options: preferred_format: mp3 preferred_sample_rate: 22050动作的 TargetTargets of the actiontts.speak必须有 target——target 是动作的作用对象。可以把动作指向单个实体、设备、区域、楼层或标签Home Assistant 会对该 target 背后匹配到的所有tts实体执行动作Entity某一个具体 TTS 实体如tts.living_room。Device属于某设备的每一个 TTS 实体。Area某房间/区域内的每一个 TTS 实体。Floor某楼层上的每一个 TTS 实体。Label共享某个标签的每一个 TTS 实体。同一个动作里还可以混选不同类型的 target例如同时指定一个具体实体和一个区域动作会对两者匹配到的 TTS 实体一并执行。缓存机制为什么同一条消息第二次更快缓存是tts.speak的默认行为其原理在 TTS 集成文档 中说明通过动作里的cache选项控制缓存开关True开启默认、False关闭。长期缓存落在文件系统上供媒体播放器快速响应的内存缓存会在一段时间后自动清理。如果想释放空间或强制重新合成所有消息可调用 tts.clear_cache 动作它删除全部已缓存的 TTS 文件并清空内存缓存且不带任何参数。不用写代码先验证Developer Tools 试跑不想先写 YAML 也可以直接试跑打开Settings Tools ActionsDeveloper Tools 的 Actions 页搜索tts.speak填入字段后点击Perform action即可在真实实体上观察效果。建议先用最小配置只填media_player_entity_id和message验证 TTS 实体与播放器是否配对正确再逐步叠加language、options。实战示例每天早晨播报天气把tts.speak放进定时自动化每天早上 07:00 在厨房播放器上播报当天天气触发器Time07:00动作SpeakTargettext-to-speech 实体Media player entityKitchenMessageGood morning. Todays weather is sunny.对应 YAMLautomation: alias: Speak the weather every morning triggers: - trigger: time at: 07:00:00 actions: - action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen message: Good morning. Todays weather is sunny.实际部署时可把message换成模板引用天气集成状态并确认tts.example替换为你在 UI 中配置好的真实 TTS 实体 ID。排错播放器不响、声音残缺怎么办tts.speak生成的音频通过 URL 发给媒体播放器播放问题多出在这一环。以下结论来自 TTS 集成的 Troubleshooting 章节优先保证本地 URL 可达。播放 TTS 媒体时会优先使用本地 Home Assistant URL在Settings System Network配置官方建议将其设为自动使生成的 URL 形如http://local_ip:local_port。自签名证书若内部 URL 走 SSL 且使用自签名证书tts动作会向设备发送https://URL设备校验证书失败后拒绝播放。许多媒体设备无法配置信任自签名证书此时只能改用http://向本地设备提供文件。Google Cast 设备Google Home、Chromecast这类设备用 Google 公共 DNS 解析媒体 URL 的主机名且不解析 mDNS 本地域名因此本地主机名如ha、homeassistant.local对它无效——用 IP 形式的内部 URL 可绕过使用 SSL 时证书又必须匹配证书中的主机名不能是 IP。最省事的办法就是不手动配置本地 Home Assistant URL。部分播放、杂音或完全无声通常是播放器不完全支持音频格式需要用options里的首选音频设置格式、声道、采样率、位深、比特率组合试验。文档给出了两个典型场景部分 Google Cast 设备在 22050Hz 采样时会跳过音频开头需把preferred_sample_rate设为44100部分设备拒绝可变比特率 MP3需把preferred_bitrate设为如48改为恒定比特率。相关的 TTS 动作tts.speak与以下动作配合使用均见各自文档tts.say面向通过 YAML 配置的遗留 TTS 平台的说消息动作按平台注册为tts.platform_say如tts.google_translate_say媒体播放器通过entity_id传入而非 target。tts.clear_cache清空全部 TTS 缓存文件与内存缓存用于释放空间或强制重新合成。此外TTS 域还暴露 REST APIPOST /api/tts_get_url传入engine_id实体 ID或platform加message即可取得生成 TTS 文件的 URL支持cache、language、options等与speak相同的参数适合在自动化之外的脚本或外部系统中直接消费语音文件。小结tts.speak的要点可以浓缩为四条target 决定用哪个声音media_player_entity_id决定从哪里出声cache默认开启让重复消息更快options中的首选音频设置负责让不兼容的播放器也能放。遇到有动作没声音时优先检查本地 URL 配置与音频格式兼容性而不是怀疑动作本身。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Home Assistant tts.speak 动作完全指南：在媒体播放器上用 TTS 播报任意消息
Home Assistant tts.speak 动作完全指南在媒体播放器上用 TTS 播报任意消息【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文聚焦 Home Assistant 官方文档中tts.speak动作Speak即 TTS 域的核心服务它把一段文本转成语音并在你指定的媒体播放器上播放。文档主体说明该动作的 UI 配置步骤、YAML 参数media_player_entity_id、message、cache、language、options、目标Target机制与实战自动化示例结合 TTS 集成文档 的缓存机制、首选音频格式preferred audio settings与 REST API 等实现细节进一步展开帮你从能发声走到稳定、快速地发声。动作定位文本变语音指定设备播放tts.speak是 Home Assistant 中面向媒体播放器的 TTS 播报动作。它的模型可以概括为两个实体各司其职TTS 实体target每个 text-to-speech 实体代表一个语音提供方speech provider代表一种声音。你选用哪个tts.xxx实体就用哪种音色/引擎合成语音。媒体播放器data真正发声的设备如media_player.kitchen。因此调用该动作时先用target选定 TTS 实体再在data里告诉它播到哪台播放器上。与之对应的旧式动作tts.say仅适用于通过 YAML 配置的遗留 TTS 平台通过 UI 配置 TTS 时一律使用tts.speak见 tts.say 文档。TTS 实体本身也有状态其 state 是文本转语音上次使用的时间戳可在Settings Tools States中查看通过用户界面使用 tts.speakHome Assistant 的 UI 会分步引导你完成该动作的配置无需编写 YAML进入Settings Automations scenes。打开一个已存在的自动化或脚本或选择Create automationCreate new automation。若是新建自动化在When部分添加触发器脚本不需要触发器由别的实体调用时运行。在Then do部分选择Add action。选择要控制的对象在By target下选择要使用的 text-to-speech 实体见下文动作的 Target。从该目标展示的动作列表中选择Speak。选择播放消息的Media player entity填写Message及其他可选项。点击Save。UI 中的选项选项说明是否必填Media player entity播放消息的媒体播放器。是Message要转换为语音的文本。是Cache将该消息缓存在本地下次请求相同文本时可更快生成输出。否Language播报消息所用的语言格式以 TTS 实体的要求为准。否Options特定于该 TTS 实体的附加设置如音色voice或音频格式。否在 YAML 中使用 tts.speak在 YAML 中该动作以tts.speak之名调用。一个基本示例如下action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen message: May the force be with you.这条动作使用tts.example实体合成语音并在media_player.kitchen上播放。YAML 参数说明参数类型必填默认值说明media_player_entity_idstring是—播放消息的媒体播放器。messagestring是—要转换为语音的文本。cacheboolean否true将合成结果缓存到本地相同文本再次请求时更快输出。languagestring否—播报所用语言格式须符合该 TTS 实体的要求。optionsmap否—该 TTS 实体支持的附加设置如音色、语速以及首选音频设置preferred audio settings。注意cache的默认值是true与旧式tts.say动作其cache默认false不同tts.speak默认开启缓存。options 中的首选音频设置options除了可以传该 TTS 集成自身支持的参数voice、speed 等具体要看你所用 TTS 集成的文档还可以包含一组首选音频设置用来解决播放器不支持 TTS 生成的音频格式这一常见问题。Home Assistant 会借助 FFmpeg 集成完成转码详见 TTS 集成的 Preferred audio settings 一节preferred_format音频格式。目标平台不支持时取值为文件扩展名如wav、mp3、ogg。preferred_sample_rate采样率Hz取 FFmpeg-ar参数支持的数值。preferred_sample_channels声道数取 FFmpeg-ac参数支持的数值。preferred_sample_bytes位深目前只能设为216 位采样其他值会被忽略。preferred_bitrate比特率kbps仅对 MP3 输出生效。默认以可变比特率编码 MP3指定该值后改为恒定比特率编码部分硬件解码器有这一要求。例如让消息以 MP3、22050Hz 输出action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen message: May the force be with you. options: preferred_format: mp3 preferred_sample_rate: 22050动作的 TargetTargets of the actiontts.speak必须有 target——target 是动作的作用对象。可以把动作指向单个实体、设备、区域、楼层或标签Home Assistant 会对该 target 背后匹配到的所有tts实体执行动作Entity某一个具体 TTS 实体如tts.living_room。Device属于某设备的每一个 TTS 实体。Area某房间/区域内的每一个 TTS 实体。Floor某楼层上的每一个 TTS 实体。Label共享某个标签的每一个 TTS 实体。同一个动作里还可以混选不同类型的 target例如同时指定一个具体实体和一个区域动作会对两者匹配到的 TTS 实体一并执行。缓存机制为什么同一条消息第二次更快缓存是tts.speak的默认行为其原理在 TTS 集成文档 中说明通过动作里的cache选项控制缓存开关True开启默认、False关闭。长期缓存落在文件系统上供媒体播放器快速响应的内存缓存会在一段时间后自动清理。如果想释放空间或强制重新合成所有消息可调用 tts.clear_cache 动作它删除全部已缓存的 TTS 文件并清空内存缓存且不带任何参数。不用写代码先验证Developer Tools 试跑不想先写 YAML 也可以直接试跑打开Settings Tools ActionsDeveloper Tools 的 Actions 页搜索tts.speak填入字段后点击Perform action即可在真实实体上观察效果。建议先用最小配置只填media_player_entity_id和message验证 TTS 实体与播放器是否配对正确再逐步叠加language、options。实战示例每天早晨播报天气把tts.speak放进定时自动化每天早上 07:00 在厨房播放器上播报当天天气触发器Time07:00动作SpeakTargettext-to-speech 实体Media player entityKitchenMessageGood morning. Todays weather is sunny.对应 YAMLautomation: alias: Speak the weather every morning triggers: - trigger: time at: 07:00:00 actions: - action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen message: Good morning. Todays weather is sunny.实际部署时可把message换成模板引用天气集成状态并确认tts.example替换为你在 UI 中配置好的真实 TTS 实体 ID。排错播放器不响、声音残缺怎么办tts.speak生成的音频通过 URL 发给媒体播放器播放问题多出在这一环。以下结论来自 TTS 集成的 Troubleshooting 章节优先保证本地 URL 可达。播放 TTS 媒体时会优先使用本地 Home Assistant URL在Settings System Network配置官方建议将其设为自动使生成的 URL 形如http://local_ip:local_port。自签名证书若内部 URL 走 SSL 且使用自签名证书tts动作会向设备发送https://URL设备校验证书失败后拒绝播放。许多媒体设备无法配置信任自签名证书此时只能改用http://向本地设备提供文件。Google Cast 设备Google Home、Chromecast这类设备用 Google 公共 DNS 解析媒体 URL 的主机名且不解析 mDNS 本地域名因此本地主机名如ha、homeassistant.local对它无效——用 IP 形式的内部 URL 可绕过使用 SSL 时证书又必须匹配证书中的主机名不能是 IP。最省事的办法就是不手动配置本地 Home Assistant URL。部分播放、杂音或完全无声通常是播放器不完全支持音频格式需要用options里的首选音频设置格式、声道、采样率、位深、比特率组合试验。文档给出了两个典型场景部分 Google Cast 设备在 22050Hz 采样时会跳过音频开头需把preferred_sample_rate设为44100部分设备拒绝可变比特率 MP3需把preferred_bitrate设为如48改为恒定比特率。相关的 TTS 动作tts.speak与以下动作配合使用均见各自文档tts.say面向通过 YAML 配置的遗留 TTS 平台的说消息动作按平台注册为tts.platform_say如tts.google_translate_say媒体播放器通过entity_id传入而非 target。tts.clear_cache清空全部 TTS 缓存文件与内存缓存用于释放空间或强制重新合成。此外TTS 域还暴露 REST APIPOST /api/tts_get_url传入engine_id实体 ID或platform加message即可取得生成 TTS 文件的 URL支持cache、language、options等与speak相同的参数适合在自动化之外的脚本或外部系统中直接消费语音文件。小结tts.speak的要点可以浓缩为四条target 决定用哪个声音media_player_entity_id决定从哪里出声cache默认开启让重复消息更快options中的首选音频设置负责让不兼容的播放器也能放。遇到有动作没声音时优先检查本地 URL 配置与音频格式兼容性而不是怀疑动作本身。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考