From 575cbfb74f2691d6608da76b1fc5e4572078a91e Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Fri, 31 Jan 2025 10:29:31 -0500 Subject: [PATCH 1/4] 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/4] 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/4] 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 2d1903f46978262c3b156bd57df24b7dc6294154 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Wed, 5 Feb 2025 09:50:54 +1300 Subject: [PATCH 4/4] Update index.rst --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.rst b/index.rst index b7bf627fb8..f98621c632 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, waveform.svg + Resampler Speaker, components/speaker/resampler, waveform.svg, dark-invert Switch Components -----------------