Media Player Components
=======================

.. seo::
    :description: Instructions for setting up generic media players in ESPHome.
    :image: folder-open.svg

The ``media_player`` domain includes all platforms that implement media player
functionality.

.. note::

    ESPHome media players require Home Assistant 2022.6 or newer.

.. _config-media_player:

Base Media Player Configuration
-------------------------------

.. code-block:: yaml

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

Configuration variables:

- **name** (**Required**, string): The name of the media player.

  .. note::

      If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
      you want the media player to use that name, you can set ``name: None``.

- **icon** (*Optional*, icon): Manually set the icon to use for the
  media player in the frontend.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
  a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
  Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
  See https://developers.home-assistant.io/docs/core/entity/#generic-properties
  for a list of available options. Set to ``""`` to remove the default entity category.

Media Player Actions
--------------------

All ``media_player`` actions can be used without specifying an ``id`` if you have only one ``media_player`` in
your configuration YAML.

Configuration variables:

**id** (*Optional*, :ref:`config-id`): The media player to control. Defaults to the only one in YAML.


.. _media_player-play:

``media_player.play`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action will resume playing the media player.

.. _media_player-play_media:

``media_player.play_media`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action will start playing the specified media.

.. code-block::

    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";'

Configuration variables:

**media_url** (**Required**, string): The media url to play.

.. _media_player-pause:

``media_player.pause`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action pauses the current playback.

.. _media_player-stop:

``media_player.stop`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action stops the current playback.

.. _media_player-toggle:

``media_player.toggle`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action will pause or resume the current playback.

.. _media_player-volume_up:

``media_player.volume_up`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action will increase the volume of the media player.

.. _media_player-volume_down:

``media_player.volume_down`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action will decrease the volume of the media player.

.. _media_player-volume_set:

``media_player.volume_set`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This action will set the volume of the media player.

.. code-block::

    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;"

Configuration variables:

**volume** (**Required**, percentage): The volume to set the media player to.

.. _media_player-on_state_trigger:

``media_player.on_state`` Trigger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This trigger is activated each time the state of the media player is updated
(for example, if the player is stop playing audio or received some command).

.. code-block:: yaml

    media_player:
      - platform: i2s_audio  # or any other platform
        # ...
        on_state:
          - logger.log: "State updated!"

.. _media_player-on_play_trigger:

``media_player.on_play`` Trigger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This trigger is activated each time then the media player is started playing.

.. code-block:: yaml

    media_player:
      - platform: i2s_audio  # or any other platform
        # ...
        on_play:
          - logger.log: "Playback started!"

.. _media_player-on_pause_trigger:

``media_player.on_pause`` Trigger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This trigger is activated every time the media player pauses playback.

.. code-block:: yaml

    media_player:
      - platform: i2s_audio  # or any other platform
        # ...
        on_pause:
          - logger.log: "Playback paused!"

.. _media_player-on_idle_trigger:

``media_player.on_idle`` Trigger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This trigger is activated every time the media player finishes playing.

.. code-block:: yaml

    media_player:
      - platform: i2s_audio  # or any other platform
        # ...
        on_idle:
          - logger.log: "Playback finished!"

.. _media_player-is_idle_condition:

``media_player.is_idle`` Condition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This condition checks if the media player is idle.

.. code-block:: yaml

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

.. _media_player-is_playing_condition:

``media_player.is_playing`` Condition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This condition checks if the media player is playing media.

.. code-block:: yaml

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

Play media in order
-------------------

You can use wait automation to play files one after the other:

.. code-block:: yaml

    # 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'

See Also
--------

.. toctree::
    :maxdepth: 1
    :glob:

    *

- :ghedit:`Edit`