ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
microphone_source.h
Go to the documentation of this file.
1#pragma once
2
3#include "microphone.h"
4
6
7#include <bitset>
8#include <cstddef>
9#include <cstdint>
10#include <span>
11#include <vector>
12
13namespace esphome::microphone {
14
15static const int32_t MAX_GAIN_FACTOR = 64;
16
17class MicrophoneSource final {
18 /*
19 * @brief Helper class that handles converting raw microphone data to a requested format.
20 * Components requesting microphone audio should register a callback through this class instead of registering a
21 * callback directly with the microphone if a particular format is required.
22 *
23 * Raw microphone data may have a different number of bits per sample and number of channels than the requesting
24 * component needs. This class handles the conversion by:
25 * - Internally adds a callback to receive the raw microphone data
26 * - The ``process_audio_`` handles the raw data
27 * - Only the channels set in the ``channels_`` bitset are passed through
28 * - Passed through samples have the bits per sample converted
29 * - A gain factor is optionally applied to increase the volume - audio may clip!
30 * - The processed audio is passed to the callback of the component requesting microphone data
31 * - It tracks an internal enabled state, so it ignores raw microphone data when the component requesting
32 * microphone data is not actively requesting audio.
33 *
34 * Note that this class cannot convert sample rates!
35 */
36 public:
37 MicrophoneSource(Microphone *mic, uint8_t bits_per_sample, int32_t gain_factor, bool passive)
38 : mic_(mic), gain_factor_(gain_factor), passive_(passive), bits_per_sample_(bits_per_sample) {}
39
47 void add_channel(uint8_t channel) { this->channels_.set(channel); }
48
50 template<typename F> void add_data_callback(F &&data_callback) {
52 [this, callback = as_capture_callback(std::forward<F>(data_callback))](const AudioCapture &capture) {
53 if (this->enabled_ || this->passive_) {
54 if (this->processed_samples_ == nullptr) {
55 // Create vector if its unused
56 this->processed_samples_ = std::make_shared<std::vector<uint8_t>>();
57 }
58
59 // Take temporary ownership of samples vector to avoid deallocation before the callback finishes
60 std::shared_ptr<std::vector<uint8_t>> output_samples = this->processed_samples_;
61 this->process_audio_(capture.data, capture.stream_info, *output_samples);
62 callback(AudioCapture{*output_samples,
65 capture.capture_time_us});
66 }
67 });
68 }
69
70 void set_gain_factor(int32_t gain_factor) { this->gain_factor_ = clamp<int32_t>(gain_factor, 1, MAX_GAIN_FACTOR); }
71 int32_t get_gain_factor() { return this->gain_factor_; }
72
77
78 void start();
79 void stop();
80 bool is_passive() const { return this->passive_; }
81 bool is_running() const { return (this->mic_->is_running() && (this->enabled_ || this->passive_)); }
82 bool is_stopped() const { return !this->is_running(); };
83
84 protected:
85 void process_audio_(std::span<const uint8_t> data, const audio::AudioStreamInfo &source_info,
86 std::vector<uint8_t> &filtered_data);
87
88 std::shared_ptr<std::vector<uint8_t>> processed_samples_;
89
91 std::bitset<8> channels_;
92 int32_t gain_factor_;
93 bool enabled_{false};
94 bool passive_; // Only pass audio if ``mic_`` is already running
96};
97
98} // namespace esphome::microphone
uint32_t get_sample_rate() const
Definition audio.h:30
void add_data_callback(F &&data_callback)
Callbacks take (const AudioCapture &) and run on the microphone's task.
Definition microphone.h:84
void set_gain_factor(int32_t gain_factor)
void process_audio_(std::span< const uint8_t > data, const audio::AudioStreamInfo &source_info, std::vector< uint8_t > &filtered_data)
MicrophoneSource(Microphone *mic, uint8_t bits_per_sample, int32_t gain_factor, bool passive)
void add_data_callback(F &&data_callback)
Same callbacks as Microphone::add_data_callback; stream_info is the processed format.
std::shared_ptr< std::vector< uint8_t > > processed_samples_
void add_channel(uint8_t channel)
Enables a channel to be processed through the callback.
audio::AudioStreamInfo get_audio_stream_info()
Gets the AudioStreamInfo of the data after processing.
auto as_capture_callback(F &&callback)
Definition microphone.h:37
int64_t capture_time_us
esp_timer_get_time() of the first frame, or 0 if unknown
Definition microphone.h:29
audio::AudioStreamInfo stream_info
Format of data.
Definition microphone.h:27
std::span< const uint8_t > data
Only valid during the callback.
Definition microphone.h:25