Media Player Components

media_player 域包含所有实现媒体播放器功能的平台。

NOTE

ESPHome 媒体播放器需要 Home Assistant 2022.6 或更高版本。

基础媒体播放器配置

media_player:
  - platform: ...
    name: "Media Player Name"

配置变量：

• id（可选，string）：手动指定用于代码生成的 ID。至少需要指定 id 和 name 之一。
• name（可选，string）：媒体播放器的名称。至少需要指定 id 和 name 之一。

NOTE

如果你的设备设置了 friendly_name，且希望媒体播放器使用该名称，可以将 name 设为 None。

• icon（可选，icon）：手动设置在前端中为该媒体播放器使用的图标。

• internal（可选，boolean）：将此组件标记为内部组件。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 将隐式地将其设为 true。

• disabled_by_default（可选，boolean）：如果为 true，则该实体不应被添加到任何客户端的前端中（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。

• entity_category（可选，string）：实体的类别。 参见 https://developers.home-assistant.io/docs/core/entity/#generic-properties 查看可用选项列表。设为 "" 可移除默认的实体类别。

媒体播放器操作

如果配置 YAML 中只有一个 media_player，则所有 media_player 操作均可在不指定 id 的情况下使用。

NOTE

并非所有操作都被每个媒体播放器平台支持。操作的可用性取决于特定平台及其实现的功能。

配置变量：

id（可选，ID）：要控制的媒体播放器。默认为 YAML 中唯一的媒体播放器。 announcement（可选，boolean）：是否以公告或常规媒体文件为目标（如果媒体播放器支持）。默认为 false。适用于所有命令操作。

media_player.play 操作

此操作将恢复媒体播放器的播放。

media_player.play_media 操作

此操作将开始播放指定媒体。

on_...:
  # Simple
  - media_player.play_media: 'http://media-url/media.mp3'

  # Full
  - media_player.play_media:
      id: media_player_id
      media_url: 'http://media-url/media.mp3'

  # Simple with lambda
  - media_player.play_media: !lambda 'return "http://media-url/media.mp3";'

配置变量：

media_url（必需，string，templatable）：要播放的媒体 URL。

media_player.enqueue 操作

此操作将把指定媒体添加到媒体播放器的队列中。

on_...:
  # Simple
  - media_player.enqueue: 'http://media-url/media.mp3'

  # Full
  - media_player.enqueue:
      id: media_player_id
      media_url: 'http://media-url/media.mp3'

  # Simple with lambda
  - media_player.enqueue: !lambda 'return "http://media-url/media.mp3";'

配置变量：

media_url（必需，string，templatable）：要入队的媒体 URL。

media_player.pause 操作

此操作将暂停当前播放。

media_player.stop 操作

此操作将停止当前播放。

media_player.toggle 操作

此操作将暂停或恢复当前播放。

media_player.turn_off 操作

此操作将关闭媒体播放器。

media_player.turn_on 操作

此操作将打开媒体播放器。

media_player.volume_up 操作

此操作将调高媒体播放器的音量。

media_player.volume_down 操作

此操作将调低媒体播放器的音量。

media_player.mute 操作

此操作将静音媒体播放器。

media_player.unmute 操作

此操作将取消静音媒体播放器。

media_player.next 操作

此操作将跳过到下一首曲目。

media_player.previous 操作

此操作将跳过到上一首曲目。

media_player.repeat_off 操作

此操作将关闭重复模式。

media_player.repeat_one 操作

此操作将设置媒体播放器重复当前曲目。

media_player.repeat_all 操作

此操作将设置媒体播放器重复所有曲目。

media_player.shuffle 操作

此操作将启用随机播放模式。

media_player.unshuffle 操作

此操作将禁用随机播放模式。

media_player.group_join 操作

此操作将媒体播放器加入一个分组。

media_player.clear_playlist 操作

此操作将清除媒体播放器的播放列表。

media_player.volume_set 操作

此操作将设置媒体播放器的音量。

on_...:
  # Simple
  - media_player.volume_set: 50%

  # Full
  - media_player.volume_set:
      id: media_player_id
      volume: 50%

  # Simple with lambda
  - media_player.volume_set: !lambda "return 0.5;"

配置变量：

volume（必需，percentage）：要设置的音量。

media_player.on_state 触发器

每当媒体播放器状态更新时，此触发器都会被激活（例如，如果播放器停止播放音频或收到了某些命令）。

media_player:
  - platform: i2s_audio  # 或其他任何平台
    # ...
    on_state:
      - logger.log: "State updated!"

media_player.on_play 触发器

每当媒体播放器开始播放时，此触发器都会被激活。

media_player:
  - platform: i2s_audio  # 或其他任何平台
    # ...
    on_play:
      - logger.log: "Playback started!"

media_player.on_pause 触发器

每当媒体播放器暂停播放时，此触发器都会被激活。

media_player:
  - platform: i2s_audio  # 或其他任何平台
    # ...
    on_pause:
      - logger.log: "Playback paused!"

media_player.on_idle 触发器

每当媒体播放器完成播放时，此触发器都会被激活。

media_player:
  - platform: i2s_audio  # 或其他任何平台
    # ...
    on_idle:
      - logger.log: "Playback finished!"

media_player.on_announcement 触发器

每当媒体播放器播放公告时，此触发器都会被激活。

media_player:
  - platform: i2s_audio  # 或其他任何平台
    # ...
    on_announcement:
      - logger.log: "Announcing!"

media_player.on_turn_off 触发器

每当媒体播放器被关闭时，此触发器都会被激活。

media_player:
  - platform: ...  # 任何实现了 `supports_turn_off_on` 特性的平台
    # ...
    on_turn_off:
      - logger.log: "Media Player is Turned Off"

media_player.on_turn_on 触发器

每当媒体播放器被打开时，此触发器都会被激活。

media_player:
  - platform: ...  # 任何实现了 `supports_turn_off_on` 特性的平台
    # ...
    on_turn_on:
      - logger.log: "Media Player is Turned On"

media_player.is_idle 条件

此条件检查媒体播放器是否处于空闲状态。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_idle:

media_player.is_playing 条件

此条件检查媒体播放器是否正在播放媒体。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_playing:

media_player.is_paused 条件

此条件检查媒体播放器是否已暂停。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_paused:

media_player.is_announcing 条件

此条件检查媒体播放器是否正在播放公告。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_announcing:

media_player.is_off 条件

此条件检查媒体播放器是否已关闭。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_off:

media_player.is_on 条件

此条件检查媒体播放器是否已打开。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_on:

media_player.is_muted 条件

此条件检查媒体播放器是否已静音。

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_muted:

按顺序播放媒体

你可以使用等待自动化依次播放文件：

# In some trigger:
on_...:
  then:
    - media_player.play_media: 'http://media-url/one.mp3'
    - wait_until:
        media_player.is_idle:
    - media_player.play_media: 'http://media-url/two.mp3'