Skip to content
Get started

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
  • 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 width of each I²S slot sent to the DAC. Audio with a different bit depth is converted to this width. 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.

  • keep_alive (Optional, boolean): Keep the I²S channel allocated between playbacks instead of tearing it down and setting it up again. Some DAC and amplifier combinations, such as the ES8311 with an NS4150B, pop or click every time the channel is set up, so with this option only the first playback after boot makes that sound. The channel’s DMA buffers stay allocated while idle, about 10 KB of internal RAM at 48 kHz 16-bit stereo. The speaker then needs its own I²S bus with no other speaker or microphone on it, and the option is not available with spdif_mode. Defaults to false.

  • spdif_mode (Optional, boolean): Enable S/PDIF (Sony/Philips Digital Interface) mode for digital audio output. When enabled, the speaker outputs a SPDIF-encoded bitstream format suitable for optical (TOSLINK optical fiber connector) or coaxial digital audio transmission. Defaults to false.

  • All other options from Speaker Component.

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

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

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
  • channel: Must be set to stereo (2 channels)
  • 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 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
channel: stereo
timeout: never