Home Assistant media_player.browse_media 动作实战在自动化与脚本中浏览媒体树【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读media_player.browse_media是 Home Assistant 提供的媒体播放器核心动作之一它允许你在自动化或脚本中读取媒体播放器暴露的媒体树media tree从而在播放之前先按分类定位目标媒体例如查找某个艺术家、专辑或视频资源。读完本文你将掌握该动作在 UI 与 YAML 两种方式下的完整配置方法、响应数据结构以及它与media_player.search_media、media_player.play_media配合使用的实战链路。本文依据的官方动作文档位于仓库 source/_actions/media_player.browse_media.markdown并补充了相关源码与变更记录证据。什么是 browse media 动作浏览媒体Browse media动作的作用是遍历由媒体播放器提供的媒体树其行为与在媒体播放器 UI 中浏览媒体类似。它非常适合在自动化或脚本中先按某个特定分类找到媒体再进行播放——典型场景如当用户按下实体按钮时浏览客厅音箱上的某个播放列表并播放。该动作的一个关键特性是结果通过响应变量response variable返回你可以在同一自动化或脚本的后续步骤中使用这个变量。实现依据Home Assistant 2025.3 版本变更记录中明确记录 Expose media_player async_browse_media as servicesource/changelogs/core-2025.3.markdown即该动作本质上是把媒体播放器实体的异步浏览方法async_browse_media暴露为服务action供自动化调用。在 UI 中调用 Browse media如果你习惯用可视化方式构建自动化Home Assistant 会逐步引导你完成该动作的配置无需编写 YAML。操作步骤如下进入设置 自动化与场景Settings Automations scenes。打开一个已有的自动化或脚本或者选择创建自动化创建新自动化。如果是新建自动化需要在When何时部分添加一个触发器脚本script不需要触发器它们由其他东西调用时运行。在Then do然后执行部分选择Add action添加动作。选择你要控制的对象在By target按目标下选择要浏览媒体的媒体播放器关于 target 的详细说明见下文动作的目标Targets一节。在针对该目标展示的动作列表中选择Browse media浏览媒体。如果你只想浏览媒体树的某个特定部分可以设置内容选项Content type / Content ID。选择保存。UI 选项选项说明是否必填Content type内容类型要浏览的内容类型如 music、playlist、video。可用类型取决于媒体播放器。否Content ID内容 ID要进入浏览的内容标识。可用 ID 取决于媒体播放器。留空则返回浏览树的顶层。否在 YAML 中使用 browse media在 YAML 中该动作的名称为media_player.browse_media。由于浏览结果通过响应变量返回建议把结果存入response_variable以便在后续步骤中使用action: media_player.browse_media target: entity_id: media_player.living_room response_variable: top_level上面的示例返回media_player.living_room媒体树的顶层内容。YAML 选项字段类型说明是否必填media_content_typestring要浏览的内容类型如 music、playlist、video。可用类型取决于媒体播放器。否media_content_idstring要进入浏览的内容标识。可用 ID 取决于媒体播放器。留空则返回浏览树的顶层。否动作的目标Targetsmedia_player.browse_media动作要求指定目标target目标是动作的作用对象。你可以把动作指向单个实体、设备、区域、楼层或标签Home Assistant 会对该目标背后每一个匹配的media_player实体执行动作实体Entity某个具体的media_player实体例如media_player.living_room。设备Device属于某设备的所有media_player实体。区域Area某个房间/区域内的所有media_player实体。楼层Floor某一楼层上的所有media_player实体。标签Label共享某个标签的所有media_player实体。你还可以在同一次动作中选择不同类型的目标例如同时添加一个具体实体和一个区域作为目标让动作同时对两者执行。响应数据结构media_player.browse_media返回一个媒体树对象你可以将其存入响应变量。响应包含以下字段title当前层级current level的显示名称。media_class当前条目的类型例如 directory目录、music音乐、video视频。media_content_type内容类型标识符。media_content_id内容 ID具体格式取决于媒体播放器。children_media_classchildren 数组中条目的类型。children子条目列表每个子条目拥有类似的属性。不同媒体播放器的响应结构与内容类型各不相同且内容 ID 通常经过 URL 编码URL-encoded。从源码结构看这个响应对象对应 Home Assistant 媒体浏览器media browser中统一的媒体条目结构顶层条目item携带title、media_class、media_content_type、media_content_id并通过children递归展开子树供 UI 的媒体浏览器与browse_media动作共用同一套数据模型。实战示例浏览 Sonos 上某位艺术家的专辑下面的示例在 Sonos 设备上浏览某位艺术家的专辑。media_content_id的格式A:ALBUMARTIST/artist_name是 Sonos 特有的action: media_player.browse_media target: entity_id: media_player.living_room data: media_content_id: A:ALBUMARTIST/Beatles media_content_type: album response_variable: albums简化后的响应示例media_player.living_room: title: Beatles media_class: album media_content_type: album media_content_id: A:ALBUMARTIST/Beatles children_media_class: directory children: - title: A Hard Days Night media_class: album media_content_type: album media_content_id: A:ALBUMARTIST/Beatles/A%20Hard%20Days%20Night - title: Abbey Road media_class: album media_content_type: album media_content_id: A:ALBUMARTIST/Beatles/Abbey%20Road注意观察子条目中的media_content_id携带了父级路径如A:ALBUMARTIST/Beatles/A%20Hard%20Days%20Night空格被编码为%20——这正是内容 ID 通常经过 URL 编码的体现。把这些子条目的media_content_id和media_content_type直接交给media_player.play_media即可精确播放对应专辑。与 search_media、play_media 的配合链路media_player.browse_media与另外两个动作形成完整的找媒体—放媒体闭环官方文档中三者互为关联动作related actionsmedia_player.search_media按关键词搜索媒体播放器上可用的媒体例如先按名称找到某首歌或专辑再播放。其返回结构与browse_media一致title、media_class、media_content_type、media_content_id、children_media_class、children并额外支持search_query必填与media_filter_classes按 media class 过滤搜索结果参数。media_player.play_media真正播放指定的媒体歌曲、播放列表或视频media_content_id与media_content_type均为必填项还支持enqueue、announce、extra等进阶参数。一个典型的自动化流程是触发条件 →media_player.browse_media或search_media把结果存入响应变量 → 从children中挑选目标条目 →media_player.play_media用其media_content_id/media_content_type完成播放。由于浏览结果保存在响应变量中同一自动化或脚本的后续步骤可以直接引用无需手工拼接媒体 ID。集成侧佐证Jellyfin 集成文档在说明如何播放媒体时明确写道要找到想播放内容的media_content_id请使用 Browse media 与 Search media 动作浏览或搜索你的媒体库source/_integrations/jellyfin.markdown并将 Browse media 列在其关联动作中。这印证了该动作是媒体集成对外暴露媒体库的标准入口。注意事项Good to know并非所有媒体播放器都支持浏览媒体。该动作只对实现了媒体浏览能力的播放器生效响应的具体结构取决于媒体播放器本身。响应中的media_content_type与media_content_id格式高度依赖厂商实现Sonos 使用A:ALBUMARTIST/...这类专有路径其他设备如 Chromecast、Squeezebox 等则可能是 URL 或服务特定的标识符。在跨设备编写通用自动化时应对不同播放器分别适配。若想缩小浏览范围可同时传入media_content_type与media_content_id定位到树的特定分支两者都留空时返回顶层。从变更记录看媒体浏览能力在各集成中持续演进例如 Spotify 的浏览媒体可读性改进、Squeezebox 新增专辑艺术家浏览分类source/changelogs/core-2025.3.markdown 与 L1007说明不同播放器对媒体树的组织方式差异明显应以实际返回结果为准。小结media_player.browse_media是把媒体浏览能力接入自动化的关键动作通过response_variable拿到结构化的媒体树再结合media_player.search_media做精确查找、media_player.play_media完成播放即可构建出按分类先找后播的完整自动化链路。掌握其响应字段media_class、media_content_type、media_content_id、children与各播放器的 ID 格式差异是写出可复用自动化脚本的前提。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考