I²S Audio Speaker

The i2s_audio speaker platform allows you to receive audio via the I2S Audio.

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): Must be external. Use an external DAC, for example the ES8311 or ES8388.

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

• 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.

• 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
  • 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. Note: With spdif_mode: true (see below), buffer underflows are filled with silence frames until the specified interval elapses; this maintains the SPDIF signal to prevent the receiver from detecting a loss of signal/source change, which may otherwise lengthen gaps of silence.

• 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. Defaults to false.

• All other options from Speaker Component.

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 settings are required:

• 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
• use_apll: Must be set to true for accurate clock generation
• i2s_mode: Must be set to primary
• i2s_comm_fmt: Must be set to stand_i2s
• mclk_multiple: Must be set to 256

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: GPIOXX
    spdif_mode: true
    use_apll: true
    sample_rate: 48000
    bits_per_sample: 16bit
    channel: stereo
    timeout: never

See Also

• Speaker Component