2025.3.4
首页 ▸ Integrations ▸

媒体播放器

与您网络上的媒体播放器进行交互。

Note

构建模块集成

这个 媒体播放器 是一个构建模块集成，无法直接添加到你的 Home Assistant 中，但可以被其他集成使用和提供。

构建模块集成不同于典型的与设备或服务连接的集成。相反，其他将设备或服务集成到 Home Assistant 中的集成使用这个 媒体播放器 构建模块来提供实体、服务和其他你可以在自动化或仪表板中使用的功能。

如果你的某个集成具有这个构建模块，这个页面记录了 媒体播放器 构建模块所提供的功能。

媒体播放器的状态

媒体播放器可以具有以下状态：

  • 关闭：媒体播放器已关闭，并且在打开之前不接受命令。
  • 打开：媒体播放器已打开，但当前没有其状态的详细信息。
  • 空闲：媒体播放器已打开并接受命令，但当前不播放任何媒体。可能处于某个空闲的主屏幕。
  • 播放中：媒体播放器当前正在播放媒体。
  • 已暂停：媒体播放器有一个活动媒体并且当前已暂停。
  • 待机：媒体播放器处于低功耗状态，接受命令。
  • 缓冲：媒体播放器正在准备开始播放媒体。
  • 不可用：实体当前不可用。
  • 未知：状态尚未知道。

操作

媒体控制操作

可用操作：turn_on, turn_off, toggle, volume_up, volume_down, volume_set, volume_mute, media_play_pause, media_play, media_pause, media_stop, media_next_track, media_previous_track, clear_playlist, shuffle_set, repeat_set, play_media, select_source, select_sound_mode, join, unjoin

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。要定位所有媒体播放器，请使用 all。

操作 media_player.volume_mute

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。要定位所有媒体播放器，请使用 all。
is_volume_muted 否 静音/取消静音的真/假值

操作 media_player.volume_set

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。要定位所有媒体播放器，请使用 all。
volume_level 否 音量级别的浮动值。范围为 0..1

操作 media_player.media_seek

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。要定位所有媒体播放器，请使用 all。
seek_position 否 寻找的位置。格式依赖于平台。

操作 media_player.play_media

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。要定位所有媒体播放器，请使用 all。
media_content_id 否 媒体标识符。格式依赖于集成。例如，您可以为 Sonos 和 Cast 提供 URL，但仅为 iTunes 提供播放列表 ID。
media_content_type 否 媒体类型。必须为 music, tvshow, video, episode, channel 或 playlist 之一。例如，要播放音乐，您需要将 media_content_type 设置为 music。
enqueue 是 新媒体与队列的交互方式。必须为 add, next, play, replace 之一。如果媒体播放器不支持此功能，则新媒体将播放，而 enqueue 指令将被忽略。
announce 是 设置为 true 以请求媒体播放器暂时停止播放媒体以宣布该媒体，然后恢复。如果媒体播放器不支持此功能，则公告将播放，但媒体播放器不会在公告完成后恢复播放中断的媒体。
extra 是 额外的字典数据发送，例如标题、缩略图。可能的值可以在下面找到。
额外的字典数据

Configuration Variables

Looking for your configuration file?
title string (Optional)

媒体的标题。

thumb string (Optional)

缩略图图像 URL。

current_time float (Optional)

自内容开始以来的秒数。如果内容是直播内容，并且位置未指定，则流将从实时位置开始。

autoplay boolean (Optional, default: true)

媒体是否将自动播放。

stream_type string (Optional)

描述媒体文档的类型之一：NONE, BUFFERED, LIVE。

subtitles string (Optional)

要在 Chromecast 上显示的字幕文件的 URL。

subtitles_lang string (Optional)

字幕语言。

subtitles_mime string (Optional)

字幕的 MIME 类型。

subtitle_id integer (Optional)

要加载的字幕 ID。

enqueue boolean (Optional, default: false)

如果为 True，则将媒体排入队列而不是播放它。

media_info map (Optional)

其他未明确列出的 MediaInformation 属性。

metadata map (Optional)

媒体元数据对象，以下之一：GenericMediaMetadata, MovieMediaMetadata, TvShowMediaMetadata, MusicTrackMediaMetadata, PhotoMediaMetadata。

文档：

调用媒体播放器操作的示例，设置标题和图像：

action: media_player.play_media
target:
  entity_id: media_player.chromecast
data:
  media_content_type: music
  media_content_id: "https://fake-home-assistant.io.stream/aac"
  extra:
    thumb: "https://brands.home-assistant.io/_/homeassistant/logo.png"
    title: HomeAssistantRadio

操作 media_player.select_source

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。要定位所有媒体播放器，请使用 all。
source 否 要切换到的源的名称。依赖于平台。

操作 media_player.select_sound_mode

目前仅在 Denon AVR 和 Songpal 上支持。

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。例如 media_player.marantz
sound_mode 否 要切换到的音效模式的名称。依赖于平台。

操作 media_player.shuffle_set

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。例如 media_player.spotify
shuffle 否 true/false 用于启用/禁用随机播放

操作 media_player.repeat_set

数据属性 可选 描述
entity_id 是 目标特定的媒体播放器。例如 media_player.kitchen
repeat 否 off/all/one 用于设置重复模式

操作 media_player.join

允许将媒体播放器组合在一起进行同步播放。仅在支持的多房间音频系统上工作。

数据属性 可选 描述
entity_id 是 媒体播放器实体，其播放将扩展到 group_members 中指定的播放器。
group_members 否 与来自 entity_id 播放同步的播放器实体。

操作 media_player.unjoin

数据属性 可选 描述
entity_id 是 将此媒体播放器从任何播放器组中取消组合。

操作 media_player.browse_media

提供对集成提供的媒体树的浏览访问。功能类似于通过媒体播放器 UI 浏览媒体。常见用例包括需要导航媒体库并按特定类别查找媒体的自动化。

数据属性 可选 描述
media_content_type 是 要浏览的媒体类型，例如音乐、播放列表和视频。特定于集成。
media_content_id 是 要浏览的内容 ID。特定于集成。空内容 ID 返回浏览树的顶层。

该操作返回一个媒体树对象，可以存储在响应变量中以便在后续自动化步骤中使用。响应包括：

字段 描述
title 当前级别的显示名称
media_class 当前项目的类型（例如，目录、音乐、视频）
media_content_type 内容类型标识符
media_content_id 特定于集成的内容 ID
children_media_class 子数组中项目的类型
children 具有相似属性的子项目数组

浏览树的根。

注意：以下示例显示来自 Sonos 设备的响应。不同媒体播放器集成之间的结构和内容类型可能会有所不同。媒体内容 ID 通常被 URL 编码。

  # 获取浏览树的顶层
  - action: media_player.browse_media
    target:
      entity_id: media_player.living_room
    response_variable: top_level

# 简化示例响应
media_player.living_room:
  title: Sonos
  media_class: directory
  media_content_type: root
  media_content_id: ""
  # children_media_class 指示子数组中的所有项都是目录  
  children_media_class: directory
  children:
    - title: 收藏夹
      media_class: directory
      media_content_type: favorites
      media_content_id: ""
    - title: 音乐库
      media_class: directory
      media_content_type: library
      media_content_id: ""

使用 Sonos 集成浏览特定艺术家的示例：

注意：此示例演示了浏览艺术家的专辑。media_content_id 的格式（A:ALBUMARTIST/artist_name）特定于 Sonos。注意响应中专辑名称中的特殊字符如何被 URL 编码（例如，空格的 %20）。

  - 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

设备类

设备类别是 Home Assistant 中的一种测量分类。它影响实体在 仪表板 中的表示方式。这可以在 自定义部分 中进行修改。例如，不同的状态可能会用不同的图标、颜色或文本来表示。

截图显示了代表媒体播放器实体的不同设备类图标：

显示代表媒体播放器实体的不同设备类图标的截图 代表媒体播放器实体的不同设备类图标示例。

以下设备类支持媒体播放器：

  • tv：设备为电视类型设备。
  • speaker：设备为扬声器或立体声音响类型设备。
  • receiver：设备为音频/视频接收器类型设备，接收音频并输出到扬声器和视频到显示器。

相关主题