ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
speaker_source_media_player.h
Go to the documentation of this file.
1#pragma once
2
4
5#ifdef USE_ESP32
6
12
16
17#include <array>
18#include <atomic>
19#include <memory>
20#include <vector>
21#include <freertos/FreeRTOS.h>
22#include <freertos/queue.h>
23
25
26// THREADING MODEL:
27// This component coordinates media sources that run their own decode tasks with speakers
28// that have their own playback callback tasks. Three thread contexts exist:
29//
30// - Main loop task: setup(), loop(), dump_config(), handle_media_state_changed_(),
31// handle_volume_request_(), handle_mute_request_(), handle_play_uri_request_(),
32// set_volume_(), apply_speaker_volume_(), set_announcement_volume(), is_media_playing_(), set_mute_state_(),
33// control(), get_source_state_(),
34// find_source_for_uri_(), try_execute_play_uri_(), save_volume_restore_state_(),
35// process_control_queue_(), handle_player_command_(), queue_command_(), queue_play_current_()
36//
37// - Media source task(s): handle_media_output_() via SourceBinding::write_audio().
38// Called from each source's decode task thread when streaming audio data.
39// Reads ps.active_source (atomic), writes ps.pending_frames (atomic), and calls
40// ps.speaker methods (speaker pointer is immutable after setup).
41//
42// - Speaker callback task: handle_speaker_playback_callback_() via speaker's
43// add_audio_output_callback(). Called when the speaker finishes writing frames to the DAC.
44// Reads ps.active_source (atomic), writes ps.pending_frames (atomic), and calls
45// active_source->notify_audio_played().
46//
47// control() is only called from the main loop (HA/automation commands).
48// Source tasks use defer() for all requests (volume, mute, play_uri).
49//
50// Thread-safe communication:
51// - FreeRTOS queue (media_control_command_queue_): control() -> loop() for play/command dispatch
52// - defer(): SourceBinding::request_volume/request_mute/request_play_uri -> main loop
53// - Atomic fields (active_source, pending_frames): shared between all three thread contexts
54//
55// Non-atomic pipeline fields (last_source, stopping_source, pending_source, playlist,
56// playlist_index, repeat_mode) are only accessed from the main loop thread.
57
58enum Pipeline : uint8_t {
61};
62
63enum RepeatMode : uint8_t {
67};
68
69// Forward declaration
70class SpeakerSourceMediaPlayer;
71
80 uint8_t pipeline;
81
82 // Implementations are in the .cpp file because SpeakerSourceMediaPlayer is only forward-declared here
83 size_t write_audio(const uint8_t *data, size_t length, uint32_t timeout_ms,
84 const audio::AudioStreamInfo &stream_info) override;
86 void request_volume(float volume) override;
87 void request_mute(bool is_muted) override;
88 void request_play_uri(const std::string &uri) override;
89};
90
92static constexpr uint32_t PIPELINE_TIMEOUT_IDS[] = {1, 2};
93
96 optional<media_player::MediaPlayerSupportedFormat> format;
97
98 std::atomic<media_source::MediaSource *> active_source{nullptr};
100 media_source::MediaSource *stopping_source{nullptr}; // Source we've asked to stop, awaiting IDLE
101 media_source::MediaSource *pending_source{nullptr}; // Source we've asked to play, awaiting PLAYING
102
103 // Each SourceBinding pairs a MediaSource* with its listener implementation.
104 // Uses unique_ptr so binding addresses are stable and set_listener() can be called in add_media_source().
105 // Uses std::vector because the count varies across instances (multiple speaker_source media players may exist).
106 std::vector<std::unique_ptr<SourceBinding>> sources;
107
108 // Dynamic allocation is unavoidable here: URIs from Home Assistant are arbitrary-length strings
109 // (media URLs with tokens can easily exceed 500 bytes), and playlist size is unbounded.
110 // Pre-allocating fixed buffers would waste significant RAM when idle without covering worst cases.
111 std::vector<std::string> playlist;
112 size_t playlist_index{0};
115
116 // When non-empty, playlist_index indexes into these vectors
117 // which contain the actual playlist indices in shuffled order
118 std::vector<size_t> shuffle_indices;
119
120 // Track frames sent to speaker to correlate with playback callbacks.
121 // Atomic because it is written from the main loop/source tasks and read/decremented from the speaker playback
122 // callback.
123 std::atomic<uint32_t> pending_frames{0};
124
126 bool is_configured() const { return this->speaker != nullptr; }
127};
128
130 enum Type : uint8_t {
131 PLAY_URI, // Clear playlist, reset index, add URI, queue PLAY_CURRENT
132 ENQUEUE_URI, // Add URI to playlist, queue PLAY_CURRENT if idle
133 PLAYLIST_ADVANCE, // Advance index (or wrap for repeat_all), queue PLAY_CURRENT if more items
134 PLAY_CURRENT, // Play item at current playlist index (can retry if speaker not ready)
135 SEND_COMMAND, // Send command to active source
136 };
138 uint8_t pipeline; // MEDIA_PIPELINE or ANNOUNCEMENT_PIPELINE
139
140 union {
141 std::string *uri; // Owned pointer, must delete after xQueueReceive (for PLAY_URI and ENQUEUE_URI)
144};
145
147 float volume;
149};
150
152 friend struct SourceBinding;
153
154 public:
156 void setup() override;
157 void loop() override;
158 void dump_config() override;
159
160 // MediaPlayer implementations
162 bool is_muted() const override { return this->is_muted_; }
163
164 // Percentage to increase or decrease the volume for volume up or volume down commands
165 void set_volume_increment(float volume_increment) { this->volume_increment_ = volume_increment; }
166
167 // Volume used initially on first boot when no volume had been previously saved
168 void set_volume_initial(float volume_initial) { this->volume_initial_ = volume_initial; }
169
170 void set_volume_max(float volume_max) { this->volume_max_ = volume_max; }
171 void set_volume_min(float volume_min) { this->volume_min_ = volume_min; }
172
174 void set_announcement_volume(float announcement_volume);
175
177 void add_media_source(uint8_t pipeline, media_source::MediaSource *media_source);
178
179 void set_speaker(uint8_t pipeline, speaker::Speaker *speaker) { this->pipelines_[pipeline].speaker = speaker; }
181 this->pipelines_[pipeline].format = format;
182 }
183
187
188 void set_playlist_delay_ms(uint8_t pipeline, uint32_t delay_ms);
189
190 protected:
191 // Callbacks from source bindings (pipeline index is captured at binding creation time)
192 size_t handle_media_output_(uint8_t pipeline, media_source::MediaSource *source, const uint8_t *data, size_t length,
193 uint32_t timeout_ms, const audio::AudioStreamInfo &stream_info);
194 void handle_media_state_changed_(uint8_t pipeline, media_source::MediaSource *source,
196 void handle_volume_request_(float volume);
198 void handle_play_uri_request_(uint8_t pipeline, const std::string &uri);
199
200 void handle_speaker_playback_callback_(uint32_t frames, int64_t timestamp, uint8_t pipeline);
201
202 // Receives commands from HA or from the voice assistant component
203 // Sends commands to the media_control_command_queue_
204 void control(const media_player::MediaPlayerCall &call) override;
205
207 void set_volume_(float volume, bool publish = true);
208
210 void apply_speaker_volume_(float volume);
211
214 return [this](float volume) { this->apply_speaker_volume_(volume); };
215 }
216
218 bool is_media_playing_() const;
219
223 void set_mute_state_(bool mute_state, bool publish = true);
224
227
234 media_player::MediaPlayerState old_state) const;
235
237 void handle_player_command_(media_player::MediaPlayerCommand player_command, uint8_t pipeline);
238 bool try_execute_play_uri_(const std::string &uri, uint8_t pipeline);
239 media_source::MediaSource *find_source_for_uri_(const std::string &uri, uint8_t pipeline);
241 void queue_play_current_(uint8_t pipeline, uint32_t delay_ms = 0);
242
244 size_t get_playlist_position_(uint8_t pipeline) const;
245
247 void shuffle_playlist_(uint8_t pipeline);
248
250 void unshuffle_playlist_(uint8_t pipeline);
251
253
254 // Pipeline context for media (index 0) and announcement (index 1) pipelines.
255 // See THREADING MODEL at top of namespace for access rules.
256 std::array<PipelineContext, 2> pipelines_;
257
258 // Used to save volume/mute state for restoration on reboot
260
264
265 // The amount to change the volume on volume up/down commands
267
268 // The initial volume used by Setup when no previous volume was saved
270
273
275
276 bool is_muted_{false};
277};
278
279} // namespace esphome::speaker_source
280
281#endif // USE_ESP32
Abstract base class for media sources MediaSource provides audio data to an orchestrator via the Medi...
Callbacks from a MediaSource to its orchestrator.
Tracks a separate volume for announcements that start while nothing else is playing.
void shuffle_playlist_(uint8_t pipeline)
Generates shuffled indices for the playlist, keeping current track at current position.
void apply_speaker_volume_(float volume)
Remaps a volume to the configured limits and sends it to the speakers.
void set_playlist_delay_ms(uint8_t pipeline, uint32_t delay_ms)
void queue_play_current_(uint8_t pipeline, uint32_t delay_ms=0)
void set_mute_state_(bool mute_state, bool publish=true)
Sets the mute state.
void set_speaker(uint8_t pipeline, speaker::Speaker *speaker)
void queue_command_(MediaPlayerControlCommand::Type type, uint8_t pipeline)
media_source::MediaSource * find_source_for_uri_(const std::string &uri, uint8_t pipeline)
void unshuffle_playlist_(uint8_t pipeline)
Clears shuffle indices and adjusts playlist_index to maintain current track.
media_player::MediaPlayerState get_source_state_(media_source::MediaSource *media_source, bool playlist_active, media_player::MediaPlayerState old_state) const
Determine media player state from a pipeline's active source.
void handle_play_uri_request_(uint8_t pipeline, const std::string &uri)
void control(const media_player::MediaPlayerCall &call) override
void handle_player_command_(media_player::MediaPlayerCommand player_command, uint8_t pipeline)
size_t get_playlist_position_(uint8_t pipeline) const
Maps playlist_index through shuffle indices if shuffle is active.
void add_media_source(uint8_t pipeline, media_source::MediaSource *media_source)
Adds a media source to a pipeline and registers this player as its listener.
auto speaker_volume_applier_()
Returns a callable that sends a volume to the speakers, for announcement_volume_ to apply its changes...
void set_format(uint8_t pipeline, const media_player::MediaPlayerSupportedFormat &format)
bool is_media_playing_() const
Whether media is audible: the active source plays, or the speaker plays what an idle source left.
bool try_execute_play_uri_(const std::string &uri, uint8_t pipeline)
void set_volume_(float volume, bool publish=true)
Updates this->volume and saves volume/mute state to flash for restoration if publish is true.
void handle_media_state_changed_(uint8_t pipeline, media_source::MediaSource *source, media_source::MediaSourceState state)
media_player::MediaPlayerTraits get_traits() override
void handle_speaker_playback_callback_(uint32_t frames, int64_t timestamp, uint8_t pipeline)
void set_announcement_volume(float announcement_volume)
Sets the volume for announcements that start while nothing else is playing.
void save_volume_restore_state_()
Saves the current volume and mute state to the flash for restoration.
size_t handle_media_output_(uint8_t pipeline, media_source::MediaSource *source, const uint8_t *data, size_t length, uint32_t timeout_ms, const audio::AudioStreamInfo &stream_info)
uint8_t type
bool state
Definition fan.h:2
const char * format
constexpr float PROCESSOR
For components that use data from sensors like displays.
Definition component.h:47
static void uint32_t
union esphome::speaker_source::MediaPlayerControlCommand::@180 data
optional< media_player::MediaPlayerSupportedFormat > format
bool is_configured() const
Check if this pipeline is configured (has a speaker assigned)
std::vector< std::unique_ptr< SourceBinding > > sources
std::atomic< media_source::MediaSource * > active_source
Per-source listener binding that captures the source pointer at registration time.
void request_play_uri(const std::string &uri) override
SourceBinding(SpeakerSourceMediaPlayer *player, media_source::MediaSource *source, uint8_t pipeline)
void report_state(media_source::MediaSourceState state) override
size_t write_audio(const uint8_t *data, size_t length, uint32_t timeout_ms, const audio::AudioStreamInfo &stream_info) override
uint16_t length
Definition tt21100.cpp:0
uint16_t timestamp
Definition tt21100.cpp:2