Home Assistant 中 media_player.play_media 动作完整指南播放媒体、队列与通告【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iomedia_player.play_media是 Home Assistant 中用于在媒体播放器上播放指定媒体歌曲、播放列表、视频、直播流等的核心动作。本文以官方动作文档为主体结合仓库中 media_source 集成文档 与配套动作文档系统讲解如何在自动化、脚本中通过 UI 或 YAML 调用该动作深入剖析media_content_id、enqueue、announce、extra等参数的取值与底层影响并给出可直接复制运行的完整示例。动作概览与适用场景media_player.play_media的作用是在一个媒体播放器实体上播放特定的媒体内容。从仓库中的动作定义source/_actions/media_player.play_media.markdown可以看到它的官方描述为 Plays specific media on a media player是media_player域下最常用的动作之一。典型应用场景包括早晨定时播放电台流或音乐播放列表有人按门铃时在客厅音箱上播放提示音或通告离家时暂停、回家时恢复指定的媒体内容在电视上播放指定视频文件或直播频道将媒体加入现有播放队列而非打断当前播放。该动作既可以完全通过 UI 可视化配置也可以直接在 YAML 中精确定义每个参数两种方式在本仓库文档中均有完整说明下文分别展开。通过用户界面UI使用该动作如果你更习惯用可视化方式构建自动化与脚本Home Assistant 会引导你逐步完成配置——选择目标、调整选项、保存即可无需掌握 YAML。对应 UI 引导文本位于 source/_includes/actions/ui_header.md。在自动化或脚本中使用该动作的步骤进入设置 自动化与场景Automations scenes。打开一个已有的自动化或脚本或选择创建自动化创建新自动化。如果是新建自动化在When何时部分添加一个触发器脚本不需要触发器它们在被其他内容调用时运行。在Then do然后执行部分选择添加动作Add action。选择要控制的设备。在按目标By target下参见后文 目标Targets选择要控制的媒体播放器。在针对该目标显示的动作列表中选择播放指定媒体Play specified media。选择要播放的媒体Media并按需设置其他选项。选择保存Save。UI 中的选项选项说明媒体Media要播放的媒体。使用媒体选择器浏览该媒体播放器上可用的内容。加入队列Enqueue新媒体如何与当前队列交互例如立即播放还是加入队列。仅支持队列功能的媒体播放器上可用。通告Announce开启后以通告形式播放媒体暂时打断当前播放。仅支持通告功能的媒体播放器上可用。上述 UI 选项定义位于文档的options_ui区块source/_actions/media_player.play_media.markdown。在 YAML 中使用该动作如果你直接编写 YAML或想确切了解 Home Assistant 在底层做了什么可参考技术参考部分对应 source/_includes/actions/yaml_header.md。它列出了 YAML 中使用的字段名、字段类型以及哪些是必填项。YAML 中动作名称为media_player.play_media。基础示例如下action: media_player.play_media target: entity_id: media_player.living_room data: media_content_id: https://example.com/stream/aac media_content_type: music这段配置会在media_player.living_room上播放给定的音频流。YAML 选项详解参数必填类型默认值说明media_content_id是string—媒体标识符。格式取决于媒体播放器。例如Sonos 和 Cast 设备可以直接传入 URL而 iTunes 只能接受播放列表 ID。media_content_type是string—媒体类型如music、tvshow、video、episode、channel、playlist等。enqueue否string—新媒体如何与当前队列交互取值为add、next、play、replace之一。如果媒体播放器不支持队列新媒体直接播放该选项被忽略。announce否booleanfalse设为true时以通告形式播放媒体暂时打断当前播放并在结束后恢复。如果媒体播放器不支持通告通告仍会播放但被打断的媒体不会恢复。extra否map—发送给媒体播放器的额外数据如标题或缩略图。支持的取值取决于媒体播放器。其中enqueue的四种取值语义为add将媒体追加到当前队列末尾next将媒体插入到当前队列的下一位置play立即播放新媒体replace清空当前队列并播放新媒体。这些定义位于文档的options_yaml区块source/_actions/media_player.play_media.markdown。extra 字典数据详解extra选项接受以下值。支持情况取决于媒体播放器且其中大部分适用于 Cast 设备。该部分在文档中有完整字段级定义source/_actions/media_player.play_media.markdown字段类型默认值说明titlestring—媒体标题。thumbstring—缩略图图片 URL。current_timefloat—距内容开始经过的秒数。对于未指定位置的直播内容流将从直播位置开始。autoplaybooleantrue媒体是否自动播放。stream_typestring—描述媒体物件的类型取值为NONE、BUFFERED或LIVE之一。subtitlesstring—在 Cast 上显示的字幕文件 URL。subtitles_langstring—字幕语言。subtitles_mimestring—字幕的 MIME 类型。subtitle_idinteger—要加载的字幕 ID。enqueuebooleanfalse若为true则将该媒体加入队列而不是立即播放。注意这与顶层enqueue字符串选项不同此为布尔值。media_infomap—未单独列出的附加 MediaInformation 属性。metadatamap—媒体元数据对象取值为GenericMediaMetadata、MovieMediaMetadata、TvShowMediaMetadata、MusicTrackMediaMetadata或PhotoMediaMetadata之一。关于 Cast 相关字段的详细取值可进一步查阅 Google Cast 的 MediaData 与 MediaInformation 参考文档。这些extra字段主要服务于 Cast 类设备Chromecast、Google TV 等用于在播放时携带标题、封面、字幕和直播位置等附加信息。目标Targets该动作需要一个目标。目标是动作的作用对象。你可以将动作指向单个实体、设备、区域、楼层或标签Home Assistant 会在该目标背后的每个匹配media_player实体上执行动作对应 source/_includes/actions/targets.md实体Entity一个特定的media_player实体如media_player.living_room。设备Device属于某台设备的所有media_player实体。区域Area某个房间或区域内的所有media_player实体。楼层Floor某一层楼上的所有media_player实体。标签Label共享同一标签的所有media_player实体。你还可以在同一个动作中选择不同类型的目标。例如可以在同一个动作中同时将某个具体实体和一个区域作为目标动作会对两者一并执行。播放本地媒体源media_sourcemedia_player.play_media常与 Home Assistant 的媒体源media source配合播放存储在本机或网络存储上的文件。根据 media_source 集成文档播放媒体源中的媒体时使用 URI schememedia-source://media_source/media_dir/path默认的media_dir为local。示例如下来自该集成文档action: media_player.play_media target: entity_id: media_player.living_room_tv data: media_content_type: video/mp4 media_content_id: media-source://media_source/local/videos/favourites/Epic Sax Guy 10 Hours.mp4注意Web 浏览器和 Google Cast 媒体播放器对视频容器和编解码器的支持非常有限media source 集成不会对媒体做任何转码因此媒体文件必须被你的播放器或浏览器原生支持否则将播放失败。如果希望为动作构造media-source://URI而媒体已出现在侧边栏的媒体浏览器中无论是本机存储还是网络存储映射可以按以下步骤确定 URI在侧边栏选择媒体Media。导航到包含要播放媒体的文件夹。复制地址栏中的当前 URL例如https://home-assistant.local/media-browser/browser/app%2Cmedia-source%3A%2F%2Fmedia_source/%2Cmedia-source%3A%2F%2Fmedia_source%2Flocal%2FNAS_Media使用在线 URL 解码器解码得到https://home-assistant.local/media-browser/browser/app,media-source://media_source/,media-source://media_source/local/NAS_Media最后一个 media source此处为media-source://media_source/local/NAS_Media构成路径的第一部分完整路径为media-source://media_source/local/NAS_Media/my-music.mp3另外若使用网络存储中的媒体需先连接网络存储参见 common-tasks/os 中的网络存储说明连接后其中的媒体会自动加入本地媒体浏览器。完整示例播放带标题和缩略图的音频流以下示例在 Cast 设备上播放音频流并设置标题与缩略图来自文档的更多示例部分source/_actions/media_player.play_media.markdownaction: media_player.play_media target: entity_id: media_player.chromecast data: media_content_type: music media_content_id: https://example.com/stream/aac extra: thumb: https://brands.home-assistant.io/_/homeassistant/logo.png title: Home Assistant Radio该示例展示了extra字典的实际用法在播放流媒体的同时向 Cast 设备提供thumb缩略图和title标题元数据。与相关动作的配合使用media_player.play_media通常与同一域下的其他动作组合使用在文档 frontmatter 中声明了关联动作见 source/_actions/media_player.play_media.markdownbrowse_media浏览媒体浏览媒体播放器提供的媒体树类似在媒体播放器 UI 中浏览媒体。适合在自动化或脚本中先按类别查找媒体再播放。它通过response_variable返回结果可在同一自动化或脚本的后续步骤中使用。search_media搜索媒体在媒体播放器上搜索媒体例如按名称查找歌曲或专辑后再播放。同样通过response_variable返回搜索结果。select_source选择媒体源切换媒体播放器的输入源例如将功放切换到不同的输入。常与播放动作配合实现电视开机时功放切到 TV 输入之类的联动。一个典型组合先调用media_player.search_media搜索目标歌曲并存入响应变量再用media_player.play_media播放找到的media_content_id或先用media_player.browse_media定位目录再构造media-source://URI 播放。排查与调试media_content_id的格式与支持的extra值取决于媒体播放器不同厂商的格式差异很大例如 Sonos/Cast 接受 URLiTunes 只接受播放列表 ID遇到播放失败时优先确认这两项是否与目标设备匹配。可以在设置 工具 动作Actions中搜索该动作填写字段并选择执行动作Perform action在真实实体上直接观察效果无需编写任何 YAML对应 source/_includes/actions/try_it.md。使用enqueue: add或next前确认目标设备支持队列使用announce: true前确认设备支持通告否则被中断的媒体不会自动恢复见前文 YAML 选项表。使用要点小结media_content_id与media_content_type是仅有的两个必填参数前者标识媒体后者声明媒体类型music、video、playlist、channel等。enqueue提供add/next/play/replace四种队列策略announce: true实现播报后自动恢复原播放的通告效果两者均依赖播放器能力。extra字典面向 Cast 类设备支持标题、缩略图、字幕、直播位置与元数据等丰富字段可显著提升播放体验。目标支持实体、设备、区域、楼层与标签五种粒度可多目标混合使用。播放本机或网络存储媒体时使用media-source://media_source/...URI注意播放器对媒体格式的原生支持限制。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考