From 575cbfb74f2691d6608da76b1fc5e4572078a91e Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Fri, 31 Jan 2025 10:29:31 -0500 Subject: [PATCH 1/7] document resampler speaker --- components/speaker/resampler.rst | 52 ++++++++++++++++++++++++++++++++ images/resampler.svg | 1 + index.rst | 1 + 3 files changed, 54 insertions(+) create mode 100644 components/speaker/resampler.rst create mode 100644 images/resampler.svg diff --git a/components/speaker/resampler.rst b/components/speaker/resampler.rst new file mode 100644 index 0000000000..cf95b26470 --- /dev/null +++ b/components/speaker/resampler.rst @@ -0,0 +1,52 @@ +Resampler Speaker +================== + +.. seo:: + :description: Instructions for setting up resampler speakers in ESPHome. + :image: resampler.svg + +The ``resampler`` speaker platform allows you to convert the sample rate of an audio stream and output it to other :doc:`/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 ` 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 `. + +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) `__ +- :doc:`index` +- :ghedit:`Edit` diff --git a/images/resampler.svg b/images/resampler.svg new file mode 100644 index 0000000000..382224da85 --- /dev/null +++ b/images/resampler.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 5aa903f660..9a4f741671 100644 --- a/index.rst +++ b/index.rst @@ -1051,6 +1051,7 @@ Speaker Components Speaker Core, components/speaker/index, speaker.svg, dark-invert I2S Speaker, components/speaker/i2s_audio, i2s_audio.svg + Resampler Speaker, components/speaker/resampler, resampler.svg Switch Components ----------------- From 66957cf8dae9769c45841c5cc46dc023d1847bb7 Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Fri, 31 Jan 2025 10:49:05 -0500 Subject: [PATCH 2/7] override the linked name for better grammar --- components/speaker/resampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/speaker/resampler.rst b/components/speaker/resampler.rst index cf95b26470..4104df67e9 100644 --- a/components/speaker/resampler.rst +++ b/components/speaker/resampler.rst @@ -5,7 +5,7 @@ Resampler Speaker :description: Instructions for setting up resampler speakers in ESPHome. :image: resampler.svg -The ``resampler`` speaker platform allows you to convert the sample rate of an audio stream and output it to other :doc:`/components/speaker/index`. +The ``resampler`` speaker platform allows you to convert the sample rate of an audio stream and output it to another :doc:`speaker component `. If the audio stream doesn't require resampling, it is automatically sent directly to the output speaker. From 0d4c7e3261691e8ff8192267c4074555638f248d Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Tue, 4 Feb 2025 15:24:39 -0500 Subject: [PATCH 3/7] use waveform icon --- components/speaker/resampler.rst | 2 +- images/resampler.svg | 1 - images/waveform.svg | 1 + index.rst | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) delete mode 100644 images/resampler.svg create mode 100644 images/waveform.svg diff --git a/components/speaker/resampler.rst b/components/speaker/resampler.rst index 4104df67e9..5fa23a7962 100644 --- a/components/speaker/resampler.rst +++ b/components/speaker/resampler.rst @@ -3,7 +3,7 @@ Resampler Speaker .. seo:: :description: Instructions for setting up resampler speakers in ESPHome. - :image: resampler.svg + :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 `. diff --git a/images/resampler.svg b/images/resampler.svg deleted file mode 100644 index 382224da85..0000000000 --- a/images/resampler.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/images/waveform.svg b/images/waveform.svg new file mode 100644 index 0000000000..a7e632f823 --- /dev/null +++ b/images/waveform.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 9a4f741671..b7bf627fb8 100644 --- a/index.rst +++ b/index.rst @@ -1051,7 +1051,7 @@ Speaker Components Speaker Core, components/speaker/index, speaker.svg, dark-invert I2S Speaker, components/speaker/i2s_audio, i2s_audio.svg - Resampler Speaker, components/speaker/resampler, resampler.svg + Resampler Speaker, components/speaker/resampler, waveform.svg Switch Components ----------------- From c9ead30d873a9feb44a3903e88d6805678a71026 Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Fri, 31 Jan 2025 10:50:07 -0500 Subject: [PATCH 4/7] document mixer speaker --- components/speaker/mixer.rst | 75 ++++++++++++++++++++++++++++++++++++ images/mixer.svg | 1 + index.rst | 1 + 3 files changed, 77 insertions(+) create mode 100644 components/speaker/mixer.rst create mode 100644 images/mixer.svg diff --git a/components/speaker/mixer.rst b/components/speaker/mixer.rst new file mode 100644 index 0000000000..d6a81695f6 --- /dev/null +++ b/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 `. Individual source speakers may be ducked (made quieter) with the :ref:`apply ducking action `. + +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 ` 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 ` 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 `. + +- **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` diff --git a/images/mixer.svg b/images/mixer.svg new file mode 100644 index 0000000000..8102917b17 --- /dev/null +++ b/images/mixer.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index b7bf627fb8..5c5610ee10 100644 --- a/index.rst +++ b/index.rst @@ -1051,6 +1051,7 @@ 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 From a926b0a564a236284ac820e30d8659ee682b9a53 Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Fri, 31 Jan 2025 11:27:09 -0500 Subject: [PATCH 5/7] list apply ducking action --- automations/all_actions.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/automations/all_actions.rst b/automations/all_actions.rst index dadff78a62..4ab5a52b5e 100644 --- a/automations/all_actions.rst +++ b/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`` From a168053cd7d1135a4f4ec091cd342c790e23ce35 Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Fri, 31 Jan 2025 12:26:35 -0500 Subject: [PATCH 6/7] lint fix --- components/speaker/mixer.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/components/speaker/mixer.rst b/components/speaker/mixer.rst index d6a81695f6..124df1912a 100644 --- a/components/speaker/mixer.rst +++ b/components/speaker/mixer.rst @@ -21,13 +21,13 @@ This platform only works on ESP32 based chips. .. 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 + # 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: ------------------------ From 9a05f3c3b188b224f48b17738ea99530cd4abd6d Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 10 Feb 2025 10:49:52 +1300 Subject: [PATCH 7/7] Apply suggestions from code review --- components/speaker/mixer.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/speaker/mixer.rst b/components/speaker/mixer.rst index 124df1912a..ed346d5dbb 100644 --- a/components/speaker/mixer.rst +++ b/components/speaker/mixer.rst @@ -32,7 +32,7 @@ This platform only works on ESP32 based chips. Configuration variables: ------------------------ -- **output_speaker** (**Required**, :ref:`config-id`): The :doc:`speaker ` to output the resampled audio. +- **output_speaker** (**Required**, :ref:`config-id`): The :doc:`speaker ` to output the mixed 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``. @@ -52,7 +52,7 @@ Automations ``mixer_speaker.apply_ducking`` Action ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This action ducks (reduces the volume) of the media stream. +This action ducks (reduces the volume of) the media stream. .. code-block::