diff --git a/components/index.rst b/components/index.rst index 737a782af..48a4c1ca8 100644 --- a/components/index.rst +++ b/components/index.rst @@ -24,5 +24,6 @@ Components display_menu/index media_player/index microphone/index + speaker/index time/index * diff --git a/components/speaker/i2s_audio.rst b/components/speaker/i2s_audio.rst new file mode 100644 index 000000000..3ece5e99a --- /dev/null +++ b/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 `): 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` diff --git a/components/speaker/index.rst b/components/speaker/index.rst new file mode 100644 index 000000000..85f110c3c --- /dev/null +++ b/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 + - 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` diff --git a/images/speaker.svg b/images/speaker.svg new file mode 100644 index 000000000..22a96737d --- /dev/null +++ b/images/speaker.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 225912426..9088ca13e 100644 --- a/index.rst +++ b/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 ---------------