ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
usb_audio_speaker.cpp
Go to the documentation of this file.
1#include "usb_audio_speaker.h"
2
3#ifdef USE_USB_AUDIO
4
5#include <algorithm>
6#include <cinttypes>
7
8#include "esphome/core/hal.h"
9#include "esphome/core/log.h"
10#include "esp_err.h"
11#include "esp_timer.h"
12#include "sdkconfig.h"
13
14namespace esphome::usb_audio {
15
16ESPHOME_LOG_TAG(TAG, "usb_audio.spk");
17
18static constexpr size_t MAX_TIMEOUT_RETRIES = 4;
19// Zeros are silence for the signed PCM the driver streams; 240 is a whole number of frames for every format.
20static constexpr uint8_t SILENCE[240] = {};
21
23 const auto &info = this->usb_stream_info_;
24 this->write_chunk_ = info.frames_to_bytes(std::max<uint32_t>(info.bytes_to_frames(this->buffer_size_ / 4), 1));
25 // The driver sends 1 ms packets, grouped into transfers it keeps in flight.
26 this->frame_bytes_ = info.frames_to_bytes(1);
27 this->packet_bytes_ = info.frames_to_bytes(info.get_sample_rate() / 1000);
28 this->packet_frac_ = info.get_sample_rate() % 1000;
29 this->transfer_bytes_ = info.frames_to_bytes((info.get_sample_rate() + 999) / 1000 * CONFIG_UAC_NUM_PACKETS_PER_URB);
30 this->transfer_us_ = CONFIG_UAC_NUM_PACKETS_PER_URB * 1000;
31 this->in_flight_us_ = CONFIG_UAC_NUM_ISOC_URBS * this->transfer_us_;
32 // About 10 ms per report, like the I2S speaker's DMA buffers.
33 this->report_frames_ = std::max<uint32_t>(info.get_sample_rate() / 100, 1);
34 // start(), stop() and finish() wake the loop.
35 this->disable_loop();
36}
37
39 ESP_LOGCONFIG(TAG,
40 "USB Speaker:\n"
41 " Sample rate: %" PRIu32 " Hz\n"
42 " Bits per sample: %u\n"
43 " Channels: %u\n"
44 " Buffer size: %" PRIu32 "\n"
45 " Write timeout: %" PRIu32 " ms",
46 this->usb_stream_info_.get_sample_rate(), this->usb_stream_info_.get_bits_per_sample(),
47 this->usb_stream_info_.get_channels(), this->buffer_size_, this->write_timeout_ms_);
48}
49
51 this->deliver_reports_();
52 const uint8_t commands = this->commands_.exchange(0);
53 if (commands & COMMAND_STOP) {
54 this->stop_();
55 }
56 if ((commands & COMMAND_START) && this->state_ == speaker::STATE_STOPPED) {
57 // Suspending flushed the driver's ring buffer, and resuming restarts its packet sizing.
58 portENTER_CRITICAL(&this->taken_lock_);
59 this->ring_bytes_ = 0;
60 this->ring_padding_ = 0;
61 // Resuming resets the driver's accumulator, then prepares every transfer, which advances it by their packets.
62 this->packet_frac_accum_ = CONFIG_UAC_NUM_ISOC_URBS * CONFIG_UAC_NUM_PACKETS_PER_URB * this->packet_frac_ % 1000;
63 this->unreported_frames_ = 0;
64 this->report_frames_pending_ = 0;
65 this->last_finish_us_ = 0;
66 // The idle window for a tail flush starts now, not at the last take of the previous stream.
67 this->last_taken_us_ = static_cast<uint32_t>(esp_timer_get_time());
68 portEXIT_CRITICAL(&this->taken_lock_);
70 // Answers through on_stream_state() now or once the device connects.
71 this->parent_->resume(Endpoint::SPEAKER);
72 }
73
74 if (commands & COMMAND_FINISH) {
75 if (this->state_ == speaker::STATE_RUNNING) {
76 this->begin_finishing_();
77 } else if (this->state_ == speaker::STATE_STARTING) {
78 // The stream is still starting; on_stream_state() finishes it once it runs.
79 this->finish_after_start_ = true;
80 }
81 }
82 if (this->finishing_ && this->pad_remaining_ > 0) {
83 this->pad_with_silence_();
84 }
85 // has_buffered_data_() turns false once the driver has taken the last whole transfer and it has had time to play.
86 if (this->finishing_ && this->pad_remaining_ == 0 && !this->has_buffered_data_()) {
87 this->stop_();
88 }
89 if (!this->finishing_ && !this->flush_tail_()) {
90 this->disable_loop();
91 }
92}
93
94// Called with taken_lock_ held. The accumulator mirrors the driver's packet sizing at fractional sample rates.
96 uint32_t size = 0;
97 for (int i = 0; i < CONFIG_UAC_NUM_PACKETS_PER_URB; i++) {
98 accum += this->packet_frac_;
99 size += this->packet_bytes_;
100 if (accum >= 1000) {
101 size += this->frame_bytes_;
102 accum -= 1000;
103 }
104 }
105 return size;
106}
107
108// Less than the next transfer of the caller's audio: the driver parks its transfers until the ring holds a whole one.
110 // No transfer is larger than transfer_bytes_, so a full transfer in the ring rules a tail out without the lock.
111 const uint32_t ring = this->ring_bytes_;
112 if (this->state_ != speaker::STATE_RUNNING || ring >= this->transfer_bytes_ || ring <= this->ring_padding_) {
113 return 0;
114 }
115 portENTER_CRITICAL(&this->taken_lock_);
116 uint32_t accum = this->packet_frac_accum_;
117 const uint32_t next = this->next_transfer_bytes_(accum);
118 portEXIT_CRITICAL(&this->taken_lock_);
119 return ring < next ? next - ring : 0;
120}
121
122// Pads an audio tail to a whole transfer once the bus has gone idle, so the driver takes it and the frames get
123// reported; a caller that stops mid-transfer (the mixer at the end of a stream) would otherwise wait for them forever.
124// Returns true while a tail is still pending, so loop() keeps running.
126 if (this->audio_tail_bytes_() == 0) {
127 return false;
128 }
129 if (this->transfers_in_flight_()) {
130 return true;
131 }
132 // Padding must sit at the end of the ring, so no caller write may interleave with it: the flag is raised before the
133 // in-flight count is read and play_internal_() reads it after raising the count, so one side always sees the other.
134 if (!this->flushing_) {
135 this->flushing_ = true;
136 if (this->writes_in_flight_ > 0) {
137 this->flushing_ = false;
138 return true;
139 }
140 this->pad_remaining_ = this->audio_tail_bytes_();
141 }
142 // A busy driver can cut the padding short; the hold stays until the rest is written on a later pass.
143 this->pad_with_silence_();
144 if (this->pad_remaining_ > 0) {
145 return true;
146 }
147 // The ring now holds exactly the next transfer (or nothing, if the driver took it meanwhile): no tail is left.
148 this->flushing_ = false;
149 return false;
150}
151
152void USBAudioSpeaker::request_(uint8_t set, uint8_t clear) {
153 this->commands_.fetch_and(static_cast<uint8_t>(~clear));
154 this->commands_.fetch_or(set);
156}
157
160 return;
161 }
163}
164
166
168
170 if (this->finishing_) {
171 return;
172 }
173 this->finishing_ = true;
174 // finish() pads the last transfer itself, so a tail flush that was cut short hands over to it.
175 this->flushing_ = false;
176 this->pad_remaining_ = this->transfer_bytes_;
177 // loop() pads the last transfer and stops once the audio has played.
178 this->enable_loop();
179}
180
182 this->finishing_ = false;
183 this->flushing_ = false;
184 this->finish_after_start_ = false;
185 this->pad_remaining_ = 0;
186 if (this->state_ == speaker::STATE_STOPPED) {
187 return;
188 }
189 this->parent_->suspend(Endpoint::SPEAKER);
191}
192
194 if (event == StreamEvent::RUNNING) {
195 if (this->state_ == speaker::STATE_STARTING) {
197 if (this->finish_after_start_) {
198 this->finish_after_start_ = false;
199 this->begin_finishing_();
200 }
201 }
202 return;
203 }
204 // Playback stops on a lost device as well as a failed start; the next start() opens it again.
205 if (event == StreamEvent::LOST && this->state_ == speaker::STATE_RUNNING) {
206 ESP_LOGW(TAG, "USB device disconnected, stopping playback");
207 }
208 this->stop_();
209}
210
211size_t USBAudioSpeaker::play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) {
212 // 0 ticks is one non-blocking pass; portMAX_DELAY is capped by the configured write timeout.
213 const uint32_t budget_ms = ticks_to_wait == portMAX_DELAY ? this->write_timeout_ms_ : pdTICKS_TO_MS(ticks_to_wait);
214 return this->play_internal_(data, length, budget_ms);
215}
216
217// Callers such as voice_assistant and rtttl call this from loop(), so it never blocks.
218size_t USBAudioSpeaker::play(const uint8_t *data, size_t length) { return this->play(data, length, 0); }
219
220size_t USBAudioSpeaker::play_internal_(const uint8_t *data, size_t length, uint32_t budget_ms) {
221 if (this->audio_stream_info_ != this->usb_stream_info_) {
222 // Playing it through the configured stream would change the speed and channel layout.
223 if (!this->format_mismatch_.exchange(true)) {
224 const auto &info = this->audio_stream_info_;
225 ESP_LOGE(TAG,
226 "Audio format (%" PRIu32 " Hz, %u bits, %u channels) does not match the USB stream; use a resampler "
227 "speaker",
228 info.get_sample_rate(), info.get_bits_per_sample(), info.get_channels());
229 }
230 if (budget_ms > 0) {
231 vTaskDelay(pdMS_TO_TICKS(budget_ms));
232 }
233 return 0;
234 }
235 this->format_mismatch_ = false;
236
237 if (this->state_ != speaker::STATE_RUNNING) {
238 this->start();
239 // Wait out the budget so a pipeline task retrying play() does not spin.
240 if (budget_ms > 0) {
241 vTaskDelay(pdMS_TO_TICKS(budget_ms));
242 }
243 return 0;
244 }
245
246 // Counted before the hub's handle is read, so the hub never closes the device under this call.
247 this->writes_in_flight_.fetch_add(1);
248
249 // Runs on the caller's task, so the cached loop time does not apply.
250 const uint32_t start_ms = millis();
251 uint32_t now = start_ms;
252 size_t written = 0;
253 size_t timeout_retries = 0;
254 while (written < length) {
255 const uint32_t elapsed = now - start_ms;
256 if (budget_ms > 0 && elapsed >= budget_ms) {
257 break;
258 }
259 const size_t chunk =
260 this->flushing_ ? 0 : std::min<size_t>({length - written, this->write_chunk_, this->ring_room_()});
261 if (chunk == 0) {
262 // Back-pressure: wait for the driver to take a transfer, or for loop() to finish padding a tail.
263 if (budget_ms == 0) {
264 break;
265 }
266 vTaskDelay(1);
267 now = millis();
268 continue;
269 }
270 const uint32_t timeout_ms = budget_ms > 0 ? budget_ms - elapsed : 0;
271 const esp_err_t err = this->write_(data + written, chunk, timeout_ms, false);
272 now = millis();
273 if (err == ESP_OK) {
274 written += chunk;
275 timeout_retries = 0;
276 } else if (err == ESP_ERR_INVALID_STATE) {
277 // The device went away.
278 break;
279 } else if (err != ESP_ERR_TIMEOUT) {
280 ESP_LOGW(TAG, "Write error: %s", esp_err_to_name(err));
281 break;
282 } else if (budget_ms == 0 || ++timeout_retries >= MAX_TIMEOUT_RETRIES) {
283 // A full driver buffer is back-pressure; the caller retries.
284 break;
285 }
286 }
287 this->writes_in_flight_.fetch_sub(1);
288 if (this->audio_tail_bytes_() > 0) {
290 }
291 return written;
292}
293
295 // Whole frames up to buffer_size_. ring_bytes_ is never below the real fill, so a write of this much does not wait.
296 const uint32_t ring = this->ring_bytes_;
297 const uint32_t room = ring < this->buffer_size_ ? this->buffer_size_ - ring : 0;
298 return room - room % this->frame_bytes_;
299}
300
301esp_err_t USBAudioSpeaker::write_(const uint8_t *data, size_t length, uint32_t timeout_ms, bool padding) {
302 // Counted first: the driver submits transfers inside the write, and on_transfer_taken() must see these bytes then.
303 // A failed write stores nothing, since the driver only writes whole chunks.
304 this->ring_bytes_.fetch_add(length);
305 if (padding) {
306 this->ring_padding_.fetch_add(length);
307 }
308 const esp_err_t err = this->parent_->write_speaker(data, length, timeout_ms);
309 if (err != ESP_OK) {
310 this->ring_bytes_.fetch_sub(length);
311 if (padding) {
312 this->ring_padding_.fetch_sub(length);
313 }
314 }
315 return err;
316}
317
319 if (this->state_ != speaker::STATE_RUNNING) {
320 this->pad_remaining_ = 0;
321 return;
322 }
323 // Counted before the hub's handle is read, so the hub never closes the device under this call.
324 this->writes_in_flight_.fetch_add(1);
325 const size_t piece = sizeof(SILENCE) - sizeof(SILENCE) % this->usb_stream_info_.frames_to_bytes(1);
326 while (this->pad_remaining_ > 0) {
327 const size_t chunk = std::min<size_t>({this->pad_remaining_, piece, this->ring_room_()});
328 if (chunk == 0 || this->write_(SILENCE, chunk, 0, true) != ESP_OK) {
329 // A full buffer; the rest is written on a later loop().
330 break;
331 }
332 this->pad_remaining_ -= chunk;
333 }
334 this->writes_in_flight_.fetch_sub(1);
335}
336
338 bool report = false;
339 portENTER_CRITICAL(&this->taken_lock_);
340 // Mirror the driver: the next transfer is CONFIG_UAC_NUM_PACKETS_PER_URB packets, and the driver takes it only when
341 // the ring buffer holds all of it; otherwise it parks the transfer until the next write.
342 uint32_t accum = this->packet_frac_accum_;
343 const uint32_t size = this->next_transfer_bytes_(accum);
344 const uint32_t ring = this->ring_bytes_;
345 // A tail left behind (less than the next transfer of the caller's audio) is flushed from loop() once the bus idles.
346 bool tail = ring < size && ring > this->ring_padding_;
347 if (ring >= size) {
348 this->packet_frac_accum_ = accum;
349 this->ring_bytes_.fetch_sub(size);
350 {
351 const uint32_t left = ring - size;
352 uint32_t next_accum = accum;
353 tail =
354 left < this->transfer_bytes_ && left > this->ring_padding_ && left < this->next_transfer_bytes_(next_accum);
355 }
356 // Padding sits at the end of the ring buffer and is not audio from the caller, so it is not reported.
357 const uint32_t padding = std::min<uint32_t>(this->ring_padding_, ring);
358 const uint32_t audio = std::min(size, ring - padding);
359 if (audio < size) {
360 this->ring_padding_.fetch_sub(std::min(size - audio, padding));
361 }
362 const int64_t now_us = esp_timer_get_time();
363 this->last_taken_us_ = static_cast<uint32_t>(now_us);
364 // The bus plays one packet per millisecond, so while it streams a transfer finishes one transfer after the one
365 // taken before it, however late this callback runs. It cannot finish later than now plus the transfers in flight,
366 // so a callback that runs on time pulls back any lateness the chain picked up. When the bus is idle, after a start
367 // (the driver submits nothing until the first write) or once it ran dry, the transfer plays right away.
368 const int64_t finish_us = this->last_finish_us_ < now_us
369 ? now_us + this->transfer_us_
370 : std::min(this->last_finish_us_ + this->transfer_us_, now_us + this->in_flight_us_);
371 this->last_finish_us_ = finish_us;
373 // Batched like the I2S speaker's DMA buffers: about every 10 ms, and once the caller's audio runs out.
374 if (this->unreported_frames_ > 0 && (this->unreported_frames_ >= this->report_frames_ || audio == ring - padding)) {
376 this->report_finish_us_ = finish_us;
377 this->unreported_frames_ = 0;
378 report = true;
379 }
380 }
381 portEXIT_CRITICAL(&this->taken_lock_);
382 if (report || tail) {
383 // The listeners can block, so loop() calls them; the frames and their finish time travel together, so the delay
384 // does not change what they compute.
386 }
387}
388
390 portENTER_CRITICAL(&this->taken_lock_);
391 const uint32_t frames = this->report_frames_pending_;
392 const int64_t finish_us = this->report_finish_us_;
393 this->report_frames_pending_ = 0;
394 portEXIT_CRITICAL(&this->taken_lock_);
395 if (frames > 0) {
396 this->audio_output_callback_(frames, finish_us);
397 }
398}
399
401 // The take time is read before the clock, so a take that lands in between cannot make the difference negative.
402 const uint32_t taken_us = this->last_taken_us_;
403 return static_cast<uint32_t>(esp_timer_get_time()) - taken_us < this->in_flight_us_;
404}
405
407 // The driver still holds a whole transfer to take, or one it took has not finished playing. Less than a transfer
408 // stays in the ring buffer until the next write.
409 return this->state_ == speaker::STATE_RUNNING &&
410 (this->ring_bytes_ >= this->transfer_bytes_ || this->transfers_in_flight_());
411}
412
414
415// The hub's worker sends volume and mute to the device.
416void USBAudioSpeaker::set_volume(float volume) {
418 this->parent_->set_speaker_volume_level(volume);
419}
420
421void USBAudioSpeaker::set_mute_state(bool mute_state) {
423 this->parent_->set_speaker_mute_state(mute_state);
424}
425
426} // namespace esphome::usb_audio
427
428#endif
void enable_loop_soon_any_context()
Thread and ISR-safe version of enable_loop() that can be called from any context.
void enable_loop()
Enable this component's loop.
Definition component.h:261
void disable_loop()
Disable this component's loop.
size_t frames_to_bytes(uint32_t frames) const
Converts frames to bytes.
Definition audio.h:53
uint32_t bytes_to_frames(size_t bytes) const
Convert bytes to frames.
Definition audio.h:43
uint32_t get_sample_rate() const
Definition audio.h:30
virtual void set_volume(float volume)
Definition speaker.h:74
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
audio::AudioStreamInfo audio_stream_info_
Definition speaker.h:149
uint32_t next_transfer_bytes_(uint32_t &accum) const
void request_(uint8_t set, uint8_t clear)
void set_mute_state(bool mute_state) override
static constexpr uint8_t COMMAND_START
static constexpr uint8_t COMMAND_STOP
std::atomic< uint32_t > ring_padding_
size_t play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) override
void pad_with_silence_()
Write silence until a whole USB transfer is padded, so the driver sends a final partial transfer.
size_t play_internal_(const uint8_t *data, size_t length, uint32_t budget_ms)
static constexpr uint8_t COMMAND_FINISH
void set_volume(float volume) override
const audio::AudioStreamInfo usb_stream_info_
void on_stream_state(StreamEvent event) override
esp_err_t write_(const uint8_t *data, size_t length, uint32_t timeout_ms, bool padding)
Write to the driver, counting the bytes in ring_bytes_ (and in ring_padding_ for silence padding).
std::atomic< uint32_t > last_taken_us_
size_t ring_room_() const
Bytes that can be written without filling the driver's ring buffer past buffer_size_.
NameCopy * next
ESPHOME_LOG_TAG(TAG, "usb_audio.mic")
StreamEvent
What the hub reports to a platform about its stream.
Definition usb_audio.h:29
uint16_t size
Definition helpers.cpp:34
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
int written
Definition helpers.h:1340
int64_t esp_timer_get_time(void)
static void uint32_t
uint16_t length
Definition tt21100.cpp:0