Home Assistant Music Assistant 集成使用music_assistant.search动作跨库全量搜索音乐【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读music_assistant.search是 Home Assistant 中 Music AssistantMA集成提供的一个搜索动作它能够同时对 Music Assistant 库以及所有已连接的音乐提供商执行全局检索并将结果通过响应变量response variable返回给自动化或脚本的后续步骤。本文将基于 source/_actions/music_assistant.search.markdown 完整梳理该动作的 UI 与 YAML 两种用法、全部参数说明、返回数据结构并结合仓库中的music_assistant.get_library、music_assistant.play_media等关联动作给出可复制的端到端搜索播放示例帮助你构建任意曲目都能被找到并播放的搜索型仪表盘或语音控制流程。动作概览一次搜索覆盖全部音乐来源从 source/_actions/music_assistant.search.markdown 的定义可以看到该动作的核心定位是搜索范围同时检索 Music Assistant 库和所有已连接的提供商provider即本地库与 Spotify、Tidal 等流媒体源一起查程序化访问返回整个音乐目录的检索结果可用于构建找到即播的界面纯查询语义结果通过响应变量返回不会改变任何播放器状态也不会在播放器上产生副作用无目标target与music_assistant.play_media不同该动作不支持指定区域、设备、实体或标签实例通过config_entry_id或 UI 中的Music Assistant instance选项选择。该动作的前端标题为Music Assistant: Search Music Assistant域domain为music_assistant。要使用它前提是已经安装并配置好 Music Assistant 集成详见 source/_integrations/music_assistant.markdown 中集成安装与手动配置部分该集成要求 Music Assistant Server 2.4 或更高版本。在 UI 中使用搜索动作操作步骤在可视化编辑器中配置自动化或脚本Home Assistant 会逐步引导你完成配置进入Settings Automations scenes。打开一个现有的自动化或脚本或选择Create automation Create new automation。如果是新建自动化在When部分添加一个触发器脚本则不需要触发器它们在被其他东西调用时运行。在Then do部分选择Add action。在搜索框中搜索并选择Music Assistant: Search Music Assistant。填写你要使用的选项。在Response variable字段中输入一个变量名例如search_results来存储返回的搜索结果数据。选择Save。由于该动作不支持目标UI 中不会提示你选择区域、设备、实体或标签而是通过Music Assistant instance选项指定要搜索的 MA 实例。UI 中的选项说明UI 选项说明Music Assistant instance要在其上执行搜索的 Music Assistant 实例。Search name要搜索的名称或标题。Media type(s)要搜索的内容类型例如 artist艺术家、album专辑、track曲目、radio电台或 playlist播放列表。省略时搜索所有类型。Artist name当在 Search name 字段中指定曲目或专辑名称时可选的用于按此艺术家名称限制结果。Album name当在 Search name 字段中指定曲目名称时可选的用于按此专辑名称限制结果。Limit每种媒体类型最多返回的项目数。Only library items仅包含在库中的结果。Username在指定 Music Assistant 用户的库中搜索。如果该用户配置了提供商过滤provider filtering结果将相应地过滤。在 YAML 中使用搜索动作基本示例在 YAML 中该动作以music_assistant.search引用。以下是一个基础示例取自原文档并保持可运行action: music_assistant.search data: config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV name: We Are The Champions response_variable: search_results关键点说明config_entry_id是必填项指向具体的 MA 实例。文档给出的获取技巧是在可视化编辑器的下拉框中选中实例然后切换到 YAML 模式读取生成的 ID 值。name是必填的搜索词此处传入曲目名称We Are The Champions。response_variable用于将结果存入后续步骤可读取的变量search_results。YAML 选项全参考根据原文档的{% options_yaml %}块各字段定义如下YAML 字段必填类型默认值说明config_entry_id是string—要在其上执行搜索的 Music Assistant 实例的 ID。name是string—要搜索的名称或标题。media_type否string / list全部类型要搜索的内容类型。可选值artist、album、audiobook、playlist、podcast、track、radio。可传多个省略时搜索所有类型。artist否string—当name指定的是曲目或专辑名称时可选的用于按艺术家名称限制结果。album否string—当name指定的是曲目名称时可选的用于按专辑名称限制结果。limit否integer5每种媒体类型最多返回的项目数。library_only否booleanfalse仅包含在库中的结果。username否string—在指定 Music Assistant 用户的库中搜索。若该用户配置了提供商过滤结果会相应过滤。对比可见UI 中名为 Media type(s)、Artist name、Album name、Only library items 的选项在 YAML 中分别对应media_type、artist、album、library_only编写 YAML 自动化时需使用后者。组合搜索条件的进阶用法利用media_type支持列表的特性可以一次性限定多种类型并用artist/album缩小范围action: music_assistant.search data: config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV name: Bohemian Rhapsody media_type: - track - album artist: Queen limit: 10 response_variable: search_results此例在 Queen 的艺术家人名下同时搜索曲目与专辑每种类型最多返回 10 条。需要说明的是UI 选项中 Media type(s) 同样支持多选其含义与 YAML 列表一致。理解响应数据与response_variable返回结构与可消费字段该动作返回按媒体类型分组的匹配项列表包括artists、albums、tracks、playlists、radio、audiobooks和podcasts。每个项目都包含诸如名称name和 URI 之类的详细信息。其中URI 是打通搜索 → 播放链路的关键文档明确指出这些 URI 可以直接传给 Play media 动作使用。这与 source/_integrations/music_assistant.markdown 中的说明一致——media_player.browse_media和搜索/库类动作产出的library://artist/1、spotify://album/5zj4Ej0FrlJQaSo0d6cttH这类 URI 可直接用于播放。另外从 source/_actions/music_assistant.play_media.markdown 可知play_media的media_id可以接受曲目/艺术家/专辑名称、spotify://artist/12345这类提供商 URI甚至提供商网页 URL与搜索返回的 URI 天然兼容。响应变量的使用机制response_variable是 Home Assistant 脚本/自动化中让动作把结果交还给调用方的标准机制。根据 source/_docs/scripts.markdown 的说明脚本可通过response_variable选项返回响应数据响应数据必须是键/值映射也可配合stop指令返回。在本动作的场景中response_variable: search_results意味着后续步骤可以直接引用search_results中的items或按类型分组的结果如search_results[tracks]。一个典型的消费方式是把返回的 URI 列表喂给music_assistant.play_media。下面的脚本示例演示了完整的搜索 → 播放链路参考 source/_actions/music_assistant.get_library.markdown 中随机播放的写法将其中的库查询替换为搜索script: sequence: - action: music_assistant.search data: config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV name: Queen media_type: track limit: 5 response_variable: search_results - action: music_assistant.play_media target: entity_id: media_player.kitchen_speaker data: media_id: {{ search_results[tracks] | map(attributeuri) | list }} media_type: track enqueue: replace该脚本先搜索与 Queen 相关的 5 首曲目再把返回结果中的uri列表通过 Jinja 模板映射出来交给music_assistant.play_media在media_player.kitchen_speaker上以replace替换队列方式播放。这里的map(attributeuri)用法与get_library文档中处理items的写法同构可直接套用。与关联动作的配合music_assistant.search在文档的related_actions中声明了两个高频搭配动作Get library items检索 Music Assistant 库中的项目适合从库中取数据而非跨提供商搜索的场景。它同样返回响应变量、不支持目标支持media_type、favorite、search、limit、offset、order_by、album_type、album_artists_only、username等参数详见 source/_actions/music_assistant.get_library.markdown。例如取 10 首随机曲目可用order_by: random。Play media在 MA 播放器上播放媒体支持一次入队多个项目、指向特定曲目或专辑、开启 radio mode 自动填充相似曲目以及通过enqueueplay/replace/next/replace_next/add精细控制队列行为。media_id支持名称、名称艺术家、提供商 URI 或提供商 URL 等多种形态详见 source/_actions/music_assistant.play_media.markdown。三者构成一个常见的工作流闭环用search跨源检索 → 用get_library从库内筛选 → 用play_media播放。其中search与get_library都是查询型动作返回响应变量、不改播放器而play_media是执行型动作作用于指定播放器目标。常见注意事项实例 ID 的获取config_entry_id没有直观的 UI 对应输入框推荐做法是在可视化编辑器中从下拉框选择实例再切到 YAML 模式复制生成的 ID。library_only与username的配合library_only: true时结果仅限 MA 库内项目username可指定在某个 MA 用户视角下搜索——若该用户配置了提供商过滤provider filtering返回结果会被相应过滤。这一点在 source/_integrations/music_assistant.markdown 的说明中也有体现MA 的用户级提供商过滤会影响媒体选择例如有声书的续播点resume point获取。当从自动化或脚本发起请求时建议显式设置username让请求归属于正确的用户。Radio mode 的限制若想基于搜索结果开启 radio mode在play_media中设置radio_mode: true需要注意并非所有音乐提供商都支持在不支持的提供商项目上启用会报错详见 source/_integrations/music_assistant.markdown 的 Known limitations。结果分组的类型边界返回分组类型artists、albums、tracks、playlists、radio、audiobooks、podcasts与media_type可选值artist、album、audiobook、playlist、podcast、track、radio一一对应编写 Jinja 模板时可按需取用对应的分组键。小结music_assistant.search是 Home Assistant 中连接 Music Assistant 全量音乐目录的查询入口它以config_entry_id指定实例以name为必填搜索词通过media_type、artist、album、limit、library_only、username等参数精细控制检索范围并将按媒体类型分组的搜索结果通过response_variable交还自动化/脚本。配合music_assistant.play_media的 URI 播放能力即可实现搜索任意曲目并立即播放的完整链路与music_assistant.get_library组合则能同时覆盖跨提供商搜索与库内浏览两类需求。【免费下载链接】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.search` 动作跨库全量搜索音乐
Home Assistant Music Assistant 集成使用music_assistant.search动作跨库全量搜索音乐【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读music_assistant.search是 Home Assistant 中 Music AssistantMA集成提供的一个搜索动作它能够同时对 Music Assistant 库以及所有已连接的音乐提供商执行全局检索并将结果通过响应变量response variable返回给自动化或脚本的后续步骤。本文将基于 source/_actions/music_assistant.search.markdown 完整梳理该动作的 UI 与 YAML 两种用法、全部参数说明、返回数据结构并结合仓库中的music_assistant.get_library、music_assistant.play_media等关联动作给出可复制的端到端搜索播放示例帮助你构建任意曲目都能被找到并播放的搜索型仪表盘或语音控制流程。动作概览一次搜索覆盖全部音乐来源从 source/_actions/music_assistant.search.markdown 的定义可以看到该动作的核心定位是搜索范围同时检索 Music Assistant 库和所有已连接的提供商provider即本地库与 Spotify、Tidal 等流媒体源一起查程序化访问返回整个音乐目录的检索结果可用于构建找到即播的界面纯查询语义结果通过响应变量返回不会改变任何播放器状态也不会在播放器上产生副作用无目标target与music_assistant.play_media不同该动作不支持指定区域、设备、实体或标签实例通过config_entry_id或 UI 中的Music Assistant instance选项选择。该动作的前端标题为Music Assistant: Search Music Assistant域domain为music_assistant。要使用它前提是已经安装并配置好 Music Assistant 集成详见 source/_integrations/music_assistant.markdown 中集成安装与手动配置部分该集成要求 Music Assistant Server 2.4 或更高版本。在 UI 中使用搜索动作操作步骤在可视化编辑器中配置自动化或脚本Home Assistant 会逐步引导你完成配置进入Settings Automations scenes。打开一个现有的自动化或脚本或选择Create automation Create new automation。如果是新建自动化在When部分添加一个触发器脚本则不需要触发器它们在被其他东西调用时运行。在Then do部分选择Add action。在搜索框中搜索并选择Music Assistant: Search Music Assistant。填写你要使用的选项。在Response variable字段中输入一个变量名例如search_results来存储返回的搜索结果数据。选择Save。由于该动作不支持目标UI 中不会提示你选择区域、设备、实体或标签而是通过Music Assistant instance选项指定要搜索的 MA 实例。UI 中的选项说明UI 选项说明Music Assistant instance要在其上执行搜索的 Music Assistant 实例。Search name要搜索的名称或标题。Media type(s)要搜索的内容类型例如 artist艺术家、album专辑、track曲目、radio电台或 playlist播放列表。省略时搜索所有类型。Artist name当在 Search name 字段中指定曲目或专辑名称时可选的用于按此艺术家名称限制结果。Album name当在 Search name 字段中指定曲目名称时可选的用于按此专辑名称限制结果。Limit每种媒体类型最多返回的项目数。Only library items仅包含在库中的结果。Username在指定 Music Assistant 用户的库中搜索。如果该用户配置了提供商过滤provider filtering结果将相应地过滤。在 YAML 中使用搜索动作基本示例在 YAML 中该动作以music_assistant.search引用。以下是一个基础示例取自原文档并保持可运行action: music_assistant.search data: config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV name: We Are The Champions response_variable: search_results关键点说明config_entry_id是必填项指向具体的 MA 实例。文档给出的获取技巧是在可视化编辑器的下拉框中选中实例然后切换到 YAML 模式读取生成的 ID 值。name是必填的搜索词此处传入曲目名称We Are The Champions。response_variable用于将结果存入后续步骤可读取的变量search_results。YAML 选项全参考根据原文档的{% options_yaml %}块各字段定义如下YAML 字段必填类型默认值说明config_entry_id是string—要在其上执行搜索的 Music Assistant 实例的 ID。name是string—要搜索的名称或标题。media_type否string / list全部类型要搜索的内容类型。可选值artist、album、audiobook、playlist、podcast、track、radio。可传多个省略时搜索所有类型。artist否string—当name指定的是曲目或专辑名称时可选的用于按艺术家名称限制结果。album否string—当name指定的是曲目名称时可选的用于按专辑名称限制结果。limit否integer5每种媒体类型最多返回的项目数。library_only否booleanfalse仅包含在库中的结果。username否string—在指定 Music Assistant 用户的库中搜索。若该用户配置了提供商过滤结果会相应过滤。对比可见UI 中名为 Media type(s)、Artist name、Album name、Only library items 的选项在 YAML 中分别对应media_type、artist、album、library_only编写 YAML 自动化时需使用后者。组合搜索条件的进阶用法利用media_type支持列表的特性可以一次性限定多种类型并用artist/album缩小范围action: music_assistant.search data: config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV name: Bohemian Rhapsody media_type: - track - album artist: Queen limit: 10 response_variable: search_results此例在 Queen 的艺术家人名下同时搜索曲目与专辑每种类型最多返回 10 条。需要说明的是UI 选项中 Media type(s) 同样支持多选其含义与 YAML 列表一致。理解响应数据与response_variable返回结构与可消费字段该动作返回按媒体类型分组的匹配项列表包括artists、albums、tracks、playlists、radio、audiobooks和podcasts。每个项目都包含诸如名称name和 URI 之类的详细信息。其中URI 是打通搜索 → 播放链路的关键文档明确指出这些 URI 可以直接传给 Play media 动作使用。这与 source/_integrations/music_assistant.markdown 中的说明一致——media_player.browse_media和搜索/库类动作产出的library://artist/1、spotify://album/5zj4Ej0FrlJQaSo0d6cttH这类 URI 可直接用于播放。另外从 source/_actions/music_assistant.play_media.markdown 可知play_media的media_id可以接受曲目/艺术家/专辑名称、spotify://artist/12345这类提供商 URI甚至提供商网页 URL与搜索返回的 URI 天然兼容。响应变量的使用机制response_variable是 Home Assistant 脚本/自动化中让动作把结果交还给调用方的标准机制。根据 source/_docs/scripts.markdown 的说明脚本可通过response_variable选项返回响应数据响应数据必须是键/值映射也可配合stop指令返回。在本动作的场景中response_variable: search_results意味着后续步骤可以直接引用search_results中的items或按类型分组的结果如search_results[tracks]。一个典型的消费方式是把返回的 URI 列表喂给music_assistant.play_media。下面的脚本示例演示了完整的搜索 → 播放链路参考 source/_actions/music_assistant.get_library.markdown 中随机播放的写法将其中的库查询替换为搜索script: sequence: - action: music_assistant.search data: config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV name: Queen media_type: track limit: 5 response_variable: search_results - action: music_assistant.play_media target: entity_id: media_player.kitchen_speaker data: media_id: {{ search_results[tracks] | map(attributeuri) | list }} media_type: track enqueue: replace该脚本先搜索与 Queen 相关的 5 首曲目再把返回结果中的uri列表通过 Jinja 模板映射出来交给music_assistant.play_media在media_player.kitchen_speaker上以replace替换队列方式播放。这里的map(attributeuri)用法与get_library文档中处理items的写法同构可直接套用。与关联动作的配合music_assistant.search在文档的related_actions中声明了两个高频搭配动作Get library items检索 Music Assistant 库中的项目适合从库中取数据而非跨提供商搜索的场景。它同样返回响应变量、不支持目标支持media_type、favorite、search、limit、offset、order_by、album_type、album_artists_only、username等参数详见 source/_actions/music_assistant.get_library.markdown。例如取 10 首随机曲目可用order_by: random。Play media在 MA 播放器上播放媒体支持一次入队多个项目、指向特定曲目或专辑、开启 radio mode 自动填充相似曲目以及通过enqueueplay/replace/next/replace_next/add精细控制队列行为。media_id支持名称、名称艺术家、提供商 URI 或提供商 URL 等多种形态详见 source/_actions/music_assistant.play_media.markdown。三者构成一个常见的工作流闭环用search跨源检索 → 用get_library从库内筛选 → 用play_media播放。其中search与get_library都是查询型动作返回响应变量、不改播放器而play_media是执行型动作作用于指定播放器目标。常见注意事项实例 ID 的获取config_entry_id没有直观的 UI 对应输入框推荐做法是在可视化编辑器中从下拉框选择实例再切到 YAML 模式复制生成的 ID。library_only与username的配合library_only: true时结果仅限 MA 库内项目username可指定在某个 MA 用户视角下搜索——若该用户配置了提供商过滤provider filtering返回结果会被相应过滤。这一点在 source/_integrations/music_assistant.markdown 的说明中也有体现MA 的用户级提供商过滤会影响媒体选择例如有声书的续播点resume point获取。当从自动化或脚本发起请求时建议显式设置username让请求归属于正确的用户。Radio mode 的限制若想基于搜索结果开启 radio mode在play_media中设置radio_mode: true需要注意并非所有音乐提供商都支持在不支持的提供商项目上启用会报错详见 source/_integrations/music_assistant.markdown 的 Known limitations。结果分组的类型边界返回分组类型artists、albums、tracks、playlists、radio、audiobooks、podcasts与media_type可选值artist、album、audiobook、playlist、podcast、track、radio一一对应编写 Jinja 模板时可按需取用对应的分组键。小结music_assistant.search是 Home Assistant 中连接 Music Assistant 全量音乐目录的查询入口它以config_entry_id指定实例以name为必填搜索词通过media_type、artist、album、limit、library_only、username等参数精细控制检索范围并将按媒体类型分组的搜索结果通过response_variable交还自动化/脚本。配合music_assistant.play_media的 URI 播放能力即可实现搜索任意曲目并立即播放的完整链路与music_assistant.get_library组合则能同时覆盖跨提供商搜索与库内浏览两类需求。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考