|
ESPHome 2026.5.0b1
|
Abstract base class for I2S audio speaker implementations. More...
#include <i2s_audio_speaker.h>
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_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 | stop_ (bool wait_on_empty) |
| Plays the provided audio data. | |
| virtual esp_err_t | start_i2s_driver (audio::AudioStreamInfo &audio_stream_info)=0 |
| Starts the ESP32 I2S driver. | |
| 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) |
| Shared I2S channel allocation, initialization, and event queue setup. | |
| void | stop_i2s_driver_ () |
| Stops the I2S driver and unlocks the I2S port. | |
| virtual void | on_task_stopped () |
| Called in loop() when the task has stopped. Override for mode-specific cleanup. | |
| void | apply_software_volume_ (uint8_t *data, size_t bytes_read) |
| Apply software volume control using Q15 fixed-point scaling. | |
| void | swap_esp32_mono_samples_ (uint8_t *data, size_t bytes_read) |
| Swap adjacent 16-bit mono samples for ESP32 (non-variant) hardware quirk. | |
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. | |
| ESPDEPRECATED ("Use mark_failed(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void mark_failed(const char *message) | |
| 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 () |
| ESPDEPRECATED ("Use status_set_error(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void status_set_error(const char *message) | |
| void | status_set_error (const LogString *message) |
| void | status_clear_warning () |
| void | status_clear_error () |
| void | status_momentary_warning (const char *name, uint32_t length=5000) |
| Set warning status flag and automatically clear it after a timeout. | |
| void | status_momentary_error (const char *name, uint32_t length=5000) |
| Set error status flag and automatically clear it after a timeout. | |
| 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) |
Static Public Member Functions | |
| static bool | i2s_on_sent_cb (i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx) |
| Callback function used to send playback timestamps to the speaker task. | |
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_ |
| bool | pause_state_ {false} |
| int32_t | q31_volume_factor_ {INT32_MAX} |
| audio::AudioStreamInfo | current_stream_info_ |
| gpio_num_t | dout_pin_ |
| i2s_chan_handle_t | tx_handle_ {nullptr} |
Additional Inherited Members | |
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. | |
| 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 (uint32_t id) |
| bool | cancel_interval (InternalSchedulerID id) |
| ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std | ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const char *name |
| ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(uint32_t id | |
| ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(uint32_t initial_wait_time | |
| ESPDEPRECATED("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(const std | ESPDEPRECATED ("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(const char *name) |
| ESPDEPRECATED ("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(uint32_t id) | |
| 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 (uint32_t id) |
| bool | cancel_timeout (InternalSchedulerID id) |
| 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 (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} |
| audio::AudioStreamInfo | audio_stream_info_ |
| float | volume_ {1.0f} |
| bool | mute_state_ {false} |
| audio_dac::AudioDac * | audio_dac_ {nullptr} |
| CallbackManager< void(uint32_t, int64_t)> | audio_output_callback_ {} |
Protected Attributes inherited from esphome::Component | |
| ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") void set_interval(const std voi | set_interval )(const char *name, uint32_t interval, std::function< void()> &&f) |
| Set an interval function with a unique name. | |
| ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_interval(const std boo | cancel_interval )(const char *name) |
| Cancel an interval function. | |
| ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t | initial_wait_time |
| ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t | max_attempts |
| ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t std::function< RetryResult(uint8_t)> && | f |
| ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t std::function< RetryResult(uint8_t)> float | backoff_increase_factor = 1.0f) |
| uint32_t | initial_wait_time |
| uint32_t uint8_t | max_attempts |
| uint32_t uint8_t std::function< RetryResult(uint8_t)> && | f |
| uint32_t uint8_t std::function< RetryResult(uint8_t)> float | backoff_increase_factor = 1.0f) |
| uint8_t | max_attempts |
| uint8_t std::function< RetryResult(uint8_t)> && | f |
| uint8_t std::function< RetryResult(uint8_t)> float | backoff_increase_factor = 1.0f) |
| ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") void set_timeout(const std voi | set_timeout )(const char *name, uint32_t timeout, std::function< void()> &&f) |
| Set a timeout function with a unique name. | |
| ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_timeout(const std boo | cancel_timeout )(const char *name) |
| Cancel a timeout function. | |
| ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0") void defer(const std voi | defer )(const char *name, std::function< void()> &&f) |
| Defer a callback to the next loop() call. | |
| ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_defer(const std boo | cancel_defer )(const char *name) |
| Cancel a defer callback using the specified name, name must not be empty. | |
| 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_ |
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 48 of file i2s_audio_speaker.h.
| void esphome::i2s_audio::I2SAudioSpeakerBase::apply_software_volume_ | ( | uint8_t * | data, |
| size_t | bytes_read ) |
Apply software volume control using Q15 fixed-point scaling.
| data | Pointer to audio sample data (modified in place) |
| bytes_read | Number of bytes of audio data |
Definition at line 333 of file i2s_audio_speaker.cpp.
|
overridevirtual |
Reimplemented from esphome::Component.
Reimplemented in esphome::i2s_audio::I2SAudioSpeakerSPDIF.
Definition at line 41 of file i2s_audio_speaker.cpp.
|
overridevirtual |
Reimplemented from esphome::speaker::Speaker.
Definition at line 238 of file i2s_audio_speaker.cpp.
|
inlineoverridevirtual |
Reimplemented from esphome::speaker::Speaker.
Definition at line 68 of file i2s_audio_speaker.h.
|
inlineoverridevirtual |
Reimplemented from esphome::Component.
Definition at line 50 of file i2s_audio_speaker.h.
|
inline |
Get the I2S TX channel handle.
Definition at line 61 of file i2s_audio_speaker.h.
|
static |
Callback function used to send playback timestamps to the speaker task.
| handle | (i2s_chan_handle_t) |
| event | (i2s_event_data_t) |
| user_ctx | (void*) User context pointer that the callback accesses |
Definition at line 306 of file i2s_audio_speaker.cpp.
| esp_err_t esphome::i2s_audio::I2SAudioSpeakerBase::init_i2s_channel_ | ( | const i2s_chan_config_t & | chan_cfg, |
| const i2s_std_config_t & | std_cfg, | ||
| size_t | event_queue_size ) |
Shared I2S channel allocation, initialization, and event queue setup.
Called by derived start_i2s_driver_() implementations after building mode-specific configs.
| chan_cfg | I2S channel configuration |
| std_cfg | I2S standard mode configuration (clock, slot, GPIO) |
| event_queue_size | Size of the event queue |
Definition at line 253 of file i2s_audio_speaker.cpp.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 52 of file i2s_audio_speaker.cpp.
|
inlinevirtual |
Called in loop() when the task has stopped. Override for mode-specific cleanup.
Reimplemented in esphome::i2s_audio::I2SAudioSpeakerSPDIF.
Definition at line 130 of file i2s_audio_speaker.h.
|
inline |
Definition at line 56 of file i2s_audio_speaker.h.
|
inline |
Definition at line 58 of file i2s_audio_speaker.h.
|
inlineoverridevirtual |
Reimplemented from esphome::speaker::Speaker.
Definition at line 67 of file i2s_audio_speaker.h.
|
inline |
Definition at line 57 of file i2s_audio_speaker.h.
|
overridevirtual |
Reimplemented from esphome::Component.
Reimplemented in esphome::i2s_audio::I2SAudioSpeakerSPDIF.
Definition at line 27 of file i2s_audio_speaker.cpp.
|
overridevirtual |
Implements esphome::speaker::Speaker.
Definition at line 225 of file i2s_audio_speaker.cpp.
|
pure virtual |
Starts the ESP32 I2S driver.
Implemented by derived classes for mode-specific configuration.
| audio_stream_info | Stream information for the I2S driver. |
Implemented in esphome::i2s_audio::I2SAudioSpeaker, and esphome::i2s_audio::I2SAudioSpeakerSPDIF.
|
overridevirtual |
Implements esphome::speaker::Speaker.
Definition at line 236 of file i2s_audio_speaker.cpp.
| void esphome::i2s_audio::I2SAudioSpeakerBase::stop_ | ( | bool | wait_on_empty | ) |
Plays the provided audio data.
Starts the speaker task, if necessary. Writes the audio data to the ring buffer.
| 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. / |
bool has_buffered_data() const override;
/ Sets the volume of the speaker. Uses the speaker's configured audio dac component. If unavailble, it is / implemented as a software volume control. Overrides the default setter to convert the floating point volume to a / Q15 fixed-point factor. /
| volume | between 0.0 and 1.0 void set_volume(float volume) override; |
/ Mutes or unmute the speaker. Uses the speaker's configured audio dac component. If unavailble, it is / implemented as a software volume control. Overrides the default setter to convert the floating point volume to a / Q15 fixed-point factor. /
| mute_state | true for muting, false for unmuting void set_mute_state(bool mute_state) override; |
protected: / FreeRTOS task entry point. Casts params to I2SAudioSpeakerBase and calls run_speaker_task_(). /
| 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_.
| wait_on_empty | If false, sends the COMMAND_STOP signal. If true, sends the COMMAND_STOP_GRACEFULLY signal. |
Definition at line 240 of file i2s_audio_speaker.cpp.
| void esphome::i2s_audio::I2SAudioSpeakerBase::stop_i2s_driver_ | ( | ) |
Stops the I2S driver and unlocks the I2S port.
Definition at line 297 of file i2s_audio_speaker.cpp.
| void esphome::i2s_audio::I2SAudioSpeakerBase::swap_esp32_mono_samples_ | ( | uint8_t * | data, |
| size_t | bytes_read ) |
Swap adjacent 16-bit mono samples for ESP32 (non-variant) hardware quirk.
Only applies when running on original ESP32 with 16-bit mono audio.
| data | Pointer to audio sample data (modified in place) |
| bytes_read | Number of bytes of audio data |
Definition at line 344 of file i2s_audio_speaker.cpp.
| std::weak_ptr<ring_buffer::RingBuffer> esphome::i2s_audio::I2SAudioSpeakerBase::audio_ring_buffer_ |
Definition at line 150 of file i2s_audio_speaker.h.
| uint32_t esphome::i2s_audio::I2SAudioSpeakerBase::buffer_duration_ms_ |
Definition at line 152 of file i2s_audio_speaker.h.
| audio::AudioStreamInfo esphome::i2s_audio::I2SAudioSpeakerBase::current_stream_info_ |
Definition at line 160 of file i2s_audio_speaker.h.
| gpio_num_t esphome::i2s_audio::I2SAudioSpeakerBase::dout_pin_ |
Definition at line 162 of file i2s_audio_speaker.h.
| EventGroupHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::event_group_ {nullptr} |
Definition at line 144 of file i2s_audio_speaker.h.
| QueueHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::i2s_event_queue_ {nullptr} |
Definition at line 147 of file i2s_audio_speaker.h.
| bool esphome::i2s_audio::I2SAudioSpeakerBase::pause_state_ {false} |
Definition at line 156 of file i2s_audio_speaker.h.
| int32_t esphome::i2s_audio::I2SAudioSpeakerBase::q31_volume_factor_ {INT32_MAX} |
Definition at line 158 of file i2s_audio_speaker.h.
| TaskHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::speaker_task_handle_ {nullptr} |
Definition at line 143 of file i2s_audio_speaker.h.
| optional<uint32_t> esphome::i2s_audio::I2SAudioSpeakerBase::timeout_ |
Definition at line 154 of file i2s_audio_speaker.h.
| i2s_chan_handle_t esphome::i2s_audio::I2SAudioSpeakerBase::tx_handle_ {nullptr} |
Definition at line 163 of file i2s_audio_speaker.h.
| QueueHandle_t esphome::i2s_audio::I2SAudioSpeakerBase::write_records_queue_ {nullptr} |
Definition at line 148 of file i2s_audio_speaker.h.