[mixer] Media Player Components Docs PR2

automations/all_actions.rst

@@ -36,6 +36,7 @@
 - **micro_wake_word:** ``start``, ``stop``
 - **microphone:** ``capture``, ``stop_capture``
 - **midea_ac:** ``beeper_off``, ``beeper_on``, ``display_toggle``, ``follow_me``, ``power_off``, ``power_on``, ``power_toggle``, ``swing_step``
+- **mixer_speaker:** ``apply_ducking``
 - **mqtt:** ``publish``, ``publish_json``
 - **number:** ``decrement``, ``increment``, ``operation``, ``set``, ``to_max``, ``to_min``
 - **output:** ``set_level``, ``turn_off``, ``turn_on``

components/speaker/mixer.rst

@@ -0,0 +1,75 @@
+Mixer Speaker
+=============
+
+.. seo::
+    :description: Instructions for setting up mixer speakers in ESPHome.
+    :image: mixer.svg
+
+The ``mixer`` speaker platform allows you to mix audio sent to different source speakers into one output which is sent to another :doc:`speaker component </components/speaker/index>`. Individual source speakers may be ducked (made quieter) with the :ref:`apply ducking action <mixer_speaker-apply_ducking>`.
+
+When mixing multiple audio streams into one, they must have the same sample rate. If they are different, enable queue mode so that only one source speaker's audio is played at a time. Otherwise, use a :doc:`resampler speaker </components/speaker/resampler>` to send audio to the source speakers.
+
+This platform only works on ESP32 based chips.
+
+.. warning::
+
+    Audio and voice components consume a significant amount of resources (RAM, CPU) on the device.
+
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. In particular, Bluetooth/BLE components are known to cause issues when used in
+    combination with Voice Assistant and/or other audio components.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    speaker:
+      - platform: mixer
+        output_speaker: speaker_id
+        source_speakers:
+          - id: announcement_mixer_input_speaker_id
+          - id: media_mixer_input_speaker_id
+
+Configuration variables:
+------------------------
+
+- **output_speaker** (**Required**, :ref:`config-id`): The :doc:`speaker </components/speaker/index>` to output the resampled audio.
+- **source_speakers** (**Required**, list): A list of source speaker inputs. Must have at least 2 and at most 8 speakers.
+
+    - **buffer_duration** (*Optional*, :ref:`config-time`): The duration of the internal ring buffer. Larger values can reduce stuttering but use more memory. Defaults to ``100ms``.
+    - **timeout** (*Optional*, :ref:`config-time`): How long to wait after finishing playback before releasing the bus. Set to ``never`` to never stop the speaker due to a timeout. Defaults to ``500ms``.
+    - All other options from :ref:`Speaker Component <config-speaker>`.
+
+- **num_channels** (*Optional*, positive integer): The number of audio channels to send to the output speaker. Either ``1`` or ``2``. Defaults to the output speaker's number of channels.
+- **queue_mode** (*Optional*, boolean): Enables queue mode. If enabled, audio isn't mixed but instead each source speaker's audio is played successively, starting with the first listed source speaker.
+- **task_stack_in_psram** (*Optional* boolean): Only with ``esp-idf``. Run the audio tasks in external memory. Defaults to ``false``.
+
+
+Automations
+-----------
+
+.. _mixer_speaker-apply_ducking:
+
+``mixer_speaker.apply_ducking`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action ducks (reduces the volume) of the media stream.
+
+.. code-block::
+
+    on_...:
+      - mixer_speaker.apply_ducking:
+          id: media_mixer_source_speaker_id
+          decibel_reduction: 20
+          duration: 2.0s
+
+Configuration variables:
+
+- **decibel_reduction** (**Required**, int, templatable): The reduction of the media stream in decibels. Must be between 0 and 50.
+- **duration** (*Optional*, :ref:`config-time`, templatable): The length of time to transition between the current reduction level and the new reduction level. Defaults to ``0s``.
+
+
+See also
+--------
+
+- :doc:`index`
+- :ghedit:`Edit`

components/speaker/resampler.rst

@@ -0,0 +1,52 @@
+Resampler Speaker
+==================
+
+.. seo::
+    :description: Instructions for setting up resampler speakers in ESPHome.
+    :image: waveform.svg
+
+The ``resampler`` speaker platform allows you to convert the sample rate of an audio stream and output it to another :doc:`speaker component </components/speaker/index>`.
+
+If the audio stream doesn't require resampling, it is automatically sent directly to the output speaker.
+
+This platform only works on ESP32 based chips.
+
+.. warning::
+
+    Audio and voice components consume a significant amount of resources (RAM and CPU) on the device.
+
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. In particular, Bluetooth/BLE components are known to cause issues when used in
+    combination with Voice Assistant and/or other audio components.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    speaker:
+      - platform: resampler
+        output_speaker: output_speaker_id
+        sample_rate: 48000
+
+Configuration variables:
+------------------------
+
+- **output_speaker** (**Required**, :ref:`config-id`): The :doc:`speaker </components/speaker/index>` to output the resampled audio.
+- **buffer_duration** (*Optional*, :ref:`config-time`): The duration of the internal ring buffer. Larger values may reduce stuttering but use more memory. Defaults to ``500ms``.
+- **bits_per_sample** (*Optional*, positive integer): The audio sample bit depth after resampling. Defaults to the output speaker's bits per sample.
+- **sample_rate** (*Optional*, positive integer): Sample rate to convert to. Must be between ``8000`` and ``48000``. Defaults to the output speaker's sample rate.
+- **filters** (*Optional*, positive integer): The number of windowed sinc interpolation filters to use. Must be between ``2`` and ``1024``. Defaults to ``16``.
+- **taps** (*Optional*, positive integer): The number of taps per windowed sinc interpolation filter. Must between ``16`` and ``128`` and divisible by 4. Defaults to ``16``.
+- **task_stack_in_psram** (*Optional* boolean): Only with ``esp-idf``. Run the audio tasks in external memory. Defaults to ``false``.
+- All other options from :ref:`Speaker Component <config-speaker>`.
+
+Improving quality
+-----------------
+
+Resampling is processor intensive and should be avoided as much as possible. The audio quality is effected by the number of filters and the number of taps. Increasing the number of filters will increase the memory load. Increasing the number of taps will increase the CPU load.
+
+See also
+--------
+
+- `ART Audio Resampler (GitHub) <https://github.com/dbry/audio-resampler>`__
+- :doc:`index`
+- :ghedit:`Edit`

index.rst

@@ -1051,6 +1051,8 @@ Speaker Components
 
     Speaker Core, components/speaker/index, speaker.svg, dark-invert
     I2S Speaker, components/speaker/i2s_audio, i2s_audio.svg
+    Mixer Speaker, components/speaker/mixer, mixer.svg
+    Resampler Speaker, components/speaker/resampler, waveform.svg
 
 Switch Components
 -----------------