Speaker docs (#2892)

components/index.rst

@@ -24,5 +24,6 @@ Components
     display_menu/index
     media_player/index
     microphone/index
+    speaker/index
     time/index
     *

components/speaker/i2s_audio.rst

@@ -0,0 +1,49 @@
+I²S Audio Speaker
+=================
+
+.. seo::
+    :description: Instructions for setting up I²S based speakers in ESPHome.
+    :image: i2s_audio.svg
+
+The ``i2s_audio`` speaker platform allows you to receive audio via the the
+:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    speaker:
+      - platform: i2s_audio
+        dac_type: external
+        i2s_dout_pin: GPIO22
+        mode: mono
+
+Configuration variables:
+------------------------
+
+- **dac_type** (**Required**, enum):
+
+  - ``external``: Use an external DAC, for example the NS4168, or UDA1334A.
+  - ``internal``: Use the internal DAC
+
+External DAC
+************
+
+- **i2s_dout_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I²S DOUT (Data Out) signal.
+- **mode** (*Optional*, string): The mode of the I²S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
+
+For best results, keep the wires as short as possible.
+
+Internal DAC
+************
+
+- **mode** (**Required**, enum): The channel mode of the internal DAC.
+
+  - ``left``
+  - ``right``
+  - ``stereo``
+
+See also
+--------
+
+- :doc:`index`
+- :ghedit:`Edit`

components/speaker/index.rst

@@ -0,0 +1,96 @@
+Speaker Components
+==================
+
+.. seo::
+    :description: Instructions for setting up speakers in ESPHome.
+    :image: speaker.svg
+
+The ``speaker`` domain contains common functionality shared across the
+speaker platforms.
+
+.. _config-speaker:
+
+Base Speaker Configuration
+--------------------------
+
+No configuration variables
+
+.. _speaker-actions:
+
+Speaker Actions
+------------------
+
+All ``speaker`` actions can be used without specifying an ``id`` if you have only one ``speaker`` in
+your configuration YAML.
+
+Configuration variables:
+
+**id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML.
+
+
+.. _speaker-play:
+
+``speaker.play`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will start playing raw audio data from the speaker.
+
+.. code-block:: yaml
+
+    on_...:
+      # Static raw audio data
+      - speaker.play: [...]
+
+      # Templated, return type is std::vector<uint8_t>
+      - speaker.play: !lambda return {...};
+
+      # in case you need to specify the speaker id
+      - speaker.play:
+          id: my_speaker
+          data: [...]
+
+Configuration variables:
+
+**id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML.
+**data** (*Required*, list of bytes): The raw audio data to play.
+
+.. _speaker-stop:
+
+``speaker.stop`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will stop playing audio data from the speaker and discard the unplayed data.
+
+.. _speaker-conditions:
+
+Speaker Conditions
+---------------------
+
+All ``speaker`` conditions can be used without specifying an ``id`` if you have only one ``speaker`` in
+your configuration YAML.
+
+Configuration variables:
+
+**id** (*Optional*, :ref:`config-id`): The speaker to check. Defaults to the only one in YAML.
+
+.. _speaker-is_playing:
+
+``speaker.is_playing`` Condition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This condition will check if the speaker is currently playing audio data.
+
+
+Platforms
+---------
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
+
+See Also
+--------
+
+- :ghedit:`Edit`

images/speaker.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.84-5 6.7v2.07c4-.91 7-4.49 7-8.77 0-4.28-3-7.86-7-8.77M16.5 12c0-1.77-1-3.29-2.5-4.03V16c1.5-.71 2.5-2.24 2.5-4M3 9v6h4l5 5V4L7 9H3Z"/></svg>

index.rst

@@ -715,6 +715,14 @@ Microphone Components
     Microphone Core, components/microphone/index, microphone.svg
     I2S Microphone, components/microphone/i2s_audio, i2s_audio.svg
 
+Speaker Components
+------------------
+
+.. imgtable::
+
+    Speaker Core, components/speaker/index, speaker.svg
+    I2S Speaker, components/speaker/i2s_audio, i2s_audio.svg
+
 Time Components
 ---------------