ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
speaker.h
Go to the documentation of this file.
1#pragma once
2
3#include <cstddef>
4#include <cstdint>
5#include <vector>
6
7#ifdef USE_ESP32
8#include <freertos/FreeRTOS.h>
9#endif
10
13
15#ifdef USE_AUDIO_DAC
17#endif
18
19namespace esphome::speaker {
20
22static constexpr float SILENT_VOLUME_THRESHOLD = 0.001f;
23
30
31class Speaker {
32 public:
33#ifdef USE_ESP32
40 virtual size_t play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) {
41 return this->play(data, length);
42 };
43#endif
44
51 virtual size_t play(const uint8_t *data, size_t length) = 0;
52
53 size_t play(const std::vector<uint8_t> &data) { return this->play(data.data(), data.size()); }
54
55 virtual void start() = 0;
56 virtual void stop() = 0;
57 // In compare between *STOP()* and *FINISH()*; *FINISH()* will stop after emptying the play buffer,
58 // while *STOP()* will break directly.
59 // When finish() is not implemented on the platform component it should just do a normal stop.
60 virtual void finish() { this->stop(); }
61
62 // Pauses processing incoming audio. Needs to be implemented specifically per speaker component
63 virtual void set_pause_state(bool pause_state) {}
64 virtual bool get_pause_state() const { return false; }
65
66 virtual bool has_buffered_data() const = 0;
67
68 bool is_running() const { return this->state_ == STATE_RUNNING; }
69 bool is_stopped() const { return this->state_ == STATE_STOPPED; }
70
71 // Volume and mute are independent: changing one never alters the other's stored state. Volume control is
72 // handled by the configured audio dac components, every one of them getting the same volume and mute. Individual
73 // speaker components can override and implement in software if an audio dac isn't available.
74 virtual void set_volume(float volume) {
75 this->volume_ = volume;
76#ifdef USE_AUDIO_DAC
77 for (auto *audio_dac : this->audio_dacs_) {
78 audio_dac->set_volume(volume);
79 }
81#endif
82 };
83 virtual float get_volume() { return this->volume_; }
84
85 virtual void set_mute_state(bool mute_state) {
86 this->mute_state_ = mute_state;
87#ifdef USE_AUDIO_DAC
89#endif
90 }
91 virtual bool get_mute_state() { return this->mute_state_; }
92
93#ifdef USE_AUDIO_DAC
96 this->audio_dacs_.assign_copy(&audio_dac, audio_dac != nullptr ? 1 : 0);
97 }
99 void set_audio_dacs(audio_dac::AudioDac *const *audio_dacs, size_t count) {
100 this->audio_dacs_.assign_static(audio_dacs, count);
101 }
102#endif
103
104 void set_audio_stream_info(const audio::AudioStreamInfo &audio_stream_info) {
105 this->audio_stream_info_ = audio_stream_info;
106 }
107
109
114 template<typename F> void add_audio_output_callback(F &&callback) {
115 this->audio_output_callback_.add(std::forward<F>(callback));
116 }
117
118 protected:
121 bool is_silent_() const { return this->mute_state_ || this->volume_ < SILENT_VOLUME_THRESHOLD; }
122
123#ifdef USE_AUDIO_DAC
125 bool has_audio_dac_() const { return !this->audio_dacs_.empty(); }
126
129 const bool silent = this->is_silent_();
130 for (auto *audio_dac : this->audio_dacs_) {
131 if (silent) {
132 audio_dac->set_mute_on();
133 } else {
134 audio_dac->set_mute_off();
135 }
136 }
137 }
138
141 for (auto *audio_dac : this->audio_dacs_) {
142 audio_dac->on_audio_started();
143 }
144 }
145#endif
146
148 bool mute_state_{false};
150 float volume_{1.0f};
151
152#ifdef USE_AUDIO_DAC
153 // all audio dacs fed by this speaker's audio output (eg two amplifiers on one I2S bus); empty without an audio dac
155#endif
156
158};
159
160} // namespace esphome::speaker
Lightweight read-only view over a const array stored in RODATA (will typically be in flash memory).
Definition helpers.h:131
virtual size_t play(const uint8_t *data, size_t length)=0
Plays the provided audio data.
bool is_running() const
Definition speaker.h:68
virtual void set_volume(float volume)
Definition speaker.h:74
size_t play(const std::vector< uint8_t > &data)
Definition speaker.h:53
void notify_audio_dacs_started_()
Tells every audio dac that its audio clocks are running; call from the main loop.
Definition speaker.h:140
void set_audio_dac(audio_dac::AudioDac *audio_dac)
Sets a single audio dac (nullptr for none), replacing any list; keeps its own copy of the pointer.
Definition speaker.h:95
virtual float get_volume()
Definition speaker.h:83
virtual bool get_pause_state() const
Definition speaker.h:64
virtual void set_pause_state(bool pause_state)
Definition speaker.h:63
CallbackManager< void(uint32_t, int64_t)> audio_output_callback_
Definition speaker.h:157
void set_audio_stream_info(const audio::AudioStreamInfo &audio_stream_info)
Definition speaker.h:104
audio::AudioStreamInfo & get_audio_stream_info()
Definition speaker.h:108
void add_audio_output_callback(F &&callback)
Callback function for sending the duration of the audio written to the speaker since the last callbac...
Definition speaker.h:114
virtual bool get_mute_state()
Definition speaker.h:91
virtual void set_mute_state(bool mute_state)
Definition speaker.h:85
virtual bool has_buffered_data() const =0
void set_audio_dacs(audio_dac::AudioDac *const *audio_dacs, size_t count)
Codegen only: the table must outlive this speaker. Every DAC listed is fed by this speaker's audio ou...
Definition speaker.h:99
audio::AudioStreamInfo audio_stream_info_
Definition speaker.h:149
virtual void start()=0
virtual void finish()
Definition speaker.h:60
bool has_audio_dac_() const
Whether volume and mute are handled in hardware by at least one audio dac.
Definition speaker.h:125
ConstVector< audio_dac::AudioDac *, true > audio_dacs_
Definition speaker.h:154
bool is_stopped() const
Definition speaker.h:69
bool is_silent_() const
Whether the output should be silent: muted, or the volume is effectively zero.
Definition speaker.h:121
void apply_audio_dac_mute_()
Uses the audio dacs' mute as the silence mechanism, since a dac's minimum volume is often audible.
Definition speaker.h:128
virtual void stop()=0
unsigned count
Definition gif.cpp:51
static void uint32_t
uint16_t length
Definition tt21100.cpp:0