ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
i2s_audio_speaker.cpp
Go to the documentation of this file.
1#include "i2s_audio_speaker.h"
2
3#ifdef USE_ESP32
4
5#include <driver/gpio.h>
6#include <driver/i2s_std.h>
7
10
12#include "esphome/core/hal.h"
13#include "esphome/core/log.h"
14
15#include "esp_timer.h"
16
17#include <cmath>
18
19namespace esphome::i2s_audio {
20
21ESPHOME_LOG_TAG(TAG, "i2s_audio.speaker");
22
23// Software volume control maps the user-facing (0.0, 1.0) range linearly to a dB reduction in
24// [-49.0, 0.0] dB; 0.0 is silence.
25static constexpr float SOFTWARE_VOLUME_MIN_DB = -49.0f;
26
27// Rate at which the software gain moves toward a new target.
28static constexpr uint32_t GAIN_RAMP_MS_PER_DB = 1;
29
31 this->event_group_ = xEventGroupCreate();
32
33 if (this->event_group_ == nullptr) {
34 ESP_LOGE(TAG, "Event group creation failed");
35 this->mark_failed();
36 return;
37 }
38
39 // Initialize volume control. When audio_dac is configured, this sets every DAC's volume and mute state.
40 // When no audio_dac is configured, this initializes software volume control.
41 this->set_volume(this->volume_);
42 this->set_mute_state(this->mute_state_);
43
44#ifdef USE_I2S_AUDIO_FULL_DUPLEX
45 // The parent set up before us and already routed dout to the shared TX channel, which is never re-initialized.
46 // Parking would detach the pin for good. SPDIF speakers cannot use a full duplex bus.
47 if (this->parent_->is_full_duplex()) {
48 if (this->parent_->is_failed()) {
49 this->mark_failed(LOG_STR("Full duplex bus setup failed"));
50 }
51 return;
52 }
53#endif
54
55 // Until the I2S driver first starts, dout sits in its reset state (often pulled high, or a JTAG
56 // function on the ESP32-S3), which keeps a SPDIF optical transmitter lit. Park it low now.
57 this->park_dout_pin_();
58}
59
60void I2SAudioSpeakerBase::park_dout_pin_() {
61 gpio_reset_pin(this->dout_pin_);
62 gpio_set_direction(this->dout_pin_, GPIO_MODE_OUTPUT);
63 gpio_set_level(this->dout_pin_, 0);
64}
65
67 ESP_LOGCONFIG(TAG,
68 "Speaker:\n"
69 " Pin: %d\n"
70 " Buffer duration: %" PRIu32 "\n"
71 " Keep alive: %s",
72 static_cast<int8_t>(this->dout_pin_), this->buffer_duration_ms_, YESNO(this->keep_alive_));
73 if (this->timeout_.has_value()) {
74 ESP_LOGCONFIG(TAG, " Timeout: %" PRIu32 " ms", this->timeout_.value());
75 }
76}
77
79 uint32_t event_group_bits = xEventGroupGetBits(this->event_group_);
80
81 // A stop that arrives while stopped cancels any start that has not been processed yet
83 if ((event_group_bits & stop_bits) && (this->state_ == speaker::STATE_STOPPED)) {
84 xEventGroupClearBits(this->event_group_, stop_bits | SpeakerEventGroupBits::COMMAND_START);
85 event_group_bits &= ~(stop_bits | SpeakerEventGroupBits::COMMAND_START);
86 }
87
88 if ((event_group_bits & SpeakerEventGroupBits::COMMAND_START) && (this->state_ == speaker::STATE_STOPPED)) {
90 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::COMMAND_START);
91 }
92
93 // Handle the task's state
94 if (event_group_bits & SpeakerEventGroupBits::TASK_STARTING) {
95 ESP_LOGD(TAG, "Starting");
96 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::TASK_STARTING);
97 }
98 if (event_group_bits & SpeakerEventGroupBits::TASK_RUNNING) {
99 ESP_LOGV(TAG, "Started");
100 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::TASK_RUNNING);
102#ifdef USE_AUDIO_DAC
103 // The task raises TASK_RUNNING only after enabling the channel, so the clocks are already running
105#endif // USE_AUDIO_DAC
106 }
107 if (event_group_bits & SpeakerEventGroupBits::TASK_STOPPING) {
108 ESP_LOGV(TAG, "Stopping");
109 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::TASK_STOPPING);
111 }
112 if (event_group_bits & SpeakerEventGroupBits::TASK_STOPPED) {
113 ESP_LOGD(TAG, "Stopped");
114
115 vTaskDelete(this->speaker_task_handle_);
116 this->speaker_task_handle_ = nullptr;
117
118 // The task raises this bit before it exits, possibly a loop pass before TASK_STOPPED is seen, so read it
119 // live here; a channel the task could not bring up is rebuilt next time rather than kept
120 const bool task_failed = xEventGroupGetBits(this->event_group_) & SpeakerEventGroupBits::ERR_ESP_NO_MEM;
121 if (task_failed) {
122 ESP_LOGE(TAG, "Speaker task setup failed (allocation, preload, or channel enable)");
123 }
124 this->stop_i2s_driver_(this->keep_alive_ && !task_failed);
125 // ALL_BITS includes COMMAND_START. Take the bits from the clear itself, not from the snapshot at
126 // the top of loop(): the audio source's task can raise a start at any point above, including
127 // during stop_i2s_driver_(), and nothing would ever re-issue it.
128 const EventBits_t bits_before_clear = xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::ALL_BITS);
129 if (bits_before_clear & SpeakerEventGroupBits::COMMAND_START) {
130 ESP_LOGD(TAG, "Start requested while stopping; keeping the request");
131 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_START);
132 }
133 this->status_clear_error();
134
135 this->on_task_stopped();
136
138 }
139
140 // Handle the speaker's state
141 switch (this->state_) {
143 if (this->status_has_error()) {
144 break;
145 }
146
147 // Still winding down from a previous run
148 if (this->speaker_task_handle_ != nullptr) {
149 break;
150 }
151
152#ifdef USE_I2S_AUDIO_FULL_DUPLEX
153 if (this->parent_->is_tx_in_use()) {
154 // Another speaker on the bus is playing; wait for it to release the channel
155 break;
156 }
157#endif
158 const esp_err_t err = this->start_i2s_driver(this->audio_stream_info_);
159 if (err == ESP_ERR_NOT_SUPPORTED) {
160 // Retrying cannot help; stay stopped so the audio source gives up instead of waiting forever
161 ESP_LOGE(TAG, "Stream format not supported; not starting");
164 break;
165 }
166 if (err != ESP_OK) {
167 ESP_LOGE(TAG, "Driver failed to start; retrying in 1 second");
168 this->status_momentary_error(1000);
169 break;
170 }
171
172 // Seed the ramp at the live target so this run adopts it instantly rather than fading to it
173 // from wherever the previous run left off. Posted here, not in the task: the ramp's mailbox
174 // allows one writer, and that is the main loop.
175 this->post_software_gain_(0);
176 xTaskCreate(I2SAudioSpeakerBase::speaker_task, "speaker_task", TASK_STACK_SIZE, (void *) this, TASK_PRIORITY,
177 &this->speaker_task_handle_);
178
179 if (this->speaker_task_handle_ == nullptr) {
180 ESP_LOGE(TAG, "Task failed to start, retrying in 1 second");
181 this->status_momentary_error(1000);
182 this->stop_i2s_driver_(false); // Stops the driver to return the lock; will be reloaded in next attempt
183 }
184 break;
185 }
186 case speaker::STATE_RUNNING: // Intentional fallthrough
187 case speaker::STATE_STOPPING: // Intentional fallthrough
189 break;
190 }
191}
192
193void I2SAudioSpeakerBase::set_volume(float volume) {
195 this->post_software_gain_(this->audio_stream_info_.ms_to_samples(GAIN_RAMP_MS_PER_DB));
196}
197
198void I2SAudioSpeakerBase::set_mute_state(bool mute_state) {
200 this->post_software_gain_(this->audio_stream_info_.ms_to_samples(GAIN_RAMP_MS_PER_DB));
201}
202
203void I2SAudioSpeakerBase::post_software_gain_(uint32_t rate_samples) {
204#ifdef USE_AUDIO_DAC
205 if (this->has_audio_dac_()) {
206 return; // Hardware volume; the ramp stays at unity
207 }
208#endif // USE_AUDIO_DAC
209 // Software volume control. The ramp treats 0 dB as unity and skips processing there.
210 float target_db;
211 if (this->is_silent_()) {
212 target_db = -INFINITY;
213 } else if (this->volume_ >= 1.0f) {
214 target_db = 0.0f;
215 } else {
216 target_db = remap<float, float>(this->volume_, 0.0f, 1.0f, SOFTWARE_VOLUME_MIN_DB, 0.0f);
217 }
218 this->gain_ramp_.set_target_db_at_rate(target_db, rate_samples);
219}
220
221size_t I2SAudioSpeakerBase::play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) {
222 if (this->is_failed()) {
223 ESP_LOGE(TAG, "Setup failed; cannot play audio");
224 return 0;
225 }
226
228 this->start();
229 }
230
231 if (this->state_ != speaker::STATE_RUNNING) {
232 // Unable to write data to a running speaker, so delay the max amount of time so it can get ready
233 vTaskDelay(ticks_to_wait);
234 ticks_to_wait = 0;
235 }
236
237 size_t bytes_written = 0;
238 if (this->state_ == speaker::STATE_RUNNING) {
239 std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->audio_ring_buffer_.lock();
240 if (temp_ring_buffer != nullptr) {
241 // The weak_ptr locks successfully only while the speaker task owns the ring buffer, so it is safe to write
242 bytes_written = temp_ring_buffer->write_without_replacement((void *) data, length, ticks_to_wait);
243 }
244 }
245
246 return bytes_written;
247}
248
250 std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->audio_ring_buffer_.lock();
251 if (temp_ring_buffer != nullptr) {
252 return temp_ring_buffer->available() > 0;
253 }
254 return false;
255}
256
257void I2SAudioSpeakerBase::speaker_task(void *params) {
258 I2SAudioSpeakerBase *this_speaker = (I2SAudioSpeakerBase *) params;
259 this_speaker->run_speaker_task();
260}
261
263 if (!this->is_ready() || this->is_failed() || this->status_has_error())
264 return;
265 if ((this->state_ == speaker::STATE_STARTING) || (this->state_ == speaker::STATE_RUNNING))
266 return;
267 // play() calls start() on every write, so without this a rejected stream would be retried and logged nonstop
268 if (this->rejected_stream_info_.has_value() && this->rejected_stream_info_.value() == this->audio_stream_info_)
269 return;
270
271 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_START);
272}
273
274void I2SAudioSpeakerBase::stop() { this->stop_(false); }
275
276void I2SAudioSpeakerBase::finish() { this->stop_(true); }
277
278void I2SAudioSpeakerBase::stop_(bool wait_on_empty) {
279 if (!this->is_ready() || this->is_failed())
280 return;
281
282 // Always set the bit, even when stopped, so loop() can cancel a start that is still pending
283 if (wait_on_empty) {
285 } else {
286 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_STOP);
287 }
288}
289
290esp_err_t I2SAudioSpeakerBase::init_i2s_channel_(const i2s_chan_config_t &chan_cfg, const i2s_std_config_t &std_cfg,
291 size_t event_queue_size) {
292 esp_err_t err = i2s_new_channel(&chan_cfg, &this->tx_handle_, NULL);
293 if (err != ESP_OK) {
294 ESP_LOGE(TAG, "I2S channel allocation failed: %s", esp_err_to_name(err));
295 this->parent_->unlock();
296 return err;
297 }
298
299 err = i2s_channel_init_std_mode(this->tx_handle_, &std_cfg);
300 if (err != ESP_OK) {
301 ESP_LOGE(TAG, "Failed to initialize I2S channel");
302 this->delete_channel_();
303 this->parent_->unlock();
304 return err;
305 }
306
307 err = this->prepare_event_queues_(event_queue_size);
308 if (err != ESP_OK) {
309 this->delete_channel_();
310 this->parent_->unlock();
311 }
312 return err;
313}
314
315esp_err_t I2SAudioSpeakerBase::prepare_event_queues_(size_t event_queue_size) {
316 // Both queues are drained by the speaker task before it preloads, whether the channel is new or kept
317 if (this->i2s_event_queue_ == nullptr) {
318 this->i2s_event_queue_ = xQueueCreate(event_queue_size, sizeof(int64_t));
319 }
320
321 // Lockstep records queue. One record per in-flight DMA buffer; sized to match the I2S event queue
322 // so a fully-saturated DMA pipeline cannot overflow either side before drain.
323 if (this->write_records_queue_ == nullptr) {
324 this->write_records_queue_ = xQueueCreate(event_queue_size, sizeof(uint32_t));
325 }
326
327 if (this->i2s_event_queue_ == nullptr || this->write_records_queue_ == nullptr) {
328 ESP_LOGE(TAG, "Failed to allocate I2S event queue(s)");
329 return ESP_ERR_NO_MEM;
330 }
331
332 return ESP_OK;
333}
334
335#ifdef USE_I2S_AUDIO_FULL_DUPLEX
336esp_err_t I2SAudioSpeakerBase::acquire_full_duplex_channel_(size_t event_queue_size) {
337 this->tx_handle_ = this->parent_->acquire_tx_channel();
338 if (this->tx_handle_ == nullptr) {
339 ESP_LOGE(TAG, "Full duplex channel unavailable");
340 return ESP_ERR_INVALID_STATE;
341 }
342
343 esp_err_t err = this->prepare_event_queues_(event_queue_size);
344 if (err != ESP_OK) {
345 this->parent_->release_tx_channel();
346 this->tx_handle_ = nullptr;
347 }
348 return err;
349}
350#endif
351
352void I2SAudioSpeakerBase::stop_i2s_driver_(bool keep_channel) {
353#ifdef USE_I2S_AUDIO_FULL_DUPLEX
354 if (this->parent_->is_full_duplex()) {
355 // The parent owns the channel pair and its pins, so only hand the TX channel back
356 if (this->tx_handle_ != nullptr) {
357 this->parent_->release_tx_channel();
358 this->tx_handle_ = nullptr;
359 }
360 return;
361 }
362#endif
363
364 if (this->tx_handle_ != nullptr) {
365 i2s_channel_disable(this->tx_handle_);
366 // A kept channel lets the next start skip i2s_new_channel and i2s_channel_init_std_mode, whose GPIO and
367 // clock reconfiguration is the audible pop
368 if (!keep_channel) {
369 this->delete_channel_();
370 }
371 }
372 this->parent_->unlock();
373}
374
375void I2SAudioSpeakerBase::delete_channel_() {
376 i2s_del_channel(this->tx_handle_);
377 this->tx_handle_ = nullptr;
378
379 // i2s_del_channel() leaves dout wired to this port's data-out signal in the GPIO matrix: it only
380 // clears an internal reservation mask, never the esp_rom_gpio_connect_out_signal() routing that
381 // setup installed. If another speaker reuses this port (shared bus), its audio still reaches our
382 // dout. Detach the pin and drive it low so a stale output stops driving downstream hardware: a
383 // SPDIF optical transmitter would otherwise stay lit, and an analog DAC would emit noise.
384 this->park_dout_pin_();
385}
386
387bool IRAM_ATTR I2SAudioSpeakerBase::i2s_on_sent_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx) {
388 int64_t now = esp_timer_get_time();
389
390 BaseType_t need_yield1 = pdFALSE;
391 BaseType_t need_yield2 = pdFALSE;
392 BaseType_t need_yield3 = pdFALSE;
393
394 I2SAudioSpeakerBase *this_speaker = (I2SAudioSpeakerBase *) user_ctx;
395
396 if (xQueueIsQueueFullFromISR(this_speaker->i2s_event_queue_)) {
397 // Queue is full, so discard the oldest event. The lockstep queues are now desynced; the task resyncs them.
398 int64_t dummy;
399 xQueueReceiveFromISR(this_speaker->i2s_event_queue_, &dummy, &need_yield1);
400 xEventGroupSetBitsFromISR(this_speaker->event_group_, SpeakerEventGroupBits::ERR_DROPPED_EVENT, &need_yield2);
401 }
402
403 xQueueSendToBackFromISR(this_speaker->i2s_event_queue_, &now, &need_yield3);
404
405 return need_yield1 | need_yield2 | need_yield3;
406}
407
408void I2SAudioSpeakerBase::drain_lockstep_(uint32_t extra_frames) {
409 // Stop DMA so no more completion events arrive while the queues are rebuilt
410 i2s_channel_disable(this->tx_handle_);
411 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::ERR_DROPPED_EVENT);
412
413 uint32_t frames = extra_frames;
414 uint32_t record_frames = 0;
415 while (xQueueReceive(this->write_records_queue_, &record_frames, 0) == pdTRUE) {
416 frames += record_frames;
417 }
418 xQueueReset(this->i2s_event_queue_);
419
420 if (frames > 0) {
421 ESP_LOGV(TAG, "Crediting %" PRIu32 " dropped frames as played", frames);
423 }
424}
425
426void I2SAudioSpeakerBase::apply_software_volume_(uint8_t *data, size_t bytes_read) {
427#ifdef USE_AUDIO_DAC
428 if (this->has_audio_dac_()) {
429 return; // Hardware volume; the ramp is never targeted
430 }
431#endif // USE_AUDIO_DAC
432 const size_t bytes_per_sample = this->current_stream_info_.samples_to_bytes(1);
433 this->gain_ramp_.process(data, static_cast<uint8_t>(bytes_per_sample),
434 this->current_stream_info_.bytes_to_samples(bytes_read));
435}
436
437bool I2SAudioSpeakerBase::esp32_mono_swap_needed(const audio::AudioStreamInfo &stream_info) {
438#ifdef USE_ESP32_VARIANT_ESP32
439 return stream_info.get_channels() == 1 && stream_info.get_bits_per_sample() == 16;
440#else
441 return false;
442#endif // USE_ESP32_VARIANT_ESP32
443}
444
445void I2SAudioSpeakerBase::swap_esp32_mono_samples_(uint8_t *data, size_t bytes_read) {
446#ifdef USE_ESP32_VARIANT_ESP32
447 // For ESP32 16-bit mono mode, adjacent samples need to be swapped.
448 if (this->esp32_mono_swap_needed_()) {
449 int16_t *samples = reinterpret_cast<int16_t *>(data);
450 size_t sample_count = bytes_read / sizeof(int16_t);
451 for (size_t i = 0; i + 1 < sample_count; i += 2) {
452 int16_t tmp = samples[i];
453 samples[i] = samples[i + 1];
454 samples[i + 1] = tmp;
455 }
456 }
457#endif // USE_ESP32_VARIANT_ESP32
458}
459
460} // namespace esphome::i2s_audio
461
462#endif // USE_ESP32
void mark_failed()
Mark this component as failed.
bool is_failed() const
Definition component.h:287
void status_clear_error()
Definition component.h:315
bool is_ready() const
bool status_has_error() const
Definition component.h:295
void status_momentary_error(uint32_t length=5000)
Set error status flag and clear it after length ms.
uint32_t ms_to_samples(uint32_t ms) const
Converts duration to samples.
Definition audio.h:68
size_t samples_to_bytes(uint32_t samples) const
Converts samples to bytes.
Definition audio.h:58
uint32_t bytes_to_samples(size_t bytes) const
Convert bytes to samples.
Definition audio.h:48
esp_audio_libs::gain::GainRamp gain_ramp_
std::weak_ptr< ring_buffer::RingBuffer > audio_ring_buffer_
optional< audio::AudioStreamInfo > rejected_stream_info_
void swap_esp32_mono_samples_(uint8_t *data, size_t bytes_read)
Plays the provided audio data.
virtual size_t play(const uint8_t *data, size_t length)=0
Plays the provided audio data.
virtual void set_volume(float volume)
Definition speaker.h:74
void notify_audio_dacs_started_()
Tells every audio dac that its audio clocks are running; call from the main loop.
Definition speaker.h:140
CallbackManager< void(uint32_t, int64_t)> audio_output_callback_
Definition speaker.h:157
virtual void set_mute_state(bool mute_state)
Definition speaker.h:85
virtual bool has_buffered_data() const =0
audio::AudioStreamInfo audio_stream_info_
Definition speaker.h:149
bool has_audio_dac_() const
Whether volume and mute are handled in hardware by at least one audio dac.
Definition speaker.h:125
bool is_silent_() const
Whether the output should be silent: muted, or the volume is effectively zero.
Definition speaker.h:121
const char * esp_err_to_name(esp_err_t err)
ESPHOME_LOG_TAG(TAG, "i2s_audio")
T remap(U value, U min, U max, T min_out, T max_out)
Remap value from the range (min, max) to (min_out, max_out).
Definition helpers.h:932
int64_t esp_timer_get_time(void)
static void uint32_t
uint16_t length
Definition tt21100.cpp:0
spi_device_handle_t handle