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 entryspeaker: - platform: i2s_audio dac_type: external i2s_dout_pin: GPIOXXConfiguration variables
Section titled “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, orstereo. Ifstereo, the input data should be twice as big, with each right sample followed by a left sample.leftandrightmute the unused channel, whilemonoplays the same samples on both. Defaults tomono. -
sample_rate (Optional, positive integer): I2S sample rate. If in
primaryI²S mode the sample rate of the audio stream is used. Defaults to16000. -
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, or32bit. Defaults to16bit. -
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 to256. -
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) orsecondary(clock driven by the attached device). Defaults toprimary. -
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_msbstand_pcm_shortstand_pcm_longi2s_msbi2s_lsbpcmpcm_shortpcm_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
neverto never stop the speaker due to a timeout. Defaults to500ms. Note: Withspdif_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 tofalse. -
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
Section titled “SPDIF Mode”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.
Hardware Setup
Section titled “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
Section titled “SPDIF Mode Constraints”When spdif_mode is enabled, the following settings are required:
- sample_rate: Only
44100Hz (CD quality) or48000Hz (DVD/DAT quality) are supported - channel: Must be set to
stereo(2 channels) - use_apll: Must be set to
truefor 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
Section titled “Example SPDIF Configuration”# Example SPDIF speaker configurationi2s_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