I²S Audio Speaker

The i2s_audio speaker platform allows you to receive audio via 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
spdif_mode (Optional, boolean): Enable SPDIF (Sony/Philips Digital Interface Format) mode for digital audio output. When enabled, the speaker outputs a SPDIF-encoded bitstream suitable for optical (TOSLINK) or coaxial digital audio transmission. Only available with the legacy I²S driver. Defaults to false.
fill_silence (Optional, boolean): When SPDIF mode is enabled, fills buffer underflows with silence frames to prevent the receiver from detecting a source change. Only supported when spdif_mode is true. Defaults to false.
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

SPDIF Mode

SPDIF (Sony/Philips Digital Interface Format) mode enables digital audio transmission over optical (TOSLINK) or coaxial connections. This mode encodes PCM audio data into a SPDIF bitstream that can be received by soundbars, A/V receivers, DACs, and other digital audio equipment.

Hardware Setup

For optical SPDIF transmission, you can use:

Simple LED: Any LED (even a debug LED on your dev board) can transmit SPDIF audio. Place an optical cable near the LED.
TOSLINK Transmitter Module: Dedicated optical transmitter modules provide a proper TOSLINK connector for reliable connections.

The transmitter is connected to the i2s_dout_pin (the same pin used for standard I²S data output).

SPDIF Mode Constraints

When spdif_mode is enabled, the following constraints apply:

Sample Rate: Only 44100 Hz (CD quality) or 48000 Hz (DVD/DAT quality) are supported
Channels: Must be set to stereo (2 channels)
Bits per Sample: Must be set to 16bit
I²S Driver: Only works with the legacy I²S driver
I²S Mode: Typically used in primary mode

Example SPDIF Configuration

# Example SPDIF speaker configuration
i2s_audio:
  - id: i2s_output

speaker:
  - platform: i2s_audio
    id: spdif_speaker
    dac_type: external
    i2s_audio_id: i2s_output
    i2s_dout_pin: GPIO13
    spdif_mode: true
    fill_silence: true
    sample_rate: 48000
    bits_per_sample: 16bit
    channel: stereo
    buffer_duration: 80ms
    timeout: never