Home Assistant 与 Music Assistant 集成指南使用 music_assistant.play_announcement 播放语音通知与提示音【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇文章聚焦 Home Assistant 官方文档中定义的music_assistant.play_announcement动作讲解如何在 Music Assistant 媒体播放器上从 URL 播放公告音频例如检测到有人移动时播放门铃声并详细说明 UI 与 YAML 两种配置方式下的全部参数、目标选择机制以及实战自动化示例。读完本文你将能够在自动化与脚本中可靠地实现提示音 公告 强制音量的完整播报流程。动作概览何时使用 play_announcementmusic_assistant.play_announcement是 Home Assistant 中 Music Assistant 集成提供的专用动作用于在指定的 MA 播放器上播放一段来自 URL 的公告音频。它与此前常用的media_player.play_media相比更强调公告这一语义场景可以同时指定预公告音pre-announce sound和公告音量announce volume让通知在任意播放状态下都能清晰、可预期地播出。在官方文档的原始定义中该动作的典型用例是当传感器检测到动作时在客厅音箱上播放门铃声。如果希望播报的是文字内容如有人来访则应改用 Home Assistant 的 text-to-speech 动作将文字先合成为语音再播放而不是直接调用本动作。需要注意的是该动作要求环境中已正确安装并配置 Music Assistant 集成music_assistant所有 MA 播放器与分组都会以 media player 实体 的形式出现在 Home Assistant 中本动作的目标对象正是这些实体。根据集成文档 source/_integrations/music_assistant.markdown集成还提供了公告期间自动暂停当前播放等增强能力这正是选择 MA 播放器做公告而非直接驱动底层设备的原因。在自动化或脚本中使用该动作该动作的完整 UI 操作路径对应文档中的actions/ui_header.md通用流程如下进入Settings Automations scenes自动化与场景。打开一个已有的自动化或脚本或选择Create automationCreate new automation新建。如果是新建自动化在When当…时部分添加触发器脚本无需触发器它们由其他自动化或流程调用时才会执行。在Then do则执行部分选择Add action添加动作。在By target目标选择下选中要播放公告的 Music Assistant 媒体播放器详见下文 动作的目标。从该目标对应的动作列表中选择Play announcement播放公告。填写需要使用的选项。选择Save保存。UI 中的选项UI 选项说明URL公告音频的 URL 地址。Use pre-announce启用后会在正式公告之前先播放一段预公告提示音。Pre-announce URL预公告提示音的 URL 地址。Announce volume为公告强制指定的音量等级留空则使用播放器默认音量。YAML 中的基本示例在 YAML 中该动作以music_assistant.play_announcement引用。官方文档给出的基本示例如下action: music_assistant.play_announcement target: entity_id: media_player.kitchen_speaker data: url: http://example.com/doorbell.mp3这段配置的作用是在media_player.kitchen_speaker这台 MA 播放器上播放http://example.com/doorbell.mp3这段音频。YAML 参数详解参数必填类型默认值说明url是string—公告音频的 URL 地址。use_pre_announce否booleanfalse设为true时在正式公告前播放一段预公告提示音。pre_announce_url否string—预公告提示音的 URL 地址。announce_volume否integer—为公告强制指定的音量等级取值范围1 到 100省略该参数则使用播放器默认音量。几点实务提示url是唯一必填参数其余均为可选这使该动作可以极简调用只传一个音频 URL。announce_volume的强制音量特性非常适合在深夜静音模式或音乐播放中等场景下确保通知能被听到但取值必须落在 1–100 的整数区间内。预公告pre-announce机制常用于先以短提示音吸引注意力、再播放完整公告的组合播报use_pre_announce与pre_announce_url搭配使用仅开启开关而不提供 URL 时行为取决于 Music Assistant 服务端的默认提示音配置。动作的目标Targets该动作必须指定目标target目标即动作的作用对象。可以指向单个实体、设备、区域、楼层或标签Home Assistant 会对目标下所有匹配的media_player实体执行动作对应仓库中的 actions/targets.mdEntity实体单个media_player实体例如media_player.kitchen_speaker。Device设备某个设备下属的所有media_player实体。Area区域某个房间/区域内的所有media_player实体。Floor楼层某个楼层上的所有media_player实体。Label标签共享某个标签的所有media_player实体。同一动作可以混合选择多种目标类型例如同时指定一个具体实体和一个区域动作会在这两者上同时执行。这意味着一个自动化即可完成全屋播报只需把目标设为一个包含所有播放器的区域或标签而不必逐一枚举实体 ID。实战示例检测到动作时播放门铃公告结合文档的原始用例下面给出一个完整的自动化 YAML它把动作检测 → 播放门铃公告 → 强制音量串成一条可落地的链路automation: alias: Play doorbell announcement on motion triggers: - trigger: state entity_id: binary_sensor.front_door_motion to: on actions: - action: music_assistant.play_announcement target: area: living_room data: url: http://example.com/doorbell.mp3 use_pre_announce: true pre_announce_url: http://example.com/chime.mp3 announce_volume: 70进阶示例公告前暂停当前音乐并播报文字通知如果需要在公告中播报文字例如洗衣机已洗完可以先用tts.speak动作生成语音再交由 MA 播放器播出。官方在 tts.speak 动作文档 中提供了每天早晨播报天气的自动化范式可仿照其结构扩展为洗衣完成播报automation: alias: Announce laundry is done on kitchen speaker triggers: - trigger: state entity_id: sensor.washing_machine_status to: idle actions: - action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen_speaker message: The laundry is done注意tts.speak与music_assistant.play_announcement的定位不同——前者面向文字转语音需要配置 TTS 实体后者面向URL 音频公告支持预公告与强制音量。若希望文字播报同样具备暂停当前播放、强制音量的公告语义更推荐将 TTS 服务产出的音频 URL 传给music_assistant.play_announcement的url参数。在线调试无需写 YAML 直接测试在Settings Tools Actions工具 动作中搜索music_assistant.play_announcement填写字段后点击Perform action即可在真实实体上立即观察效果对应仓库中的 actions/try_it.md。这是验证音频 URL 是否可访问、音量参数是否生效的最快路径也便于在编写自动化前先确认目标播放器的行为。常见问题与排查如果动作执行没有效果可按以下顺序排查集成是否已安装UI 编辑器中找不到任何 Music Assistant 动作通常意味着 Home Assistant 中尚未安装该集成app 与集成是两回事。请前往Settings Devices services添加 Music Assistant 集成参见集成文档的 配置章节。集成要求 Music Assistant 服务端版本2.4 或以上可运行在 Home Assistant 应用内或独立 Docker 容器中。目标是否正确确认target中的entity_id/area/label确实对应 MA 播放器实体。集成会自动为 MA 中所有播放器与分组包括从 Home Assistant 导入的播放器创建media_player实体。URL 是否可达播放器需要能通过网络访问url与pre_announce_url指向的资源注意检查内网地址、端口与鉴权问题。音量是否被覆盖若announce_volume设置的值过低可能导致公告无声先省略该参数以播放器默认音量测试。相关动作music_assistant.play_announcement经常与以下动作配合使用对应文档 front matter 中声明的相关动作Play media在 MA 播放器上播放媒体支持一次入队多个条目、指定音轨/专辑、启用电台模式等精细控制当需要在公告之后继续播放音乐时可在公告结束后调用它恢复播放。Transfer queue将播放队列从一个播放器转移到另一个播放器适合音乐跟着人走的多房间场景。总结music_assistant.play_announcement是 Home Assistant 生态中面向 Music Assistant 播放器的公告级播报动作通过url播放任意音频通过use_pre_announce/pre_announce_url实现提示音 正文的两段式播报通过announce_volume1–100强制公告音量配合实体/设备/区域/楼层/标签五种目标类型可轻松实现单点或全屋通知。需要播报文字时则与tts.speak或 TTS 集成组合使用。官方文档原文见 source/_actions/music_assistant.play_announcement.markdown集成背景与实体模型可进一步阅读 Music Assistant 集成文档。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Home Assistant 与 Music Assistant 集成指南：使用 music_assistant.play_announcement 播放语音通知与提示音
Home Assistant 与 Music Assistant 集成指南使用 music_assistant.play_announcement 播放语音通知与提示音【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇文章聚焦 Home Assistant 官方文档中定义的music_assistant.play_announcement动作讲解如何在 Music Assistant 媒体播放器上从 URL 播放公告音频例如检测到有人移动时播放门铃声并详细说明 UI 与 YAML 两种配置方式下的全部参数、目标选择机制以及实战自动化示例。读完本文你将能够在自动化与脚本中可靠地实现提示音 公告 强制音量的完整播报流程。动作概览何时使用 play_announcementmusic_assistant.play_announcement是 Home Assistant 中 Music Assistant 集成提供的专用动作用于在指定的 MA 播放器上播放一段来自 URL 的公告音频。它与此前常用的media_player.play_media相比更强调公告这一语义场景可以同时指定预公告音pre-announce sound和公告音量announce volume让通知在任意播放状态下都能清晰、可预期地播出。在官方文档的原始定义中该动作的典型用例是当传感器检测到动作时在客厅音箱上播放门铃声。如果希望播报的是文字内容如有人来访则应改用 Home Assistant 的 text-to-speech 动作将文字先合成为语音再播放而不是直接调用本动作。需要注意的是该动作要求环境中已正确安装并配置 Music Assistant 集成music_assistant所有 MA 播放器与分组都会以 media player 实体 的形式出现在 Home Assistant 中本动作的目标对象正是这些实体。根据集成文档 source/_integrations/music_assistant.markdown集成还提供了公告期间自动暂停当前播放等增强能力这正是选择 MA 播放器做公告而非直接驱动底层设备的原因。在自动化或脚本中使用该动作该动作的完整 UI 操作路径对应文档中的actions/ui_header.md通用流程如下进入Settings Automations scenes自动化与场景。打开一个已有的自动化或脚本或选择Create automationCreate new automation新建。如果是新建自动化在When当…时部分添加触发器脚本无需触发器它们由其他自动化或流程调用时才会执行。在Then do则执行部分选择Add action添加动作。在By target目标选择下选中要播放公告的 Music Assistant 媒体播放器详见下文 动作的目标。从该目标对应的动作列表中选择Play announcement播放公告。填写需要使用的选项。选择Save保存。UI 中的选项UI 选项说明URL公告音频的 URL 地址。Use pre-announce启用后会在正式公告之前先播放一段预公告提示音。Pre-announce URL预公告提示音的 URL 地址。Announce volume为公告强制指定的音量等级留空则使用播放器默认音量。YAML 中的基本示例在 YAML 中该动作以music_assistant.play_announcement引用。官方文档给出的基本示例如下action: music_assistant.play_announcement target: entity_id: media_player.kitchen_speaker data: url: http://example.com/doorbell.mp3这段配置的作用是在media_player.kitchen_speaker这台 MA 播放器上播放http://example.com/doorbell.mp3这段音频。YAML 参数详解参数必填类型默认值说明url是string—公告音频的 URL 地址。use_pre_announce否booleanfalse设为true时在正式公告前播放一段预公告提示音。pre_announce_url否string—预公告提示音的 URL 地址。announce_volume否integer—为公告强制指定的音量等级取值范围1 到 100省略该参数则使用播放器默认音量。几点实务提示url是唯一必填参数其余均为可选这使该动作可以极简调用只传一个音频 URL。announce_volume的强制音量特性非常适合在深夜静音模式或音乐播放中等场景下确保通知能被听到但取值必须落在 1–100 的整数区间内。预公告pre-announce机制常用于先以短提示音吸引注意力、再播放完整公告的组合播报use_pre_announce与pre_announce_url搭配使用仅开启开关而不提供 URL 时行为取决于 Music Assistant 服务端的默认提示音配置。动作的目标Targets该动作必须指定目标target目标即动作的作用对象。可以指向单个实体、设备、区域、楼层或标签Home Assistant 会对目标下所有匹配的media_player实体执行动作对应仓库中的 actions/targets.mdEntity实体单个media_player实体例如media_player.kitchen_speaker。Device设备某个设备下属的所有media_player实体。Area区域某个房间/区域内的所有media_player实体。Floor楼层某个楼层上的所有media_player实体。Label标签共享某个标签的所有media_player实体。同一动作可以混合选择多种目标类型例如同时指定一个具体实体和一个区域动作会在这两者上同时执行。这意味着一个自动化即可完成全屋播报只需把目标设为一个包含所有播放器的区域或标签而不必逐一枚举实体 ID。实战示例检测到动作时播放门铃公告结合文档的原始用例下面给出一个完整的自动化 YAML它把动作检测 → 播放门铃公告 → 强制音量串成一条可落地的链路automation: alias: Play doorbell announcement on motion triggers: - trigger: state entity_id: binary_sensor.front_door_motion to: on actions: - action: music_assistant.play_announcement target: area: living_room data: url: http://example.com/doorbell.mp3 use_pre_announce: true pre_announce_url: http://example.com/chime.mp3 announce_volume: 70进阶示例公告前暂停当前音乐并播报文字通知如果需要在公告中播报文字例如洗衣机已洗完可以先用tts.speak动作生成语音再交由 MA 播放器播出。官方在 tts.speak 动作文档 中提供了每天早晨播报天气的自动化范式可仿照其结构扩展为洗衣完成播报automation: alias: Announce laundry is done on kitchen speaker triggers: - trigger: state entity_id: sensor.washing_machine_status to: idle actions: - action: tts.speak target: entity_id: tts.example data: media_player_entity_id: media_player.kitchen_speaker message: The laundry is done注意tts.speak与music_assistant.play_announcement的定位不同——前者面向文字转语音需要配置 TTS 实体后者面向URL 音频公告支持预公告与强制音量。若希望文字播报同样具备暂停当前播放、强制音量的公告语义更推荐将 TTS 服务产出的音频 URL 传给music_assistant.play_announcement的url参数。在线调试无需写 YAML 直接测试在Settings Tools Actions工具 动作中搜索music_assistant.play_announcement填写字段后点击Perform action即可在真实实体上立即观察效果对应仓库中的 actions/try_it.md。这是验证音频 URL 是否可访问、音量参数是否生效的最快路径也便于在编写自动化前先确认目标播放器的行为。常见问题与排查如果动作执行没有效果可按以下顺序排查集成是否已安装UI 编辑器中找不到任何 Music Assistant 动作通常意味着 Home Assistant 中尚未安装该集成app 与集成是两回事。请前往Settings Devices services添加 Music Assistant 集成参见集成文档的 配置章节。集成要求 Music Assistant 服务端版本2.4 或以上可运行在 Home Assistant 应用内或独立 Docker 容器中。目标是否正确确认target中的entity_id/area/label确实对应 MA 播放器实体。集成会自动为 MA 中所有播放器与分组包括从 Home Assistant 导入的播放器创建media_player实体。URL 是否可达播放器需要能通过网络访问url与pre_announce_url指向的资源注意检查内网地址、端口与鉴权问题。音量是否被覆盖若announce_volume设置的值过低可能导致公告无声先省略该参数以播放器默认音量测试。相关动作music_assistant.play_announcement经常与以下动作配合使用对应文档 front matter 中声明的相关动作Play media在 MA 播放器上播放媒体支持一次入队多个条目、指定音轨/专辑、启用电台模式等精细控制当需要在公告之后继续播放音乐时可在公告结束后调用它恢复播放。Transfer queue将播放队列从一个播放器转移到另一个播放器适合音乐跟着人走的多房间场景。总结music_assistant.play_announcement是 Home Assistant 生态中面向 Music Assistant 播放器的公告级播报动作通过url播放任意音频通过use_pre_announce/pre_announce_url实现提示音 正文的两段式播报通过announce_volume1–100强制公告音量配合实体/设备/区域/楼层/标签五种目标类型可轻松实现单点或全屋通知。需要播报文字时则与tts.speak或 TTS 集成组合使用。官方文档原文见 source/_actions/music_assistant.play_announcement.markdown集成背景与实体模型可进一步阅读 Music Assistant 集成文档。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考