ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
audio_pipeline.cpp
Go to the documentation of this file.
1#include "audio_pipeline.h"
2#include "playback_start.h"
3
4#ifdef USE_ESP32
5
7#include "esphome/core/hal.h"
9#include "esphome/core/log.h"
10
11namespace esphome::speaker {
12
13static const uint32_t INITIAL_BUFFER_MS = 1000; // Start playback after buffering this duration of the file
14
15static const uint32_t READ_TASK_STACK_SIZE = 5 * 1024;
16// Opus decoding uses more stack than other codecs
17#ifdef USE_AUDIO_OPUS_SUPPORT
18static const uint32_t DECODE_TASK_STACK_SIZE = 5 * 1024;
19#else
20static const uint32_t DECODE_TASK_STACK_SIZE = 3 * 1024;
21#endif
22
23static const uint32_t INFO_ERROR_QUEUE_COUNT = 5;
24
25ESPHOME_LOG_TAG(TAG, "speaker_media_player.pipeline");
26
28 // MESSAGE_* bits are only set by their respective tasks
29
30 // Stops all activity in the pipeline elements; cleared by process_state() and set by stop() or by each task
32
33 // Read audio from an HTTP source; cleared by reader task and set by start_url
35 // Read audio from an audio file from the flash; cleared by reader task and set by start_file
37
38 // Audio file type is read after checking it is supported; cleared by decoder task
40 // Reader is done (either through a failure or just end of the stream); cleared by reader task
42 // Error reading the file; cleared by process_state()
44
45 // Decoder is done (either through a faiilure or the end of the stream); cleared by decoder task
47 // Error decoding the file; cleared by process_state() by decoder task
49};
50
51AudioPipeline::AudioPipeline(speaker::Speaker *speaker, size_t buffer_size, bool task_stack_in_psram,
52 const char *base_name, UBaseType_t priority)
53 : base_name_(base_name),
54 priority_(priority),
55 task_stack_in_psram_(task_stack_in_psram),
56 speaker_(speaker),
57 buffer_size_(buffer_size) {
59 this->transfer_buffer_size_ = std::min(buffer_size_ / 4, DEFAULT_TRANSFER_BUFFER_SIZE);
60}
61
62void AudioPipeline::start_url(const std::string &uri, bool is_announcement) {
63 if (this->is_playing_) {
64 xEventGroupSetBits(this->event_group_, PIPELINE_COMMAND_STOP);
65 }
66 this->current_uri_ = uri;
67 this->pending_is_announcement_ = is_announcement;
68 this->pending_url_ = true;
69}
70
71void AudioPipeline::start_file(const audio::AudioFile *audio_file, bool is_announcement) {
72 if (this->is_playing_) {
73 xEventGroupSetBits(this->event_group_, PIPELINE_COMMAND_STOP);
74 }
75 this->current_audio_file_ = audio_file;
76 this->pending_is_announcement_ = is_announcement;
77 this->pending_file_ = true;
78}
79
81 xEventGroupSetBits(this->event_group_, EventGroupBits::PIPELINE_COMMAND_STOP);
82
83 return ESP_OK;
84}
85void AudioPipeline::set_pause_state(bool pause_state) {
86 this->speaker_->set_pause_state(pause_state);
87
88 this->pause_state_ = pause_state;
89}
90
92 if (this->read_task_.is_created()) {
93 vTaskSuspend(this->read_task_.get_handle());
94 }
95 if (this->decode_task_.is_created()) {
96 vTaskSuspend(this->decode_task_.get_handle());
97 }
98}
99
101 if (this->read_task_.is_created()) {
102 vTaskResume(this->read_task_.get_handle());
103 }
104 if (this->decode_task_.is_created()) {
105 vTaskResume(this->decode_task_.get_handle());
106 }
107}
108
110 /*
111 * Log items from info error queue
112 */
113 InfoErrorEvent event;
114 if (this->info_error_queue_ != nullptr) {
115 while (xQueueReceive(this->info_error_queue_, &event, 0)) {
116 switch (event.source) {
118 if (event.err.has_value()) {
119 ESP_LOGE(TAG, "Media reader encountered an error: %s", esp_err_to_name(event.err.value()));
120 } else if (event.file_type.has_value()) {
121 ESP_LOGD(TAG, "Reading %s file type", audio_file_type_to_string(event.file_type.value()));
122 }
123
124 break;
126 if (event.err.has_value()) {
127 ESP_LOGE(TAG, "Decoder encountered an error: %s", esp_err_to_name(event.err.value()));
128 }
129
130 if (event.audio_stream_info.has_value()) {
131 ESP_LOGD(TAG, "Decoded audio has %d channels, %" PRId32 " Hz sample rate, and %d bits per sample",
132 event.audio_stream_info.value().get_channels(), event.audio_stream_info.value().get_sample_rate(),
133 event.audio_stream_info.value().get_bits_per_sample());
134 }
135
136 if (event.decoding_err.has_value()) {
137 switch (event.decoding_err.value()) {
139 ESP_LOGE(TAG, "Failed to parse the file's header.");
140 break;
142 ESP_LOGE(TAG, "Incompatible bits per sample. Only 16 bits per sample is supported");
143 break;
145 ESP_LOGE(TAG, "Incompatible number of channels. Only 1 or 2 channel audio is supported.");
146 break;
147 }
148 }
149 break;
150 }
151 }
152 }
153
154 /*
155 * Determine the current state based on the event group bits and tasks' status
156 */
157
158 EventBits_t event_bits = xEventGroupGetBits(this->event_group_);
159
160 if (this->pending_url_ || this->pending_file_) {
161 // Init command pending
162 if (!(event_bits & EventGroupBits::PIPELINE_COMMAND_STOP)) {
163 // Only start if there is no pending stop command
164 if (!this->read_task_.is_created() || !this->decode_task_.is_created()) {
165 // At least one task isn't running
166 this->start_tasks_();
167 }
168
170 if (this->pending_url_) {
172 this->playback_ms_ = 0;
173 this->pending_url_ = false;
174 } else if (this->pending_file_) {
176 this->playback_ms_ = 0;
177 this->pending_file_ = false;
178 }
179
180 this->is_playing_ = true;
182 }
183 }
184
185 if ((event_bits & EventGroupBits::READER_MESSAGE_ERROR)) {
186 xEventGroupClearBits(this->event_group_, EventGroupBits::READER_MESSAGE_ERROR);
188 }
189
190 if ((event_bits & EventGroupBits::DECODER_MESSAGE_ERROR)) {
191 xEventGroupClearBits(this->event_group_, EventGroupBits::DECODER_MESSAGE_ERROR);
193 }
194
195 if ((event_bits & EventGroupBits::READER_MESSAGE_FINISHED) &&
198 // Tasks are finished and there's no media in between the reader and decoder
199
200 if (event_bits & EventGroupBits::PIPELINE_COMMAND_STOP) {
201 // Stop command is fully processed, so clear the command bit
202 xEventGroupClearBits(this->event_group_, EventGroupBits::PIPELINE_COMMAND_STOP);
203 this->hard_stop_ = true;
204 }
205
206 if (!this->is_playing_) {
207 // The tasks have been stopped for two ``process_state`` calls in a row, so delete the tasks
208 if (this->read_task_.is_created() || this->decode_task_.is_created()) {
209 // Both are attempted every time; a task that is still running on the other core is freed by a
210 // subsequent call, and freeing an already freed task succeeds without doing anything
211 bool read_task_freed = this->read_task_.deallocate();
212 bool decode_task_freed = this->decode_task_.deallocate();
213 if (!read_task_freed || !decode_task_freed) {
214 // A task is still running on the other core, so keep the pipeline in its current state and try
215 // again on the next call
217 }
218 if (this->hard_stop_) {
219 // Stop command was sent, so immediately end the playback
220 this->speaker_->stop();
221 this->hard_stop_ = false;
222 } else {
223 // Decoded all the audio, so let the speaker finish playing before stopping
224 this->speaker_->finish();
225 }
226 }
227 }
228 this->is_playing_ = false;
229 if (!this->speaker_->is_running()) {
231 } else {
232 this->is_finishing_ = true;
233 }
234 }
235
236 if (this->pause_state_) {
238 }
239
240 if (this->is_finishing_) {
241 if (!this->speaker_->is_running()) {
242 this->is_finishing_ = false;
243 } else {
245 }
246 }
247
248 if (!this->read_task_.is_created() && !this->decode_task_.is_created()) {
249 // No tasks are running, so the pipeline is stopped.
250 xEventGroupClearBits(this->event_group_, EventGroupBits::PIPELINE_COMMAND_STOP);
252 }
253
254 this->is_playing_ = true;
256}
257
259 if (this->event_group_ == nullptr)
260 this->event_group_ = xEventGroupCreate();
261
262 if (this->event_group_ == nullptr) {
263 return ESP_ERR_NO_MEM;
264 }
265
266 if (this->info_error_queue_ == nullptr)
267 this->info_error_queue_ = xQueueCreate(INFO_ERROR_QUEUE_COUNT, sizeof(InfoErrorEvent));
268
269 if (this->info_error_queue_ == nullptr)
270 return ESP_ERR_NO_MEM;
271
272 return ESP_OK;
273}
274
276 char task_name[configMAX_TASK_NAME_LEN];
277 if (!this->read_task_.is_created()) {
278 // Reader task uses the AudioReader class which uses esp_http_client. This crashes on IDF 5.4 if the task stack is
279 // in PSRAM. As a workaround, always allocate the read task in internal memory.
280 snprintf(task_name, sizeof(task_name), "%s_read", this->base_name_);
281 if (!this->read_task_.create(read_task, task_name, READ_TASK_STACK_SIZE, (void *) this, this->priority_, false)) {
282 return ESP_ERR_NO_MEM;
283 }
284 }
285
286 if (!this->decode_task_.is_created()) {
287 snprintf(task_name, sizeof(task_name), "%s_decode", this->base_name_);
288 if (!this->decode_task_.create(decode_task, task_name, DECODE_TASK_STACK_SIZE, (void *) this, this->priority_,
289 this->task_stack_in_psram_)) {
290 return ESP_ERR_NO_MEM;
291 }
292 }
293
294 return ESP_OK;
295}
296
297void AudioPipeline::read_task(void *params) {
298 AudioPipeline *this_pipeline = (AudioPipeline *) params;
299
300 while (true) {
301 xEventGroupSetBits(this_pipeline->event_group_, EventGroupBits::READER_MESSAGE_FINISHED);
302
303 // Wait until the pipeline notifies us the source of the media file
304 EventBits_t event_bits = xEventGroupWaitBits(
305 this_pipeline->event_group_,
307 pdFALSE, // Clear the bit on exit
308 pdFALSE, // Wait for all the bits,
309 portMAX_DELAY); // Block indefinitely until bit is set
310
311 if (!(event_bits & EventGroupBits::PIPELINE_COMMAND_STOP)) {
312 xEventGroupClearBits(this_pipeline->event_group_, EventGroupBits::READER_MESSAGE_FINISHED |
315 InfoErrorEvent event;
317 esp_err_t err = ESP_OK;
318
319 std::unique_ptr<audio::AudioReader> reader =
320 make_unique<audio::AudioReader>(this_pipeline->transfer_buffer_size_);
321
323 err = reader->start(this_pipeline->current_audio_file_, this_pipeline->current_audio_file_type_);
324 } else {
325 err = reader->start(this_pipeline->current_uri_, this_pipeline->current_audio_file_type_);
326 }
327
328 if (err == ESP_OK) {
329 size_t file_ring_buffer_size = this_pipeline->buffer_size_;
330
331 std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this_pipeline->raw_file_ring_buffer_.lock();
332
333 if (temp_ring_buffer == nullptr) {
334 temp_ring_buffer = ring_buffer::RingBuffer::create(file_ring_buffer_size);
335 this_pipeline->raw_file_ring_buffer_ = temp_ring_buffer;
336 }
337
338 if (temp_ring_buffer == nullptr) {
339 err = ESP_ERR_NO_MEM;
340 } else {
341 err = reader->add_sink(temp_ring_buffer);
342 }
343 }
344
345 if (err != ESP_OK) {
346 // Send specific error message
347 event.err = err;
348 xQueueSend(this_pipeline->info_error_queue_, &event, portMAX_DELAY);
349
350 // Setting up the reader failed, stop the pipeline
351 xEventGroupSetBits(this_pipeline->event_group_,
353 } else {
354 // Send the file type to the pipeline
355 event.file_type = this_pipeline->current_audio_file_type_;
356 xQueueSend(this_pipeline->info_error_queue_, &event, portMAX_DELAY);
357 xEventGroupSetBits(this_pipeline->event_group_, EventGroupBits::READER_MESSAGE_LOADED_MEDIA_TYPE);
358 }
359
360 while (true) {
361 event_bits = xEventGroupGetBits(this_pipeline->event_group_);
362
363 if (event_bits & EventGroupBits::PIPELINE_COMMAND_STOP) {
364 break;
365 }
366
367 audio::AudioReaderState reader_state = reader->read();
368
369 if (reader_state == audio::AudioReaderState::FINISHED) {
370 break;
371 } else if (reader_state == audio::AudioReaderState::FAILED) {
372 xEventGroupSetBits(this_pipeline->event_group_,
374 break;
375 }
376 }
377 event_bits = xEventGroupGetBits(this_pipeline->event_group_);
379 (this_pipeline->raw_file_ring_buffer_.use_count() == 1)) {
380 // Decoder task hasn't started yet, so delay a bit before releasing ownership of the ring buffer
381 delay(10);
382 }
383 }
384 }
385}
386
387void AudioPipeline::decode_task(void *params) {
388 AudioPipeline *this_pipeline = (AudioPipeline *) params;
389
390 while (true) {
391 xEventGroupSetBits(this_pipeline->event_group_, EventGroupBits::DECODER_MESSAGE_FINISHED);
392
393 // Wait until the reader notifies us that the media type is available
394 EventBits_t event_bits =
395 xEventGroupWaitBits(this_pipeline->event_group_,
397 pdFALSE, // Clear the bit on exit
398 pdFALSE, // Wait for all the bits,
399 portMAX_DELAY); // Block indefinitely until bit is set
400
401 xEventGroupClearBits(this_pipeline->event_group_,
403
404 if (!(event_bits & EventGroupBits::PIPELINE_COMMAND_STOP)) {
405 const bool is_announcement = this_pipeline->current_is_announcement_;
406 InfoErrorEvent event;
408
409 std::unique_ptr<audio::AudioDecoder> decoder =
410 make_unique<audio::AudioDecoder>(this_pipeline->transfer_buffer_size_, this_pipeline->transfer_buffer_size_);
411
412 esp_err_t err = decoder->start(this_pipeline->current_audio_file_type_);
413 if (err == ESP_OK) {
414 err = decoder->add_source(this_pipeline->raw_file_ring_buffer_);
415 }
416
417 if (err != ESP_OK) {
418 // Send specific error message
419 event.err = err;
420 xQueueSend(this_pipeline->info_error_queue_, &event, portMAX_DELAY);
421
422 // Setting up the decoder failed, stop the pipeline
423 xEventGroupSetBits(this_pipeline->event_group_,
425 }
426
427 bool has_stream_info = false;
428 bool started_playback = false;
429 PlaybackStartGate start_gate;
430
431 size_t initial_bytes_to_buffer = 0;
432
433 while (true) {
434 event_bits = xEventGroupGetBits(this_pipeline->event_group_);
435
436 if (event_bits & EventGroupBits::PIPELINE_COMMAND_STOP) {
437 break;
438 }
439
440 // Update pause state
441 if (!started_playback) {
442 if (!(event_bits & EventGroupBits::READER_MESSAGE_FINISHED)) {
443 decoder->set_pause_output_state(true);
444 } else {
445 started_playback = true;
446 }
447 } else {
448 decoder->set_pause_output_state(this_pipeline->pause_state_);
449 }
450
451 // Stop gracefully if the reader has finished
452 audio::AudioDecoderState decoder_state = decoder->decode(event_bits & EventGroupBits::READER_MESSAGE_FINISHED);
453
454 if ((decoder_state == audio::AudioDecoderState::DECODING) ||
455 (decoder_state == audio::AudioDecoderState::FINISHED)) {
456 this_pipeline->playback_ms_ = decoder->get_playback_ms();
457 }
458
459 if (decoder_state == audio::AudioDecoderState::FINISHED) {
460 break;
461 } else if (decoder_state == audio::AudioDecoderState::FAILED) {
462 if (!has_stream_info) {
463 event.decoding_err = DecodingError::FAILED_HEADER;
464 xQueueSend(this_pipeline->info_error_queue_, &event, portMAX_DELAY);
465 }
466 xEventGroupSetBits(this_pipeline->event_group_,
468 break;
469 }
470
471 if (!has_stream_info && decoder->get_audio_stream_info().has_value()) {
472 has_stream_info = true;
473
474 this_pipeline->current_audio_stream_info_ = decoder->get_audio_stream_info().value();
475
476 // Send the stream information to the pipeline
477 event.audio_stream_info = this_pipeline->current_audio_stream_info_;
478
479 if (this_pipeline->current_audio_stream_info_.get_bits_per_sample() != 16) {
480 // Error state, incompatible bits per sample
482 xEventGroupSetBits(this_pipeline->event_group_,
484 } else if ((this_pipeline->current_audio_stream_info_.get_channels() > 2)) {
485 // Error state, incompatible number of channels
486 event.decoding_err = DecodingError::INCOMPATIBLE_CHANNELS;
487 xEventGroupSetBits(this_pipeline->event_group_,
489 } else {
490 // Send audio directly to the speaker
491 this_pipeline->speaker_->set_audio_stream_info(this_pipeline->current_audio_stream_info_);
492 decoder->add_sink(this_pipeline->speaker_);
493 }
494
495 initial_bytes_to_buffer = std::min(this_pipeline->current_audio_stream_info_.ms_to_bytes(INITIAL_BUFFER_MS),
496 this_pipeline->buffer_size_ * 3 / 4);
497
498 switch (this_pipeline->current_audio_file_type_) {
499#ifdef USE_AUDIO_MP3_SUPPORT
501 initial_bytes_to_buffer /= 8; // Estimate the MP3 compression factor is 8
502 break;
503#endif
504#ifdef USE_AUDIO_FLAC_SUPPORT
506 initial_bytes_to_buffer /= 2; // Estimate the FLAC compression factor is 2
507 break;
508#endif
509#ifdef USE_AUDIO_OPUS_SUPPORT
511 initial_bytes_to_buffer /= 8; // Estimate the Opus compression factor is 8
512 break;
513#endif
514 default:
515 break;
516 }
517 xQueueSend(this_pipeline->info_error_queue_, &event, portMAX_DELAY);
518 }
519
520 if (!started_playback && has_stream_info) {
521 // Verify enough data is available before starting playback
522 std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this_pipeline->raw_file_ring_buffer_.lock();
523 if (temp_ring_buffer != nullptr &&
524 start_gate.ready(is_announcement, temp_ring_buffer->available(), initial_bytes_to_buffer, millis())) {
525 started_playback = true;
526 }
527 }
528 }
529 }
530 }
531}
532
533} // namespace esphome::speaker
534
535#endif
bool is_created() const
Check if the task has been created and not yet destroyed.
Definition static_task.h:28
TaskHandle_t get_handle() const
Get the FreeRTOS task handle.
Definition static_task.h:31
bool deallocate()
Delete the task (if created) and free the TCB and stack buffer.
bool create(TaskFunction_t fn, const char *name, uint32_t stack_size, void *param, UBaseType_t priority, bool use_psram, BaseType_t core_id=tskNO_AFFINITY)
Allocate the TCB (always internal RAM) and the stack, then create the task.
size_t ms_to_bytes(uint32_t ms) const
Converts duration to bytes.
Definition audio.h:75
uint8_t get_bits_per_sample() const
Definition audio.h:28
uint8_t get_channels() const
Definition audio.h:29
static std::unique_ptr< RingBuffer > create(size_t len, MemoryPreference preference=MemoryPreference::EXTERNAL_FIRST)
const audio::AudioFile * current_audio_file_
static void read_task(void *params)
void suspend_tasks()
Suspends any running tasks.
void start_file(const audio::AudioFile *audio_file, bool is_announcement=false)
Starts an audio pipeline given a AudioFile pointer.
void set_pause_state(bool pause_state)
esp_err_t allocate_communications_()
Allocates the event group and info error queue.
esp_err_t start_tasks_()
Common start code for the pipeline, regardless if the source is a file or url.
audio::AudioStreamInfo current_audio_stream_info_
esp_err_t stop()
Stops the pipeline.
AudioPipeline(speaker::Speaker *speaker, size_t buffer_size, bool task_stack_in_psram, const char *base_name, UBaseType_t priority)
void start_url(const std::string &uri, bool is_announcement=false)
Starts an audio pipeline given a media url.
static void decode_task(void *params)
void resume_tasks()
Resumes any running tasks.
audio::AudioFileType current_audio_file_type_
std::weak_ptr< ring_buffer::RingBuffer > raw_file_ring_buffer_
AudioPipelineState process_state()
Processes the state of the audio pipeline based on the info_error_queue_ and event_group_.
Decides when buffered audio starts playing.
bool ready(bool announcement, size_t raw_bytes, size_t initial_bytes, uint32_t now_ms)
bool is_running() const
Definition speaker.h:68
virtual void set_pause_state(bool pause_state)
Definition speaker.h:63
void set_audio_stream_info(const audio::AudioStreamInfo &audio_stream_info)
Definition speaker.h:104
virtual void finish()
Definition speaker.h:60
virtual void stop()=0
uint8_t priority
ESPHOME_LOG_TAG(TAG, "announcement_volume")
void HOT delay(uint32_t ms)
Definition hal.cpp:85
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
static void uint32_t
optional< DecodingError > decoding_err
optional< audio::AudioFileType > file_type
optional< audio::AudioStreamInfo > audio_stream_info