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 service"（source/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_type | string | 要浏览的内容类型，如 music、playlist、video。可用类型取决于媒体播放器。 | 否 |
media_content_id | string | 要进入浏览的内容标识。可用 ID 取决于媒体播放器。留空则返回浏览树的顶层。 | 否 |
动作的目标（Targets）
media_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_class：children 数组中条目的类型。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 Day's Night media_class: album media_content_type: album media_content_id: A:ALBUMARTIST/Beatles/A%20Hard%20Day's%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%20Day's%20Night），空格被编码为%20——这正是"内容 ID 通常经过 URL 编码"的体现。把这些子条目的media_content_id和media_content_type直接交给media_player.play_media，即可精确播放对应专辑。
与 search_media、play_media 的配合链路
media_player.browse_media与另外两个动作形成完整的"找媒体—放媒体"闭环，官方文档中三者互为关联动作（related actions）：
- media_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），仅供参考
