I²S Audio Speaker

The i2s_audio speaker platform allows you to receive audio via the the I²S Audio Component.

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.

# Example configuration entry
speaker:
  - platform: i2s_audio
    dac_type: external
    i2s_dout_pin: GPIOXX

Configuration variables

• dac_type (Required, enum):

  • external : Use an external DAC, for example the NS4168, or UDA1334A.
  • internal : Use the internal DAC

• channel (Optional, enum): The channel of the speaker. One of left, right, mono, or stereo. If stereo, the input data should be twice as big, with each right sample followed by a left sample. left and right mute the unused channel, while mono plays the same samples on both. Defaults to mono.

• sample_rate (Optional, positive integer): I2S sample rate. If in primary I²S mode the sample rate of the audio stream is used. Defaults to 16000.

• bits_per_sample (Optional, enum): The bit depth of the audio samples sent to the DAC. One of 8bit, 16bit, 24bit, or 32bit. Defaults to 16bit.

• bits_per_channel (Optional, enum): The bit depth of the audio channels. This is what is actually send to the DAC and needs to be equal or larger than bits_per_sample. See the datasheet of your I2S device for details. Defaults to bits_per_sample. Setting is ignored if the legacy driver is not used.

• mclk_multiple (Optional, enum): The multiple of the MCLK frequency to the sample rate. Must be divisible by 3 if using 24 bits per sample. One of 128, 256, 384, 512. Defaults to 256.

• use_apll (Optional, boolean): I2S using APLL as main I2S clock, enable it to get accurate clock. Defaults to false.

• i2s_mode (Optional, enum): The I²S mode to use. One of primary (clock driven by the host) or secondary (clock driven by the attached device). Defaults to primary.

• i2s_audio_id (Optional, ID): The ID of the I²S Audio you wish to use for this speaker.

• i2s_comm_fmt (Optional, enum): The I²S communication standard format used by this speaker.

  • stand_i2s (Default)
  • stand_msb
  • stand_pcm_short
  • stand_pcm_long
  • stand_max (only with legacy driver)
  • i2s_msb
  • i2s_lsb
  • pcm
  • pcm_short
  • pcm_long

• buffer_duration (Optional, Time): The duration of the internal ring buffer. Larger values can reduce stuttering but uses more memory. Defaults to 500ms.

• timeout (Optional, 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 Speaker Component.

External DAC

• i2s_dout_pin (Required, Pin Schema): The GPIO pin to use for the I²S DOUT (Data Out) signal.

For best results, keep the wires as short as possible.

Internal DAC

ℹ️ Note

Internal DAC speakers are only supported by the legacy I²S driver on a regular ESP32, not the variants.

• mode (Required, enum): The channel mode of the internal DAC.

  • left
  • right
  • stereo

See also

• Speaker Components