媒体播放器组件

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

NOTE

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

基础媒体播放器配置

media_player:
  - platform: ...
    name: "媒体播放器名称"

配置变量：

• id (可选, 字符串): 手动指定用于代码生成的 ID。id 和 name 中至少必须指定一个。
• name (可选, 字符串): 媒体播放器的名称。id 和 name 中至少必须指定一个。

NOTE

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

• icon (可选, 图标): 手动设置前端中媒体播放器使用的图标。

• internal (可选, 布尔值): 将此组件标记为内部。内部组件不会暴露给前端（如 Home Assistant）。只指定 id 而不指定 name 会隐式将其设置为 true。

• disabled_by_default (可选, 布尔值): 如果为 true，则此实体不应添加到任何客户端的前端 （通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。 默认为 false。

• entity_category (可选, 字符串): 实体的类别。 请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项列表。设置为 "" 以移除默认的实体类别。

媒体播放器动作

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

turn_off 和 turn_on 动作是可选的，取决于平台是否实现 supports_turn_off_on 特性。

配置变量：

id (可选, ID): 要控制的媒体播放器。默认为 YAML 中唯一的一个。

media_player.play 动作

此动作将恢复播放媒体播放器。

media_player.play_media 动作

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

on_...:
  # 简单形式
  - media_player.play_media: 'http://media-url/media.mp3'

  # 完整形式
  - media_player.play_media:
      id: media_player_id
      media_url: 'http://media-url/media.mp3'

  # 简单形式带 lambda
  - media_player.play_media: !lambda 'return "http://media-url/media.mp3";'

配置变量：

media_url (必需, 字符串): 要播放的媒体 URL。

media_player.pause 动作

此动作暂停当前播放。

media_player.stop 动作

此动作停止当前播放。

配置变量：

announcement (可选, 布尔值): 是否针对公告或常规媒体文件（如果媒体播放器支持）。默认为 false。

media_player.toggle 动作

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

media_player.turn_off 动作

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

media_player.turn_on 动作

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

media_player.volume_up 动作

此动作将增加媒体播放器的音量。

media_player.volume_down 动作

此动作将降低媒体播放器的音量。

media_player.volume_set 动作

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

on_...:
  # 简单形式
  - media_player.volume_set: 50%

  # 完整形式
  - media_player.volume_set:
      id: media_player_id
      volume: 50%

  # 简单形式带 lambda
  - media_player.volume_set: !lambda "return 0.5;"

配置变量：

volume (必需, 百分比): 要设置的媒体播放器音量。

media_player.on_state 触发器

每次媒体播放器状态更新时（例如，播放器停止播放音频或收到某个命令），此触发器将被激活。

media_player:
  - platform: i2s_audio  # 或任何其他平台
    # ...
    on_state:
      - logger.log: "状态已更新！"

media_player.on_play 触发器

每次媒体播放器开始播放时，此触发器将被激活。

media_player:
  - platform: i2s_audio  # 或任何其他平台
    # ...
    on_play:
      - logger.log: "播放已开始！"

media_player.on_pause 触发器

每次媒体播放器暂停播放时，此触发器将被激活。

media_player:
  - platform: i2s_audio  # 或任何其他平台
    # ...
    on_pause:
      - logger.log: "播放已暂停！"

media_player.on_idle 触发器

每次媒体播放器完成播放时，此触发器将被激活。

media_player:
  - platform: i2s_audio  # 或任何其他平台
    # ...
    on_idle:
      - logger.log: "播放已完成！"

media_player.on_announcement 触发器

每次媒体播放器播放公告时，此触发器将被激活。

media_player:
  - platform: i2s_audio  # 或任何其他平台
    # ...
    on_announcement:
      - logger.log: "正在播报！"

media_player.on_turn_off 触发器

每次媒体播放器被关闭时，此触发器将被激活。

media_player:
  - platform: ...  # 任何实现 `supports_turn_off_on` 特性的平台
    # ...
    on_turn_off:
      - logger.log: "媒体播放器已关闭"

media_player.on_turn_on 触发器

每次媒体播放器被打开时，此触发器将被激活。

media_player:
  - platform: ...  # 任何实现 `supports_turn_off_on` 特性的平台
    # ...
    on_turn_on:
      - logger.log: "媒体播放器已打开"

media_player.is_idle 条件

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

# 在某个触发器中：
on_...:
  if:
    condition:
      media_player.is_idle:

media_player.is_playing 条件

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

# 在某个触发器中：
on_...:
  if:
    condition:
      media_player.is_playing:

media_player.is_paused 条件

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

# 在某个触发器中：
on_...:
  if:
    condition:
      media_player.is_paused:

media_player.is_announcing 条件

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

# 在某个触发器中：
on_...:
  if:
    condition:
      media_player.is_announcing:

media_player.is_off 条件

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

# 在某个触发器中：
on_...:
  if:
    condition:
      media_player.is_off:

media_player.is_on 条件

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

# 在某个触发器中：
on_...:
  if:
    condition:
      media_player.is_on:

按顺序播放媒体

您可以使用等待自动化逐个播放文件：

# 在某个触发器中：
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'