Skip to content
Get started

I²S Audio Component

The i2s_audio component allows for sending and receiving audio via I²S. This component only works on ESP32 based chips.

# Example configuration entry
i2s_audio:
i2s_lrclk_pin: GPIOXX
i2s_bclk_pin: GPIOXX
  • i2s_lrclk_pin (Required, Pin): The GPIO pin to use for the I²S LRCLK (Left/Right Clock) signal, also referred to as WS (Word Select) or FS (Frame Sync).
  • i2s_bclk_pin (Optional, Pin): The GPIO pin to use for the I²S BCLK (Bit Clock) signal, also referred to as SCK (Serial Clock).
  • i2s_mclk_pin (Optional, Pin): The GPIO pin to use for the I²S MCLK (Master Clock) signal.
  • id (Optional, ID): Manually specify the ID for this I²S bus if you need multiple.
  • full_duplex (Optional, boolean): Run a microphone and a speaker at the same time on this bus. See Full Duplex. Defaults to false.

By default, a microphone and a speaker on the same I²S bus cannot run at the same time: while one is active, the other has to wait. This prevents a device with a single I²S codec from recording while it plays audio.

With full_duplex: true, the microphone and speaker run at the same time on the same I²S port and share its bit clock and word clock. Both I²S channels are set up once at boot and kept for the lifetime of the device.

A full duplex bus must meet these requirements, which are checked when the configuration is validated:

  • Exactly one I²S Audio Microphone and at least one I²S Audio Speaker use the bus.
  • The microphone is not a PDM microphone.
  • The speakers do not use spdif_mode.
  • The microphone and every speaker use the same sample_rate, bits_per_sample, i2s_mode, use_apll and mclk_multiple, because both directions run from the same clocks. Note that bits_per_sample has a different default for the microphone (32bit) and the speaker (16bit), so set it explicitly on both.
  • All speakers use the same i2s_dout_pin, channel and i2s_comm_fmt, because they share one output channel.

Because the output channel is set up only once, a speaker on a full duplex bus only accepts audio that matches its configured sample_rate and number of channels (channel: stereo takes two channel audio, mono, left and right take one channel audio) and whose bits per sample is the configured bits_per_sample or wider. Wider samples are narrowed to the configured width. A stream that does not match is rejected and a message is logged. Put a Resampler Speaker in front of the speaker to convert the sample rate and to widen the samples when the bus uses more bits than the source. A resampler does not change the number of channels, so a speaker with channel: mono, left or right also needs a Mixer Speaker with num_channels: 1; see the mono example below.

More than one speaker can use a full duplex bus, for example a media speaker and an announcement speaker that a Router Speaker switches between. They share the one output channel, so only one of them can play at a time. Two DACs wired to the same data pin both play whatever is on the line; choosing one needs a mute or enable control on each DAC, which the router does not provide.

# Example full duplex configuration
i2s_audio:
- id: i2s_duplex_bus
i2s_lrclk_pin: GPIOXX
i2s_bclk_pin: GPIOXX
full_duplex: true
microphone:
- platform: i2s_audio
i2s_audio_id: i2s_duplex_bus
i2s_din_pin: GPIOXX
adc_type: external
sample_rate: 48000
bits_per_sample: 32bit
speaker:
- platform: i2s_audio
id: duplex_speaker
i2s_audio_id: i2s_duplex_bus
i2s_dout_pin: GPIOXX
dac_type: external
# stereo, so stereo sources play without a mixer
channel: stereo
sample_rate: 48000
bits_per_sample: 32bit
# Converts incoming audio to the sample rate and bits per sample of the full duplex bus
- platform: resampler
output_speaker: duplex_speaker
bits_per_sample: 32

A speaker with channel: mono only accepts one channel audio. The mixer converts stereo sources to one channel, and the resamplers convert each source to the sample rate and bits per sample of the bus.

speaker:
- platform: i2s_audio
id: duplex_speaker
i2s_audio_id: i2s_duplex_bus
i2s_dout_pin: GPIOXX
dac_type: external
channel: mono
sample_rate: 48000
bits_per_sample: 32bit
- platform: mixer
output_speaker: duplex_speaker
num_channels: 1
source_speakers:
- id: announcement_mixer_input
- id: media_mixer_input
- platform: resampler
id: announcement_resampler
output_speaker: announcement_mixer_input
bits_per_sample: 32
- platform: resampler
id: media_resampler
output_speaker: media_mixer_input
bits_per_sample: 32