Abstract base class for I2S audio speaker implementations. More...

#include <i2s_audio_speaker.h>

Inheritance diagram for esphome::i2s_audio::I2SAudioSpeakerBase:

Public Member Functions
float	get_setup_priority () const override

void	setup () override

void	dump_config () override

void	loop () override

void	set_buffer_duration (uint32_t buffer_duration_ms)

void	set_timeout (uint32_t ms)

void	set_keep_alive (bool keep_alive)

void	set_dout_pin (uint8_t pin)

i2s_chan_handle_t	get_tx_handle () const
	Get the I2S TX channel handle.

void	start () override

void	stop () override

void	finish () override

void	set_pause_state (bool pause_state) override

bool	get_pause_state () const override

void	swap_esp32_mono_samples_ (uint8_t *data, size_t bytes_read)
	Plays the provided audio data.

Public Member Functions inherited from esphome::i2s_audio::I2SAudioOut
virtual void	build_full_duplex_config (i2s_chan_config_t &chan_cfg, i2s_std_config_t &std_cfg)
	Builds the TX configuration the parent uses to set up a full duplex channel pair.

Public Member Functions inherited from esphome::i2s_audio::I2SAudioBase
void	set_i2s_role (i2s_role_t role)

void	set_slot_mode (i2s_slot_mode_t slot_mode)

void	set_std_slot_mask (i2s_std_slot_mask_t std_slot_mask)

void	set_slot_bit_width (i2s_slot_bit_width_t slot_bit_width)

void	set_sample_rate (uint32_t sample_rate)

void	set_use_apll (uint32_t use_apll)

void	set_mclk_multiple (i2s_mclk_multiple_t mclk_multiple)

Public Member Functions inherited from esphome::Parented< I2SAudioComponent >
	Parented ()

	Parented (I2SAudioComponent *parent)

I2SAudioComponent *	get_parent () const
	Get the parent of this object.

void	set_parent (I2SAudioComponent *parent)
	Set the parent of this object.

Public Member Functions inherited from esphome::speaker::Speaker
virtual size_t	play (const uint8_t *data, size_t length)=0
	Plays the provided audio data.

size_t	play (const std::vector< uint8_t > &data)

virtual bool	has_buffered_data () const =0

bool	is_running () const

bool	is_stopped () const

virtual void	set_volume (float volume)

virtual float	get_volume ()

virtual void	set_mute_state (bool mute_state)

virtual bool	get_mute_state ()

void	set_audio_dac (audio_dac::AudioDac *audio_dac)

void	set_audio_stream_info (const audio::AudioStreamInfo &audio_stream_info)

audio::AudioStreamInfo &	get_audio_stream_info ()

template<typename F >
void	add_audio_output_callback (F &&callback)
	Callback function for sending the duration of the audio written to the speaker since the last callback.

Public Member Functions inherited from esphome::Component
float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

virtual bool	teardown ()
	Called during teardown to allow component to gracefully finish operations.

virtual void	on_powerdown ()
	Called after teardown is complete to power down hardware.

uint8_t	get_component_state () const

void	reset_to_construction_state ()
	Reset this component back to the construction state to allow setup to run again.

bool	is_in_loop_state () const
	Check if this component has completed setup and is in the loop state.

bool	is_idle () const
	Check if this component is idle.

void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const LogString *message)

void	disable_loop ()
	Disable this component's loop.

void	enable_loop ()
	Enable this component's loop.

void	enable_loop_soon_any_context ()
	Thread and ISR-safe version of enable_loop() that can be called from any context.

bool	is_failed () const

bool	is_ready () const

virtual bool	can_proceed ()

bool	status_has_warning () const

bool	status_has_error () const

void	status_set_warning ()

void	status_set_warning (const char *message)

void	status_set_warning (const LogString *message)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

	ESPDEPRECATED ("Use status_momentary_warning() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_warning(const char *name

void	status_momentary_warning (uint32_t length=5000)
	Set warning status flag and clear it after `length` ms.

void	status_momentary_warning (const LogString *message, uint32_t length=5000)

	ESPDEPRECATED ("Use status_momentary_error() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_error(const char *name

void	status_momentary_error (uint32_t length=5000)
	Set error status flag and clear it after `length` ms.

void	status_momentary_error (const LogString *message, uint32_t length=5000)

bool	has_overridden_loop () const

const LogString *	get_component_log_str () const ESPHOME_ALWAYS_INLINE
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)

Data Fields
TaskHandle_t	speaker_task_handle_ {nullptr}

EventGroupHandle_t	event_group_ {nullptr}

QueueHandle_t	i2s_event_queue_ {nullptr}

QueueHandle_t	write_records_queue_ {nullptr}

std::weak_ptr< ring_buffer::RingBuffer >	audio_ring_buffer_

uint32_t	buffer_duration_ms_

optional< uint32_t >	timeout_

optional< audio::AudioStreamInfo >	rejected_stream_info_

bool	pause_state_ {false}

bool	keep_alive_ {false}

esp_audio_libs::gain::GainRamp	gain_ramp_

audio::AudioStreamInfo	current_stream_info_

audio::AudioStreamInfo	output_stream_info_

gpio_num_t	dout_pin_

i2s_chan_handle_t	tx_handle_ {nullptr}

Data Fields inherited from esphome::Component
uint32_t	length = 5000)

Additional Inherited Members
Protected Member Functions inherited from esphome::i2s_audio::I2SAudioBase
i2s_clock_src_t	get_clock_source_ () const

Protected Member Functions inherited from esphome::speaker::Speaker
bool	is_silent_ () const
	Whether the output should be silent: muted, or the volume is effectively zero.

void	apply_audio_dac_mute_ ()
	Uses the audio dac's mute as the silence mechanism, since a dac's minimum volume is often audible.

Protected Member Functions inherited from esphome::Component
friend	void::setup ()

friend	void::original_setup ()

void	set_component_source_ (uint8_t index)
	Set where this component was loaded from for some debug messages.

virtual void	call_setup ()

void	call_dump_config_ ()

void	enable_loop_slow_path_ ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

bool	set_status_flag_ (uint8_t flag)
	Helper to set a status LED flag on both this component and the app.

bool	set_error_flag_ (const LogString *message)
	Set the error flag and log it; true when it was not set before.

void	set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a const char* name.

void	set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a numeric ID (zero heap allocation).

void	set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const char *name)
	Cancel an interval function.

bool	cancel_interval (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

void	set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a const char* name.

void	set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a numeric ID (zero heap allocation).

void	set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const char *name)
	Cancel a timeout function.

bool	cancel_timeout (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

void	defer (const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call with a const char* name.

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call.

void	defer (uint32_t id, std::function< void()> &&f)
	Defer a callback with a numeric ID (zero heap allocation)

bool	cancel_defer (const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

bool	cancel_defer (uint32_t id)

void	status_clear_warning_slow_path_ ()

void	status_clear_error_slow_path_ ()

Protected Attributes inherited from esphome::i2s_audio::I2SAudioBase
i2s_role_t	i2s_role_ {}

i2s_slot_mode_t	slot_mode_

i2s_std_slot_mask_t	std_slot_mask_

i2s_slot_bit_width_t	slot_bit_width_

uint32_t	sample_rate_

bool	use_apll_

i2s_mclk_multiple_t	mclk_multiple_

Protected Attributes inherited from esphome::Parented< I2SAudioComponent >
I2SAudioComponent *	parent_

Protected Attributes inherited from esphome::speaker::Speaker
State	state_ {STATE_STOPPED}

bool	mute_state_ {false}

audio::AudioStreamInfo	audio_stream_info_

float	volume_ {1.0f}

audio_dac::AudioDac *	audio_dac_ {nullptr}

CallbackManager< void(uint32_t, int64_t)>	audio_output_callback_ {}

Protected Attributes inherited from esphome::Component
uint8_t	component_source_index_ {0}
	Index into component source PROGMEM lookup table (0 = not set)

uint8_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
	Warn threshold in centiseconds (max 2550ms)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

ComponentRuntimeStats	runtime_stats_

Detailed Description

Abstract base class for I2S audio speaker implementations.

Provides shared infrastructure (event groups, ring buffer, volume control, task lifecycle) for derived standard I2S and SPDIF speaker classes.

Definition at line 47 of file i2s_audio_speaker.h.

Member Function Documentation

◆ dump_config()

void esphome::i2s_audio::I2SAudioSpeakerBase::dump_config ( )

overridevirtual

Reimplemented from esphome::Component.

Reimplemented in esphome::i2s_audio::I2SAudioSpeakerSPDIF.

Definition at line 66 of file i2s_audio_speaker.cpp.

◆ finish()

void esphome::i2s_audio::I2SAudioSpeakerBase::finish ( )

overridevirtual

Reimplemented from esphome::speaker::Speaker.

Definition at line 278 of file i2s_audio_speaker.cpp.

◆ get_pause_state()

bool esphome::i2s_audio::I2SAudioSpeakerBase::get_pause_state ( ) const

inlineoverridevirtual

Reimplemented from esphome::speaker::Speaker.

Definition at line 68 of file i2s_audio_speaker.h.

◆ get_setup_priority()

float esphome::i2s_audio::I2SAudioSpeakerBase::get_setup_priority ( ) const

inlineoverridevirtual

Reimplemented from esphome::Component.

Definition at line 49 of file i2s_audio_speaker.h.

◆ get_tx_handle()

i2s_chan_handle_t esphome::i2s_audio::I2SAudioSpeakerBase::get_tx_handle ( ) const

inline

Get the I2S TX channel handle.

Definition at line 61 of file i2s_audio_speaker.h.

◆ loop()

void esphome::i2s_audio::I2SAudioSpeakerBase::loop ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 78 of file i2s_audio_speaker.cpp.

◆ set_buffer_duration()

void esphome::i2s_audio::I2SAudioSpeakerBase::set_buffer_duration ( uint32_t buffer_duration_ms )

inline

Definition at line 55 of file i2s_audio_speaker.h.

◆ set_dout_pin()

void esphome::i2s_audio::I2SAudioSpeakerBase::set_dout_pin ( uint8_t pin )

inline

Definition at line 58 of file i2s_audio_speaker.h.

◆ set_keep_alive()

void esphome::i2s_audio::I2SAudioSpeakerBase::set_keep_alive ( bool keep_alive )

inline

Definition at line 57 of file i2s_audio_speaker.h.

◆ set_pause_state()

void esphome::i2s_audio::I2SAudioSpeakerBase::set_pause_state ( bool pause_state )

inlineoverridevirtual

Reimplemented from esphome::speaker::Speaker.

Definition at line 67 of file i2s_audio_speaker.h.

◆ set_timeout()

void esphome::i2s_audio::I2SAudioSpeakerBase::set_timeout ( uint32_t ms )

inline

Definition at line 56 of file i2s_audio_speaker.h.

◆ setup()

void esphome::i2s_audio::I2SAudioSpeakerBase::setup ( )

overridevirtual

Reimplemented from esphome::Component.

Reimplemented in esphome::i2s_audio::I2SAudioSpeakerSPDIF.

Definition at line 30 of file i2s_audio_speaker.cpp.

◆ start()

void esphome::i2s_audio::I2SAudioSpeakerBase::start ( )

overridevirtual

Implements esphome::speaker::Speaker.

Definition at line 264 of file i2s_audio_speaker.cpp.

◆ stop()

void esphome::i2s_audio::I2SAudioSpeakerBase::stop ( )

overridevirtual

Implements esphome::speaker::Speaker.

Definition at line 276 of file i2s_audio_speaker.cpp.

◆ swap_esp32_mono_samples_()

void esphome::i2s_audio::I2SAudioSpeakerBase::swap_esp32_mono_samples_	(	uint8_t *	data,
		size_t	bytes_read )

Plays the provided audio data.

Starts the speaker task, if necessary. Writes the audio data to the ring buffer.

Parameters

data	Audio data in the format set by the parent speaker classes `set_audio_stream_info` method. /
length	The length of the audio data in bytes. /
ticks_to_wait	The FreeRTOS ticks to wait before writing as much data as possible to the ring buffer. /

Returns: The number of bytes that were actually written to the ring buffer. size_t play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) override; size_t play(const uint8_t *data, size_t length) override { return play(data, length, 0); }

bool has_buffered_data() const override;

/ Sets the volume of the speaker. Uses the speaker's configured audio dac component. If unavailable, it is / implemented as a software volume control. Overrides the default setter to convert the volume to a dB target for / the gain ramp. /

Parameters

volume between 0.0 and 1.0 void set_volume(float volume) override;

/ Mutes or unmutes the speaker. Uses the speaker's configured audio dac component. If unavailable, it is / implemented as a software volume control. Overrides the default setter to post the mute state to the gain ramp. /

Parameters

mute_state true for muting, false for unmuting void set_mute_state(bool mute_state) override;

protected: / Posts the ramp target derived from the current volume and mute state. No-op when an audio dac owns / volume. Main loop only. /

Parameters

rate_samples Samples the ramp takes per dB of change; 0 adopts the target at once void post_software_gain_(uint32_t rate_samples);

/ FreeRTOS task entry point. Casts params to I2SAudioSpeakerBase and calls run_speaker_task_(). /

Parameters

params I2SAudioSpeakerBase component pointer static void speaker_task(void *params);

/ The main speaker task loop. Implemented by derived classes for mode-specific behavior. virtual void run_speaker_task() = 0;

/ Sends a stop command to the speaker task via event_group_. /

Parameters

wait_on_empty If false, sends the COMMAND_STOP signal. If true, sends the COMMAND_STOP_GRACEFULLY signal. void stop_(bool wait_on_empty);

/ Callback function used to send playback timestamps to the speaker task. /

Parameters

handle	(i2s_chan_handle_t) /
event	(i2s_event_data_t) /
user_ctx	(void*) User context pointer that the callback accesses /

Returns: True if a higher priority task was interrupted static bool i2s_on_sent_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx);

/ Starts the ESP32 I2S driver. Implemented by derived classes for mode-specific configuration. /

Parameters

audio_stream_info Stream information for the I2S driver. /

Returns: ESP_OK if successful, or an error code virtual esp_err_t start_i2s_driver(audio::AudioStreamInfo &audio_stream_info) = 0;

/ Shared I2S channel allocation, initialization, and event queue setup. / Called by derived start_i2s_driver_() implementations after building mode-specific configs. /

Parameters

chan_cfg	I2S channel configuration /
std_cfg	I2S standard mode configuration (clock, slot, GPIO) /
event_queue_size	Size of the event queue /

Returns: ESP_OK if successful, or an error code. On failure, cleans up channel and unlocks parent. esp_err_t init_i2s_channel_(const i2s_chan_config_t &chan_cfg, const i2s_std_config_t &std_cfg, size_t event_queue_size);

/ Creates the lockstep queues unless they exist already. /

Parameters

event_queue_size Size of each queue /

Returns: ESP_OK if successful, or ESP_ERR_NO_MEM esp_err_t prepare_event_queues_(size_t event_queue_size);

#ifdef USE_I2S_AUDIO_FULL_DUPLEX / Takes the TX channel of the parent's full duplex pair and prepares the event queues. /

Parameters

event_queue_size Size of the event queue /

Returns: ESP_OK if successful, or an error code. On failure, hands the channel back to the parent. esp_err_t acquire_full_duplex_channel_(size_t event_queue_size); #endif

/ Stops the I2S driver and unlocks the I2S port; keep_channel leaves the disabled channel allocated void stop_i2s_driver_(bool keep_channel);

/ Detaches dout from the I2S signal and drives it low void park_dout_pin_();

/ Deletes the I2S channel and parks dout; the caller holds the bus lock void delete_channel_();

/ Called in loop() when the task has stopped. Override for mode-specific cleanup. virtual void on_task_stopped() {}

/ Rebuilds the lockstep queues in place: disables the channel, credits every in-flight real frame as / played now, empties both queues, preloads silence through preload and re-enables the channel. Speaker / task only. /

Parameters

extra_frames	Real frames the caller consumed that never reached a write record /
preload	Callable returning true once every DMA descriptor holds silence with a matching record /

Returns: false if the preload or the channel enable failed; the caller should restart the task template<typename F> bool resync_lockstep_(uint32_t extra_frames, F &&preload) { this->drain_lockstep_(extra_frames); return preload() && (i2s_channel_enable(this->tx_handle_) == ESP_OK); }

/ Disables the channel, credits extra_frames plus every real frame still recorded as in flight, / and empties both lockstep queues. void drain_lockstep_(uint32_t extra_frames);

/ Apply software volume control by running the samples through the gain ramp. Called from the / speaker task only. /

Parameters

data	Pointer to audio sample data (modified in place) /
bytes_read	Number of bytes of audio data void apply_software_volume_(uint8_t *data, size_t bytes_read);

/ Whether 16-bit mono samples in this format need the ESP32 (non-variant) pair swap. static bool esp32_mono_swap_needed(const audio::AudioStreamInfo &stream_info); / Whether the output is 16-bit mono on the original ESP32, which sends each pair of samples swapped. bool esp32_mono_swap_needed_() const { return esp32_mono_swap_needed(this->output_stream_info_); }

/ Swap adjacent 16-bit mono samples for ESP32 (non-variant) hardware quirk. / Only applies when esp32_mono_swap_needed_() is true. data must start on a DMA word and hold whole pairs.

Parameters

data	Pointer to audio sample data (modified in place)
bytes_read	Number of bytes of audio data

Definition at line 447 of file i2s_audio_speaker.cpp.

Field Documentation

◆ audio_ring_buffer_

std::weak_ptr<ring_buffer::RingBuffer> esphome::i2s_audio::I2SAudioSpeakerBase::audio_ring_buffer_

Definition at line 193 of file i2s_audio_speaker.h.

◆ buffer_duration_ms_

uint32_t esphome::i2s_audio::I2SAudioSpeakerBase::buffer_duration_ms_

Definition at line 195 of file i2s_audio_speaker.h.

◆ current_stream_info_

audio::AudioStreamInfo esphome::i2s_audio::I2SAudioSpeakerBase::current_stream_info_

Definition at line 209 of file i2s_audio_speaker.h.

◆ dout_pin_

gpio_num_t esphome::i2s_audio::I2SAudioSpeakerBase::dout_pin_

Definition at line 215 of file i2s_audio_speaker.h.

◆ event_group_

EventGroupHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::event_group_ {nullptr}

Definition at line 187 of file i2s_audio_speaker.h.

◆ gain_ramp_

esp_audio_libs::gain::GainRamp esphome::i2s_audio::I2SAudioSpeakerBase::gain_ramp_

Definition at line 207 of file i2s_audio_speaker.h.

◆ i2s_event_queue_

QueueHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::i2s_event_queue_ {nullptr}

Definition at line 190 of file i2s_audio_speaker.h.

◆ keep_alive_

bool esphome::i2s_audio::I2SAudioSpeakerBase::keep_alive_ {false}

Definition at line 203 of file i2s_audio_speaker.h.

◆ output_stream_info_

audio::AudioStreamInfo esphome::i2s_audio::I2SAudioSpeakerBase::output_stream_info_

Definition at line 213 of file i2s_audio_speaker.h.

◆ pause_state_

bool esphome::i2s_audio::I2SAudioSpeakerBase::pause_state_ {false}

Definition at line 202 of file i2s_audio_speaker.h.

◆ rejected_stream_info_

optional<audio::AudioStreamInfo> esphome::i2s_audio::I2SAudioSpeakerBase::rejected_stream_info_

Definition at line 200 of file i2s_audio_speaker.h.

◆ speaker_task_handle_

TaskHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::speaker_task_handle_ {nullptr}

Definition at line 186 of file i2s_audio_speaker.h.

◆ timeout_

optional<uint32_t> esphome::i2s_audio::I2SAudioSpeakerBase::timeout_

Definition at line 197 of file i2s_audio_speaker.h.

◆ tx_handle_

i2s_chan_handle_t esphome::i2s_audio::I2SAudioSpeakerBase::tx_handle_ {nullptr}

Definition at line 216 of file i2s_audio_speaker.h.

◆ write_records_queue_

QueueHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::write_records_queue_ {nullptr}

Definition at line 191 of file i2s_audio_speaker.h.

The documentation for this class was generated from the following files:

esphome/components/i2s_audio/speaker/i2s_audio_speaker.h
esphome/components/i2s_audio/speaker/i2s_audio_speaker.cpp

Public Member Functions

Data Fields

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ dump_config()

◆ finish()

◆ get_pause_state()

◆ get_setup_priority()

◆ get_tx_handle()

◆ loop()

◆ set_buffer_duration()

◆ set_dout_pin()

◆ set_keep_alive()

◆ set_pause_state()

◆ set_timeout()

◆ setup()

◆ start()

◆ stop()

◆ swap_esp32_mono_samples_()

Field Documentation

◆ audio_ring_buffer_

◆ buffer_duration_ms_

◆ current_stream_info_

◆ dout_pin_

◆ event_group_

◆ gain_ramp_

◆ i2s_event_queue_

◆ keep_alive_

◆ output_stream_info_

◆ pause_state_

◆ rejected_stream_info_

◆ speaker_task_handle_

◆ timeout_

◆ tx_handle_

◆ write_records_queue_