ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
i2s_audio_speaker_standard.cpp
Go to the documentation of this file.
2
3#ifdef USE_ESP32
4
5#include <driver/i2s_std.h>
6#include <hal/dma_types.h>
7
10
11#include "esphome/core/hal.h"
12#include "esphome/core/log.h"
13
14#include "esp_timer.h"
15
16// esp-audio-libs
17#include <pcm_convert.h>
18
19namespace esphome::i2s_audio {
20
21ESPHOME_LOG_TAG(TAG, "i2s_audio.speaker.std");
22
23static constexpr uint32_t DMA_BUFFER_DURATION_MS = 10;
24static constexpr size_t DMA_BUFFERS_COUNT = 5;
25// ESP-IDF clamps each DMA descriptor to this many bytes when allocating the channel (see i2s_get_buf_size in
26// the I2S driver). Mirror its target-dependent selection so the requested dma_frame_num stays in range; the
27// speaker task reads the size actually allocated back from the driver rather than relying on this value.
28#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
29static constexpr size_t I2S_DMA_BUFFER_MAX_SIZE = DMA_DESCRIPTOR_BUFFER_MAX_SIZE_64B_ALIGNED;
30#else
31static constexpr size_t I2S_DMA_BUFFER_MAX_SIZE = DMA_DESCRIPTOR_BUFFER_MAX_SIZE_4B_ALIGNED;
32#endif
33// Sized to comfortably absorb scheduling jitter: at most DMA_BUFFERS_COUNT events can be in flight,
34// doubled so that a transient backlog never overruns the queue (which would desync the lockstep
35// invariant between i2s_event_queue_ and write_records_queue_).
36static constexpr size_t I2S_EVENT_QUEUE_COUNT = DMA_BUFFERS_COUNT * 2;
37// Generous timeout for ``i2s_channel_write`` blocking. A buffer frees roughly every
38// DMA_BUFFER_DURATION_MS, so a multiple of that gives plenty of slack against scheduling jitter
39// without masking real failures.
40static constexpr TickType_t WRITE_TIMEOUT_TICKS = pdMS_TO_TICKS(DMA_BUFFER_DURATION_MS * (DMA_BUFFERS_COUNT + 1));
41#ifdef USE_ESP32_VARIANT_ESP32
42// Stack buffer that widened audio passes through on the original ESP32. Small enough for the speaker task's stack,
43// large enough that the extra i2s_channel_write calls cost little.
44static constexpr size_t WIDEN_BUFFER_BYTES = 512;
45#endif
46
47// Requested frames per DMA buffer for the given stream, clamped so the byte size stays within the ESP-IDF
48// maximum DMA descriptor size. This is only the value handed to the channel config: ESP-IDF may still adjust
49// it (e.g. cache-line rounding on some targets), so the speaker task reads the size actually allocated back
50// from the driver instead of assuming this value. Clamping here keeps the request in range and avoids a
51// noisy ESP-IDF "dma frame num is out of dma buffer size" warning at high sample rates or bit depths.
52static uint32_t dma_buffer_frames(const audio::AudioStreamInfo &stream_info, uint32_t frame_multiple) {
53 const uint32_t frames_from_duration = stream_info.ms_to_frames(DMA_BUFFER_DURATION_MS);
54 const uint32_t max_frames = I2S_DMA_BUFFER_MAX_SIZE / stream_info.frames_to_bytes(1);
55 return (std::min(frames_from_duration, max_frames) / frame_multiple) * frame_multiple;
56}
57
60 const char *fmt_str;
61 switch (this->i2s_comm_fmt_) {
62 case I2SCommFmt::PCM:
63 fmt_str = "pcm";
64 break;
65 case I2SCommFmt::MSB:
66 fmt_str = "msb";
67 break;
68 default:
69 fmt_str = "std";
70 break;
71 }
72 ESP_LOGCONFIG(TAG, " Communication format: %s", fmt_str);
73 if (this->slot_bit_width_ != I2S_SLOT_BIT_WIDTH_AUTO) {
74 // The width of each I2S slot. Wider streams are narrowed to it. Narrower streams are padded into the slot by
75 // the peripheral, except on the original ESP32, where they are widened to it.
76 ESP_LOGCONFIG(TAG, " Slot bit width: %u", (unsigned) static_cast<uint32_t>(this->slot_bit_width_));
77 }
78}
79
81 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::TASK_STARTING);
82 // Stale records from the previous run would pair with the wrong DMA events
83 xQueueReset(this->i2s_event_queue_);
84 xQueueReset(this->write_records_queue_);
85
86 const uint32_t dma_buffers_duration_ms = DMA_BUFFER_DURATION_MS * DMA_BUFFERS_COUNT;
87 // Ensure ring buffer duration is at least the duration of all DMA buffers
88 const uint32_t ring_buffer_duration = std::max(dma_buffers_duration_ms, this->buffer_duration_ms_);
89
90 // The ring buffer holds input-format audio (what play() receives), so size it from the input stream info.
91 const size_t bytes_per_frame = this->current_stream_info_.frames_to_bytes(1);
92 // Hand over whole ESP32 mono sample pairs so writes stay word-aligned
93 const size_t source_alignment = bytes_per_frame * dma_frame_multiple(this->output_stream_info_);
94 const bool pair_aligned = source_alignment > bytes_per_frame;
95 // Round the ring buffer size down to a multiple of source_alignment so the wrap boundary avoids splices.
96 const size_t ring_buffer_size =
97 (this->current_stream_info_.ms_to_bytes(ring_buffer_duration) / source_alignment) * source_alignment;
98
99 // Per-frame byte widths and whether the task must convert the bit depth before writing to the I2S peripheral.
100 const uint8_t channels = this->current_stream_info_.get_channels();
101 const uint8_t input_bytes_per_sample = this->current_stream_info_.get_bits_per_sample() / 8;
102 const uint8_t output_bytes_per_sample = this->output_stream_info_.get_bits_per_sample() / 8;
103 const bool narrowing = input_bytes_per_sample > output_bytes_per_sample;
104#ifdef USE_ESP32_VARIANT_ESP32
105 const bool widening = input_bytes_per_sample < output_bytes_per_sample;
106#endif
107
108 // ESP-IDF may allocate smaller (or cache-line-rounded) DMA buffers than dma_buffer_frames() requested: it
109 // clamps each descriptor to the max DMA descriptor size and, on targets that route internal memory through
110 // the L1 cache (e.g. ESP32-P4), rounds the buffer to the cache line. Read the size the driver actually
111 // allocated so preload, silence padding, and the write/event lockstep all match it exactly. The channel is
112 // in the READY state here because start_i2s_driver() initialized it before this task was created.
113 size_t dma_buffer_bytes;
114 i2s_chan_info_t chan_info;
115 if (i2s_channel_get_info(this->tx_handle_, &chan_info) == ESP_OK && chan_info.total_dma_buf_size > 0) {
116 // total_dma_buf_size spans all DMA_BUFFERS_COUNT descriptors and is an exact multiple of the count.
117 dma_buffer_bytes = chan_info.total_dma_buf_size / DMA_BUFFERS_COUNT;
118 } else {
119 // Should not happen for a READY channel; fall back to the requested size.
120 dma_buffer_bytes = this->output_stream_info_.frames_to_bytes(
121 dma_buffer_frames(this->output_stream_info_, dma_frame_multiple(this->output_stream_info_)));
122 }
123 // dma_buffer_bytes counts output-format bytes; convert with the output stream info.
124 const uint32_t frames_per_dma_buffer = this->output_stream_info_.bytes_to_frames(dma_buffer_bytes);
125 // Soft cap for each source read: enough input-format bytes to fill one DMA buffer's worth of frames.
126 const size_t dma_buffer_input_bytes = this->current_stream_info_.frames_to_bytes(frames_per_dma_buffer);
127
128 bool successful_setup = false;
129
130 std::unique_ptr<audio::RingBufferAudioSource> audio_source;
131
132 // Pre-zeroed buffer used to silence-pad each DMA descriptor whenever real audio doesn't fully fill it.
133 RAMAllocator<uint8_t> silence_allocator;
134 uint8_t *silence_buffer = silence_allocator.allocate(dma_buffer_bytes);
135
136 if (silence_buffer != nullptr) {
137 memset(silence_buffer, 0, dma_buffer_bytes);
138
139 std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = ring_buffer::RingBuffer::create(ring_buffer_size);
140 audio_source = audio::RingBufferAudioSource::create(temp_ring_buffer, dma_buffer_input_bytes,
141 static_cast<uint8_t>(source_alignment));
142
143 if (audio_source != nullptr) {
144 // audio_source is nullptr if the ring buffer fails to allocate
145 this->audio_ring_buffer_ = temp_ring_buffer;
146 successful_setup = true;
147 }
148 }
149
150 // Preload every DMA descriptor with silence and push a matching zero-real-frames record per buffer, so every
151 // on_sent event has a write record from the start. Runs with the channel disabled: at startup and after a resync.
152 auto preload_silence = [&]() -> bool {
153 for (size_t i = 0; i < DMA_BUFFERS_COUNT; i++) {
154 size_t bytes_loaded = 0;
155 esp_err_t err = i2s_channel_preload_data(this->tx_handle_, silence_buffer, dma_buffer_bytes, &bytes_loaded);
156 if (err != ESP_OK || bytes_loaded != dma_buffer_bytes) {
157 ESP_LOGV(TAG, "Failed to preload silence into DMA buffer %u (err=%d, loaded=%u)", (unsigned) i, (int) err,
158 (unsigned) bytes_loaded);
159 return false;
160 }
161 uint32_t zero_real_frames = 0;
162 if (xQueueSend(this->write_records_queue_, &zero_real_frames, 0) != pdTRUE) {
163 // Should never happen: the queue was just reset and is sized for DMA_BUFFERS_COUNT * 2 entries.
164 ESP_LOGV(TAG, "Failed to push preload write record");
165 return false;
166 }
167 }
168 return true;
169 };
170
171 if (successful_setup) {
172 successful_setup = preload_silence();
173 }
174
175 if (successful_setup) {
176 // Register the on_sent callback BEFORE enabling the channel so the very first transmitted buffer
177 // generates a queued event that pairs with the first preloaded silence record.
178 const i2s_event_callbacks_t callbacks = {.on_sent = i2s_on_sent_cb};
179 i2s_channel_register_event_callback(this->tx_handle_, &callbacks, this);
180
181 if (i2s_channel_enable(this->tx_handle_) != ESP_OK) {
182 ESP_LOGV(TAG, "Failed to enable I2S channel");
183 successful_setup = false;
184 }
185 }
186
187 if (!successful_setup) {
188 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::ERR_ESP_NO_MEM);
189 } else {
190 bool stop_gracefully = false;
191 // Number of records currently in ``write_records_queue_`` that carry real audio. Used by graceful
192 // stop to wait until every real-audio buffer has been confirmed played by an ISR event.
193 uint32_t pending_real_buffers = 0;
194 uint32_t last_data_received_time = millis();
195 bool resync_needed = false;
196 // Real frames consumed from the ring buffer that never reached a write record
197 uint32_t unrecorded_frames = 0;
198
199 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::TASK_RUNNING);
200
201 // Main speaker task loop. Continues while:
202 // - Paused, OR
203 // - No timeout configured, OR
204 // - Timeout hasn't elapsed since last data
205 //
206 // Always-fill model: every iteration writes exactly one DMA buffer's worth, mixing real audio
207 // and silence padding as needed. The blocking ``i2s_channel_write`` paces the loop at the DMA
208 // consumption rate, and every buffer write is matched 1:1 with a record on ``write_records_queue_``.
209 //
210 // While paused, the real-audio fill is skipped and the entire DMA buffer is filled with silence;
211 // the same blocking ``i2s_channel_write`` provides natural pacing (one buffer per ~DMA_BUFFER_DURATION_MS),
212 // so the lockstep invariant is preserved without burning CPU.
213 while (this->pause_state_ || !this->timeout_.has_value() ||
214 (millis() - last_data_received_time) <= this->timeout_.value()) {
215 uint32_t event_group_bits = xEventGroupGetBits(this->event_group_);
216
217 if (event_group_bits & SpeakerEventGroupBits::COMMAND_STOP) {
218 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::COMMAND_STOP);
219 ESP_LOGV(TAG, "Exiting: COMMAND_STOP received");
220 break;
221 }
222 if (event_group_bits & SpeakerEventGroupBits::COMMAND_STOP_GRACEFULLY) {
223 xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::COMMAND_STOP_GRACEFULLY);
224 stop_gracefully = true;
225 }
226
227 if (this->audio_stream_info_ != this->current_stream_info_) {
228 // Audio stream info changed, stop the speaker task so it will restart with the proper settings.
229 ESP_LOGV(TAG, "Exiting: stream info changed");
230 break;
231 }
232
233 if (event_group_bits & SpeakerEventGroupBits::ERR_DROPPED_EVENT) {
234 ESP_LOGE(TAG, "ISR event queue overflow, resyncing DMA lockstep");
235 resync_needed = true;
236 }
237 if (resync_needed) {
238 // Rebuild the lockstep in place; the ring buffer keeps accepting audio throughout
239 const bool resynced = this->resync_lockstep_(unrecorded_frames, preload_silence);
240 unrecorded_frames = 0;
241 pending_real_buffers = 0;
242 resync_needed = false;
243 if (!resynced) {
244 ESP_LOGE(TAG, "DMA lockstep resync failed, restarting speaker task");
245 break;
246 }
247 }
248
249 // Drain ISR-stamped completion events. Each event corresponds 1:1 with a write_records_queue_
250 // entry by construction (preloaded records at startup, plus exactly one record pushed per
251 // iteration alongside exactly one DMA-buffer-sized write).
252 int64_t write_timestamp;
253 bool lockstep_broken = false;
254 while (xQueueReceive(this->i2s_event_queue_, &write_timestamp, 0)) {
255 uint32_t real_frames = 0;
256 if (xQueueReceive(this->write_records_queue_, &real_frames, 0) != pdTRUE) {
257 // Should never happen: would indicate the lockstep invariant is broken.
258 ESP_LOGE(TAG, "Event without matching write record, resyncing DMA lockstep");
259 lockstep_broken = true;
260 break;
261 }
262 if (real_frames > 0) {
263 pending_real_buffers--;
264 // Real audio is packed at the start of each DMA buffer with any silence padding on the
265 // tail, so the real audio finished playing earlier than the buffer-completion timestamp
266 // by the duration of the trailing zeros.
267 const uint32_t silence_frames = frames_per_dma_buffer - real_frames;
268 const int64_t adjusted_ts =
269 write_timestamp - this->current_stream_info_.frames_to_microseconds(silence_frames);
270 this->audio_output_callback_(real_frames, adjusted_ts);
271 }
272 }
273 if (lockstep_broken) {
274 resync_needed = true;
275 continue;
276 }
277
278 // Graceful stop: exit only after the source's exposed chunk is drained, the underlying ring
279 // buffer has nothing left to hand over, and every real-audio buffer we submitted has been
280 // confirmed played. ``has_buffered_data()`` returns bytes still sitting in the ring buffer
281 // awaiting fill().
282 if (stop_gracefully && audio_source->available() == 0 && !this->has_buffered_data() &&
283 pending_real_buffers == 0) {
284 ESP_LOGV(TAG, "Exiting: graceful stop complete");
285 break;
286 }
287
288 // Compose exactly one DMA buffer's worth: drain as much real audio as the source currently
289 // exposes (may take multiple fill() calls when crossing a ring buffer wrap), then pad any
290 // remainder with silence. All writes pack into the next free DMA descriptor in order, so the
291 // descriptor ends up holding [real audio][silence padding]. ``bytes_written_total`` counts
292 // output-format bytes so it tracks how full the DMA buffer is regardless of any narrowing.
293 size_t bytes_written_total = 0;
294 uint32_t real_frames_total = 0;
295 bool partial_write_failure = false;
296
297 if (!this->pause_state_) {
298 while (bytes_written_total < dma_buffer_bytes) {
299 size_t bytes_read = audio_source->fill(pdMS_TO_TICKS(DMA_BUFFER_DURATION_MS) / 2);
300 if (bytes_read > 0) {
301 // Apply volume at the input bit depth, before any narrowing, so the full precision is scaled.
302 uint8_t *new_data = audio_source->mutable_data() + audio_source->available() - bytes_read;
303 this->apply_software_volume_(new_data, bytes_read);
304 }
305
306 // Convert as many whole frames as fit in the remaining DMA space, bounded by what the source
307 // currently exposes. Frame counts are shared between input and output; only the byte widths differ.
308 uint32_t frames_available = this->current_stream_info_.bytes_to_frames(audio_source->available());
309 const uint32_t frames_room =
310 this->output_stream_info_.bytes_to_frames(dma_buffer_bytes - bytes_written_total);
311 uint32_t padding_frames = 0;
312 if (pair_aligned && frames_available == 0 && frames_room >= 2 && !audio_source->has_buffered_data()) {
313 // Silence padding follows, so write a held half pair now with a silent partner rather than strand it.
314 // Only the real frame is reported as played.
315 const size_t real_bytes = audio_source->expose_padded_partial(bytes_per_frame);
316 if (real_bytes > 0) {
317 this->apply_software_volume_(audio_source->mutable_data(), real_bytes);
318 frames_available = this->current_stream_info_.bytes_to_frames(audio_source->available());
319 padding_frames = frames_available - this->current_stream_info_.bytes_to_frames(real_bytes);
320 }
321 }
322 const uint32_t frames_to_write = std::min(frames_available, frames_room);
323 if (frames_to_write == 0) {
324 // Ring buffer has nothing more to hand over right now; pad the rest of this DMA buffer
325 // with silence so the lockstep invariant (one write per iteration) is preserved.
326 break;
327 }
328
329 const size_t input_bytes = this->current_stream_info_.frames_to_bytes(frames_to_write);
330 const size_t output_bytes = this->output_stream_info_.frames_to_bytes(frames_to_write);
331
332 uint8_t *chunk = audio_source->mutable_data();
333 size_t bw = 0;
334#ifdef USE_ESP32_VARIANT_ESP32
335 if (widening) {
336 bw = this->write_widened_(chunk, frames_to_write);
337 } else
338#endif
339 {
340 if (narrowing) {
341 // Narrow the bit depth in place: output exactly aliases input with the same channel count and a
342 // smaller width, which copy_frames handles as a single forward pass. Only the frames about to be
343 // consumed are overwritten, so any unprocessed tail stays intact for the next iteration.
344 esp_audio_libs::pcm_convert::copy_frames(chunk, chunk, input_bytes_per_sample, channels,
345 output_bytes_per_sample, channels, frames_to_write);
346 }
347 this->swap_esp32_mono_samples_(chunk, output_bytes);
348 i2s_channel_write(this->tx_handle_, chunk, output_bytes, &bw, WRITE_TIMEOUT_TICKS);
349 }
350 if (bw != output_bytes) {
351 // A short write breaks DMA descriptor alignment for every subsequent event. Drop the chunk rather
352 // than retry it: it may already have been converted in place.
353 ESP_LOGE(TAG, "Partial DMA write (%u of %u bytes), resyncing DMA lockstep", (unsigned) bw,
354 (unsigned) output_bytes);
355 audio_source->consume(input_bytes);
356 real_frames_total += frames_to_write - padding_frames;
357 partial_write_failure = true;
358 break;
359 }
360 audio_source->consume(input_bytes);
361 bytes_written_total += output_bytes;
362 real_frames_total += frames_to_write - padding_frames;
363 if (padding_frames > 0) {
364 // The source was already empty; skip waiting on another fill() before the silence padding
365 break;
366 }
367 }
368 if (real_frames_total > 0) {
369 last_data_received_time = millis();
370 }
371 }
372
373 if (partial_write_failure) {
374 unrecorded_frames += real_frames_total;
375 resync_needed = true;
376 continue;
377 }
378
379 const size_t silence_bytes = dma_buffer_bytes - bytes_written_total;
380 if (silence_bytes > 0) {
381 size_t bw = 0;
382 i2s_channel_write(this->tx_handle_, silence_buffer, silence_bytes, &bw, WRITE_TIMEOUT_TICKS);
383 if (bw != silence_bytes) {
384 // Same descriptor-alignment hazard as a partial real-audio write.
385 ESP_LOGE(TAG, "Partial DMA write (%u of %u bytes), resyncing DMA lockstep", (unsigned) bw,
386 (unsigned) silence_bytes);
387 unrecorded_frames += real_frames_total;
388 resync_needed = true;
389 continue;
390 }
391 }
392
393 // Push the matching write record. Capacity headroom in I2S_EVENT_QUEUE_COUNT guarantees this
394 // succeeds even with a transient backlog of unprocessed events; if it ever fails the lockstep
395 // invariant is broken and every subsequent timestamp would be silently wrong, so rebuild it.
396 if (xQueueSend(this->write_records_queue_, &real_frames_total, 0) != pdTRUE) {
397 ESP_LOGE(TAG, "Write records queue full, resyncing DMA lockstep");
398 unrecorded_frames += real_frames_total;
399 resync_needed = true;
400 continue;
401 }
402 if (real_frames_total > 0) {
403 pending_real_buffers++;
404 }
405 }
406 }
407
408 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::TASK_STOPPING);
409
410 audio_source.reset();
411
412 if (silence_buffer != nullptr) {
413 silence_allocator.deallocate(silence_buffer, dma_buffer_bytes);
414 silence_buffer = nullptr;
415 }
416
417 xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::TASK_STOPPED);
418
419 while (true) {
420 // Continuously delay until the loop method deletes the task
421 vTaskDelay(pdMS_TO_TICKS(10));
422 }
423}
424
426 if ((this->i2s_role_ & I2S_ROLE_SLAVE) && (this->sample_rate_ != audio_stream_info.get_sample_rate())) { // NOLINT
427 // Can't reconfigure I2S bus, so the sample rate must match the configured value
428 ESP_LOGE(TAG, "Incompatible stream settings");
429 return ESP_ERR_NOT_SUPPORTED;
430 }
431
432 // Compute the output width so the driver, DMA buffers, and the task's conversion all agree. A stream wider than
433 // the configured slot is narrowed to it, and a narrower stream keeps its width for the peripheral to pad into the
434 // slot. The original ESP32 cannot clock a slot wider than its data, so there every stream is converted to the
435 // slot's memory width instead.
436 uint8_t output_bits_per_sample = audio_stream_info.get_bits_per_sample();
437 if (this->slot_bit_width_ != I2S_SLOT_BIT_WIDTH_AUTO) {
438#ifdef USE_ESP32_VARIANT_ESP32
439 output_bits_per_sample = this->slot_memory_bits_();
440#else
441 const uint8_t configured_bits = static_cast<uint8_t>(this->slot_bit_width_);
442 if (output_bits_per_sample > configured_bits) {
443 output_bits_per_sample = configured_bits;
444 }
445#endif
446 }
447 this->output_stream_info_ = audio::AudioStreamInfo(output_bits_per_sample, audio_stream_info.get_channels(),
448 audio_stream_info.get_sample_rate());
449
450#ifdef USE_ESP32_VARIANT_ESP32
451 // Only a slot left at AUTO can reach this; every configured slot is converted to 16- or 32-bit samples above
452 if (output_bits_per_sample % 16 != 0) {
453 ESP_LOGE(TAG, "ESP32 supports only 16- or 32-bit output, got %u-bit", (unsigned) output_bits_per_sample);
454 return ESP_ERR_NOT_SUPPORTED;
455 }
456#endif // USE_ESP32_VARIANT_ESP32
457
458#ifdef USE_I2S_AUDIO_FULL_DUPLEX
459 if (this->parent_->is_full_duplex()) {
460 // The parent set up the channel once from the configured format, so the stream must produce exactly that
461 const audio::AudioStreamInfo required = this->full_duplex_stream_info_();
462 if (this->output_stream_info_ != required) {
463 ESP_LOGE(TAG, "Full duplex requires %u-bit, %u channel audio at %" PRIu32 " Hz",
464 (unsigned) required.get_bits_per_sample(), (unsigned) required.get_channels(),
465 required.get_sample_rate());
466 if (this->output_stream_info_.get_channels() != required.get_channels()) {
467 ESP_LOGE(TAG, "A resampler does not change the channel count; add a mixer speaker with num_channels: %u",
468 (unsigned) required.get_channels());
469 }
470 return ESP_ERR_NOT_SUPPORTED;
471 }
472 this->current_stream_info_ = audio_stream_info;
473 // The speaker task will enable the channel after preloading.
474 return this->acquire_full_duplex_channel_(I2S_EVENT_QUEUE_COUNT);
475 }
476#endif // USE_I2S_AUDIO_FULL_DUPLEX
477
478 if (!this->parent_->try_lock()) {
479 ESP_LOGE(TAG, "Parent bus is busy");
480 return ESP_ERR_INVALID_STATE;
481 }
482
483 // Reuse a kept channel while the stream format matches
484 if (this->tx_handle_ != nullptr) {
485 if (this->current_stream_info_ == audio_stream_info) {
486 return ESP_OK;
487 }
488 this->delete_channel_();
489 }
490
491 this->current_stream_info_ = audio_stream_info;
492
493 i2s_chan_config_t chan_cfg;
494 i2s_std_config_t std_cfg;
495 this->build_i2s_config_(this->output_stream_info_, chan_cfg, std_cfg);
496
497 // The speaker task will enable the channel after preloading.
498 return this->init_i2s_channel_(chan_cfg, std_cfg, I2S_EVENT_QUEUE_COUNT);
499}
500
501#ifdef USE_I2S_AUDIO_FULL_DUPLEX
503 return audio::AudioStreamInfo(this->slot_memory_bits_(), this->slot_mode_ == I2S_SLOT_MODE_STEREO ? 2 : 1,
504 this->sample_rate_);
505}
506
507void I2SAudioSpeaker::build_full_duplex_config(i2s_chan_config_t &chan_cfg, i2s_std_config_t &std_cfg) {
508 this->build_i2s_config_(this->full_duplex_stream_info_(), chan_cfg, std_cfg);
509}
510#endif // USE_I2S_AUDIO_FULL_DUPLEX
511
512void I2SAudioSpeaker::build_i2s_config_(const audio::AudioStreamInfo &output_stream_info, i2s_chan_config_t &chan_cfg,
513 i2s_std_config_t &std_cfg) const {
514 // The DMA buffers hold output-format (post-narrowing) samples, so size them from the output stream info.
515 uint32_t dma_buffer_length = dma_buffer_frames(output_stream_info, dma_frame_multiple(output_stream_info));
516
517 // Log DMA configuration for debugging
518 ESP_LOGV(TAG, "I2S DMA config: %zu buffers x %lu frames", (size_t) DMA_BUFFERS_COUNT,
519 (unsigned long) dma_buffer_length);
520
521 chan_cfg = {
522 .id = this->parent_->get_port(),
523 .role = this->i2s_role_,
524 .dma_desc_num = DMA_BUFFERS_COUNT,
525 .dma_frame_num = dma_buffer_length,
526 .auto_clear = true,
527 .intr_priority = 3,
528 };
529
530 // Build standard I2S clock/slot/gpio configuration
531 i2s_std_clk_config_t clk_cfg = {
532 .sample_rate_hz = output_stream_info.get_sample_rate(),
533 .clk_src = this->get_clock_source_(),
534 .mclk_multiple = this->mclk_multiple_,
535 };
536
537 i2s_slot_mode_t slot_mode = this->slot_mode_;
538 i2s_std_slot_mask_t slot_mask = this->std_slot_mask_;
539 if (output_stream_info.get_channels() == 1) {
540 slot_mode = I2S_SLOT_MODE_MONO;
541 } else if (output_stream_info.get_channels() == 2) {
542 slot_mode = I2S_SLOT_MODE_STEREO;
543 slot_mask = I2S_STD_SLOT_BOTH;
544 }
545
546 // Configure the data bit width from the output (post-conversion) format, which is what is clocked out.
547 i2s_data_bit_width_t data_bit_width = (i2s_data_bit_width_t) output_stream_info.get_bits_per_sample();
548#ifdef USE_ESP32_VARIANT_ESP32
549 // The original ESP32 clocks data at the slot width; a 24-bit slot sends the top 24 bits of each 32-bit sample
550 if (this->slot_bit_width_ != I2S_SLOT_BIT_WIDTH_AUTO) {
551 data_bit_width = (i2s_data_bit_width_t) this->slot_bit_width_;
552 }
553#endif
554 i2s_std_slot_config_t slot_cfg;
555 switch (this->i2s_comm_fmt_) {
556 case I2SCommFmt::PCM:
557 slot_cfg = I2S_STD_PCM_SLOT_DEFAULT_CONFIG(data_bit_width, slot_mode);
558 break;
559 case I2SCommFmt::MSB:
560 slot_cfg = I2S_STD_MSB_SLOT_DEFAULT_CONFIG(data_bit_width, slot_mode);
561 break;
562 default:
563 slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(data_bit_width, slot_mode);
564 break;
565 }
566
567 slot_cfg.slot_bit_width = this->slot_bit_width_;
568 if (this->slot_bit_width_ != I2S_SLOT_BIT_WIDTH_AUTO) {
569 slot_cfg.ws_width = static_cast<uint32_t>(this->slot_bit_width_);
570 }
571 slot_cfg.slot_mask = slot_mask;
572
573 i2s_std_gpio_config_t gpio_cfg = this->parent_->get_pin_config();
574 gpio_cfg.dout = this->dout_pin_;
575
576 std_cfg = {
577 .clk_cfg = clk_cfg,
578 .slot_cfg = slot_cfg,
579 .gpio_cfg = gpio_cfg,
580 };
581}
582
584#ifdef USE_ESP32_VARIANT_ESP32
585 // The original ESP32 stores a 24-bit slot's samples in 32-bit words
586 if (this->slot_bit_width_ == I2S_SLOT_BIT_WIDTH_24BIT) {
587 return 32;
588 }
589#endif
590 return static_cast<uint8_t>(this->slot_bit_width_);
591}
592
593#ifdef USE_ESP32_VARIANT_ESP32
594size_t I2SAudioSpeaker::write_widened_(const uint8_t *input, uint32_t frames) {
595 alignas(4) uint8_t widened[WIDEN_BUFFER_BYTES];
596 const uint8_t channels = this->current_stream_info_.get_channels();
597 const uint8_t input_bytes_per_sample = this->current_stream_info_.get_bits_per_sample() / 8;
598 const uint8_t output_bytes_per_sample = this->output_stream_info_.get_bits_per_sample() / 8;
599 const uint32_t frames_per_pass = WIDEN_BUFFER_BYTES / this->output_stream_info_.frames_to_bytes(1);
600
601 size_t bytes_written = 0;
602 while (frames > 0) {
603 const uint32_t pass_frames = std::min(frames, frames_per_pass);
604 esp_audio_libs::pcm_convert::copy_frames(input, widened, input_bytes_per_sample, channels, output_bytes_per_sample,
605 channels, pass_frames);
606 const size_t pass_bytes = this->output_stream_info_.frames_to_bytes(pass_frames);
607 // 8-bit mono widened to 16-bit mono needs the pair swap; passes hold whole pairs since writes are pair-aligned
608 this->swap_esp32_mono_samples_(widened, pass_bytes);
609 size_t bw = 0;
610 i2s_channel_write(this->tx_handle_, widened, pass_bytes, &bw, WRITE_TIMEOUT_TICKS);
611 bytes_written += bw;
612 if (bw != pass_bytes) {
613 break;
614 }
615 input += this->current_stream_info_.frames_to_bytes(pass_frames);
616 frames -= pass_frames;
617 }
618 return bytes_written;
619}
620#endif // USE_ESP32_VARIANT_ESP32
621
622} // namespace esphome::i2s_audio
623
624#endif // USE_ESP32
An STL allocator that uses SPI or internal RAM.
Definition helpers.h:2396
void deallocate(T *p, size_t n)
Definition helpers.h:2453
T * allocate(size_t n)
Definition helpers.h:2423
size_t ms_to_bytes(uint32_t ms) const
Converts duration to bytes.
Definition audio.h:75
size_t frames_to_bytes(uint32_t frames) const
Converts frames to bytes.
Definition audio.h:53
uint8_t get_bits_per_sample() const
Definition audio.h:28
uint32_t frames_to_microseconds(uint32_t frames) const
Computes the duration, in microseconds, the given amount of frames represents.
Definition audio.cpp:25
uint32_t bytes_to_frames(size_t bytes) const
Convert bytes to frames.
Definition audio.h:43
uint8_t get_channels() const
Definition audio.h:29
uint32_t ms_to_frames(uint32_t ms) const
Converts duration to frames.
Definition audio.h:63
uint32_t get_sample_rate() const
Definition audio.h:30
static std::unique_ptr< RingBufferAudioSource > create(std::shared_ptr< ring_buffer::RingBuffer > ring_buffer, size_t max_fill_bytes, uint8_t alignment_bytes=1)
Creates a new ring-buffer-backed audio source after validating its parameters.
i2s_std_slot_mask_t std_slot_mask_
Definition i2s_audio.h:38
i2s_slot_bit_width_t slot_bit_width_
Definition i2s_audio.h:39
i2s_clock_src_t get_clock_source_() const
Definition i2s_audio.h:27
i2s_mclk_multiple_t mclk_multiple_
Definition i2s_audio.h:42
std::weak_ptr< ring_buffer::RingBuffer > audio_ring_buffer_
void swap_esp32_mono_samples_(uint8_t *data, size_t bytes_read)
Plays the provided audio data.
audio::AudioStreamInfo full_duplex_stream_info_() const
The output format of a full duplex bus, fixed by the configuration since the channel is set up once.
static uint32_t dma_frame_multiple(const audio::AudioStreamInfo &stream_info)
Frame multiple for DMA buffers and writes; 2 keeps ESP32 mono sample pairs word-aligned.
size_t write_widened_(const uint8_t *input, uint32_t frames)
Widens frames to the output bit depth through a small stack buffer and writes them to the peripheral.
uint8_t slot_memory_bits_() const
Bits per sample that the configured slot takes in DMA memory.
esp_err_t start_i2s_driver(audio::AudioStreamInfo &audio_stream_info) override
void build_i2s_config_(const audio::AudioStreamInfo &output_stream_info, i2s_chan_config_t &chan_cfg, i2s_std_config_t &std_cfg) const
Builds the channel and standard mode configuration for the given output format.
void build_full_duplex_config(i2s_chan_config_t &chan_cfg, i2s_std_config_t &std_cfg) override
static std::unique_ptr< RingBuffer > create(size_t len, MemoryPreference preference=MemoryPreference::EXTERNAL_FIRST)
CallbackManager< void(uint32_t, int64_t)> audio_output_callback_
Definition speaker.h:157
audio::AudioStreamInfo audio_stream_info_
Definition speaker.h:149
ESPHOME_LOG_TAG(TAG, "i2s_audio")
auto * new_data
Definition helpers.cpp:38
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
static void uint32_t