From 6d10e5fd7532cc79ec77db52c84aa24781db1561 Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Sat, 23 May 2026 07:30:19 -0400 Subject: [PATCH 1/2] Add documentation for new router speaker --- src/content/docs/components/index.mdx | 1 + .../docs/components/speaker/router.mdx | 108 ++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 src/content/docs/components/speaker/router.mdx diff --git a/src/content/docs/components/index.mdx b/src/content/docs/components/index.mdx index e50bbf9856..5c37c12d00 100644 --- a/src/content/docs/components/index.mdx +++ b/src/content/docs/components/index.mdx @@ -996,6 +996,7 @@ Used for creating infrared (IR) remote control transmitters and/or receivers. ["I2S Speaker", "/components/speaker/i2s_audio/", "i2s_audio.svg"], ["Mixer Speaker", "/components/speaker/mixer/", "mixer.svg"], ["Resampler Speaker", "/components/speaker/resampler/", "waveform.svg", "dark-invert"], + ["Router Speaker", "/components/speaker/router/", "speaker.svg", "dark-invert"], ]} /> ## Switch Components diff --git a/src/content/docs/components/speaker/router.mdx b/src/content/docs/components/speaker/router.mdx new file mode 100644 index 0000000000..4f121f5571 --- /dev/null +++ b/src/content/docs/components/speaker/router.mdx @@ -0,0 +1,108 @@ +--- +description: "Instructions for setting up router speakers in ESPHome." +title: "Router Speaker" +--- + +The `router` speaker platform allows you to switch which [speaker component](/components/speaker/) receives audio at +runtime. The router acts as a single speaker that an audio producer (such as a [media player](/components/media_player/) +or a [mixer speaker](/components/speaker/mixer/)) sends audio to, and it forwards that audio to whichever output speaker +is currently active. Use the [switch output action](#router_speaker-switch_output) to change the active output while +audio is playing, for example to move playback between an I²S speaker and an +[SPDIF](/components/speaker/i2s_audio/#spdif-mode) output. + +Every output speaker must use the same audio format. The format is declared on the router so that the producer can keep +streaming through a switch without reconfiguring its output. + +This platform only works on ESP32 based chips. + +```yaml +# Example configuration entry +speaker: + - platform: router + output_speakers: + - speaker_a_id + - speaker_b_id + bits_per_sample: 16 + num_channels: 2 + sample_rate: 48000 +``` + +## Configuration Variables + +- **output_speakers** (**Required**, list of [IDs](/guides/configuration-types#id)): A list of + [speakers](/components/speaker/) the router can output to. Must have at least 2 and at most 8 speakers. The first + speaker listed is the active output when the device boots. +- **bits_per_sample** (**Required**, positive integer): The bit depth of the audio stream. Must be between `8` and `32`. + Every output speaker must use this bit depth. +- **num_channels** (**Required**, positive integer): The number of audio channels. Either `1` or `2`. Every output + speaker must use this number of channels. +- **sample_rate** (**Required**, positive integer): The sample rate of the audio stream in Hz. Must be between `8000` + and `96000`. Every output speaker must use this sample rate. + +## Automations + + + +### `router.speaker.switch_output` Action + +This action switches the active output to the specified speaker. The target must be one of the configured +`output_speakers`. + +```yaml +on_...: + - router.speaker.switch_output: + target_speaker: speaker_b_id +``` + +Configuration variables: + +- **id** (*Optional*, [ID](/guides/configuration-types#id)): The router speaker to control. Defaults to the only one in + your YAML. +- **target_speaker** (**Required**, [ID](/guides/configuration-types#id), [templatable](/automations/templates)): The + output speaker to switch to. Must be one of the configured `output_speakers`. + +> [!NOTE] +> Switching outputs while audio is playing drops any audio still buffered on the previous output. This produces a brief +> discontinuity at the moment of the switch. + +## Example + +Pairing the router with a [template select](/components/select/template/) lets the active output be chosen from the +frontend (such as Home Assistant). The select's `on_value` trigger calls the switch output action, mapping each option +to one of the configured output speakers. The two referenced speakers are +[I²S audio speakers](/components/speaker/i2s_audio/) configured elsewhere in your YAML. + +```yaml +speaker: + - platform: router + id: router_id + output_speakers: + - spdif_speaker_id + - analog_speaker_id + bits_per_sample: 16 + num_channels: 2 + sample_rate: 48000 + +select: + - platform: template + name: "Audio Output" + optimistic: true + restore_value: true + options: + - "SPDIF (TOSLINK)" + - "Analog (I2S)" + on_value: + - router.speaker.switch_output: + id: router_id + target_speaker: !lambda |- + if (x == "SPDIF (TOSLINK)") { + return id(spdif_speaker_id); + } + return id(analog_speaker_id); +``` + +## See Also + +- [Speaker Component](/components/speaker/) +- [Mixer Speaker](/components/speaker/mixer/) +- [I²S Audio Speaker](/components/speaker/i2s_audio/) From b0e3c78f59ffa1f8aae3fbfd2dd6c3af572732eb Mon Sep 17 00:00:00 2001 From: Kevin Ahrendt Date: Sat, 23 May 2026 07:38:32 -0400 Subject: [PATCH 2/2] Fix header capitalization Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/content/docs/components/speaker/router.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/components/speaker/router.mdx b/src/content/docs/components/speaker/router.mdx index 4f121f5571..e845ba44f8 100644 --- a/src/content/docs/components/speaker/router.mdx +++ b/src/content/docs/components/speaker/router.mdx @@ -27,7 +27,7 @@ speaker: sample_rate: 48000 ``` -## Configuration Variables +## Configuration variables - **output_speakers** (**Required**, list of [IDs](/guides/configuration-types#id)): A list of [speakers](/components/speaker/) the router can output to. Must have at least 2 and at most 8 speakers. The first