esphome 2024.12.3__py3-none-any.whl → 2025.2.0b1__py3-none-any.whl

esphome/components/speaker/media_player/audio_pipeline.h

@@ -0,0 +1,159 @@
+#pragma once
+
+#ifdef USE_ESP_IDF
+
+#include "esphome/components/audio/audio.h"
+#include "esphome/components/audio/audio_reader.h"
+#include "esphome/components/audio/audio_decoder.h"
+#include "esphome/components/speaker/speaker.h"
+
+#include "esphome/core/ring_buffer.h"
+
+#include "esp_err.h"
+
+#include <freertos/FreeRTOS.h>
+#include <freertos/event_groups.h>
+#include <freertos/queue.h>
+
+namespace esphome {
+namespace speaker {
+
+// Internal sink/source buffers for reader and decoder
+static const size_t DEFAULT_TRANSFER_BUFFER_SIZE = 24 * 1024;
+
+enum class AudioPipelineType : uint8_t {
+  MEDIA,
+  ANNOUNCEMENT,
+};
+
+enum class AudioPipelineState : uint8_t {
+  STARTING_FILE,
+  STARTING_URL,
+  PLAYING,
+  STOPPING,
+  STOPPED,
+  PAUSED,
+  ERROR_READING,
+  ERROR_DECODING,
+};
+
+enum class InfoErrorSource : uint8_t {
+  READER = 0,
+  DECODER,
+};
+
+enum class DecodingError : uint8_t {
+  FAILED_HEADER = 0,
+  INCOMPATIBLE_BITS_PER_SAMPLE,
+  INCOMPATIBLE_CHANNELS,
+};
+
+// Used to pass information from each task.
+struct InfoErrorEvent {
+  InfoErrorSource source;
+  optional<esp_err_t> err;
+  optional<audio::AudioFileType> file_type;
+  optional<audio::AudioStreamInfo> audio_stream_info;
+  optional<DecodingError> decoding_err;
+};
+
+class AudioPipeline {
+ public:
+  /// @param speaker ESPHome speaker component for pipeline's audio output
+  /// @param buffer_size Size of the buffer in bytes between the reader and decoder
+  /// @param task_stack_in_psram True if the task stack should be allocated in PSRAM, false otherwise
+  /// @param task_name FreeRTOS task base name
+  /// @param priority FreeRTOS task priority
+  AudioPipeline(speaker::Speaker *speaker, size_t buffer_size, bool task_stack_in_psram, std::string base_name,
+                UBaseType_t priority);
+
+  /// @brief Starts an audio pipeline given a media url
+  /// @param uri media file url
+  /// @return ESP_OK if successful or an appropriate error if not
+  void start_url(const std::string &uri);
+
+  /// @brief Starts an audio pipeline given a AudioFile pointer
+  /// @param audio_file pointer to an AudioFile object
+  /// @return ESP_OK if successful or an appropriate error if not
+  void start_file(audio::AudioFile *audio_file);
+
+  /// @brief Stops the pipeline. Sends a stop signal to each task (if running) and clears the ring buffers.
+  /// @return ESP_OK if successful or ESP_ERR_TIMEOUT if the tasks did not indicate they stopped
+  esp_err_t stop();
+
+  /// @brief Processes the state of the audio pipeline based on the info_error_queue_ and event_group_. Handles creating
+  /// and stopping the pipeline tasks. Needs to be regularly called to update the internal pipeline state.
+  /// @return AudioPipelineState
+  AudioPipelineState process_state();
+
+  /// @brief Suspends any running tasks
+  void suspend_tasks();
+  /// @brief Resumes any running tasks
+  void resume_tasks();
+
+  uint32_t get_playback_ms() { return this->playback_ms_; }
+
+  void set_pause_state(bool pause_state);
+
+ protected:
+  /// @brief Allocates the event group and info error queue.
+  /// @return ESP_OK if successful or ESP_ERR_NO_MEM if it is unable to allocate all parts
+  esp_err_t allocate_communications_();
+
+  /// @brief Common start code for the pipeline, regardless if the source is a file or url.
+  /// @return ESP_OK if successful or an appropriate error if not
+  esp_err_t start_tasks_();
+
+  /// @brief Resets the task related pointers and deallocates their stacks.
+  void delete_tasks_();
+
+  std::string base_name_;
+  UBaseType_t priority_;
+
+  uint32_t playback_ms_{0};
+
+  bool hard_stop_{false};
+  bool is_playing_{false};
+  bool pause_state_{false};
+  bool task_stack_in_psram_;
+
+  // Pending file start state used to ensure the pipeline fully stops before attempting to start the next file
+  bool pending_url_{false};
+  bool pending_file_{false};
+
+  speaker::Speaker *speaker_{nullptr};
+
+  std::string current_uri_{};
+  audio::AudioFile *current_audio_file_{nullptr};
+
+  audio::AudioFileType current_audio_file_type_;
+  audio::AudioStreamInfo current_audio_stream_info_;
+
+  size_t buffer_size_;           // Ring buffer between reader and decoder
+  size_t transfer_buffer_size_;  // Internal source/sink buffers for the audio reader and decoder
+
+  std::weak_ptr<RingBuffer> raw_file_ring_buffer_;
+
+  // Handles basic control/state of the three tasks
+  EventGroupHandle_t event_group_{nullptr};
+
+  // Receives detailed info (file type, stream info, resampling info) or specific errors from the three tasks
+  QueueHandle_t info_error_queue_{nullptr};
+
+  // Handles reading the media file from flash or a url
+  static void read_task(void *params);
+  TaskHandle_t read_task_handle_{nullptr};
+  StaticTask_t read_task_stack_;
+  StackType_t *read_task_stack_buffer_{nullptr};
+
+  // Decodes the media file into PCM audio
+  static void decode_task(void *params);
+  TaskHandle_t decode_task_handle_{nullptr};
+  StaticTask_t decode_task_stack_;
+  StackType_t *decode_task_stack_buffer_{nullptr};
+};
+
+}  // namespace speaker
+}  // namespace esphome
+
+#endif

esphome/components/speaker/media_player/automation.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "speaker_media_player.h"
+
+#ifdef USE_ESP_IDF
+
+#include "esphome/components/audio/audio.h"
+#include "esphome/core/automation.h"
+
+namespace esphome {
+namespace speaker {
+
+template<typename... Ts> class PlayOnDeviceMediaAction : public Action<Ts...>, public Parented<SpeakerMediaPlayer> {
+  TEMPLATABLE_VALUE(audio::AudioFile *, audio_file)
+  TEMPLATABLE_VALUE(bool, announcement)
+  TEMPLATABLE_VALUE(bool, enqueue)
+  void play(Ts... x) override {
+    this->parent_->play_file(this->audio_file_.value(x...), this->announcement_.value(x...),
+                             this->enqueue_.value(x...));
+  }
+};
+
+}  // namespace speaker
+}  // namespace esphome
+
+#endif