esphome 2025.4.2__py3-none-any.whl → 2025.5.0b3__py3-none-any.whl

esphome/components/micro_wake_word/streaming_model.h

@@ -4,6 +4,8 @@
 
 #include "preprocessor_settings.h"
 
+#include "esphome/core/preferences.h"
+
 #include <tensorflow/lite/core/c/common.h>
 #include <tensorflow/lite/micro/micro_interpreter.h>
 #include <tensorflow/lite/micro/micro_mutable_op_resolver.h>
@@ -11,31 +13,71 @@
 namespace esphome {
 namespace micro_wake_word {
 
+static const uint8_t MIN_SLICES_BEFORE_DETECTION = 100;
 static const uint32_t STREAMING_MODEL_VARIABLE_ARENA_SIZE = 1024;
 
+struct DetectionEvent {
+  std::string *wake_word;
+  bool detected;
+  bool partially_detection;  // Set if the most recent probability exceed the threshold, but the sliding window average
+                             // hasn't yet
+  uint8_t max_probability;
+  uint8_t average_probability;
+  bool blocked_by_vad = false;
+};
+
 class StreamingModel {
  public:
   virtual void log_model_config() = 0;
-  virtual bool determine_detected() = 0;
+  virtual DetectionEvent determine_detected() = 0;
 
+  // Performs inference on the given features.
+  //  - If the model is enabled but not loaded, it will load it
+  //  - If the model is disabled but loaded, it will unload it
+  // Returns true if sucessful or false if there is an error
   bool perform_streaming_inference(const int8_t features[PREPROCESSOR_FEATURE_SIZE]);
 
-  /// @brief Sets all recent_streaming_probabilities to 0
+  /// @brief Sets all recent_streaming_probabilities to 0 and resets the ignore window count
   void reset_probabilities();
 
-  /// @brief Allocates tensor and variable arenas and sets up the model interpreter
-  /// @param op_resolver MicroMutableOpResolver object that must exist until the model is unloaded
-  /// @return True if successful, false otherwise
-  bool load_model(tflite::MicroMutableOpResolver<20> &op_resolver);
-
   /// @brief Destroys the TFLite interpreter and frees the tensor and variable arenas' memory
   void unload_model();
 
+  /// @brief Enable the model. The next performing_streaming_inference call will load it.
+  virtual void enable() { this->enabled_ = true; }
+
+  /// @brief Disable the model. The next performing_streaming_inference call will unload it.
+  virtual void disable() { this->enabled_ = false; }
+
+  /// @brief Return true if the model is enabled.
+  bool is_enabled() const { return this->enabled_; }
+
+  bool get_unprocessed_probability_status() const { return this->unprocessed_probability_status_; }
+
+  // Quantized probability cutoffs mapping 0.0 - 1.0 to 0 - 255
+  uint8_t get_default_probability_cutoff() const { return this->default_probability_cutoff_; }
+  uint8_t get_probability_cutoff() const { return this->probability_cutoff_; }
+  void set_probability_cutoff(uint8_t probability_cutoff) { this->probability_cutoff_ = probability_cutoff; }
+
  protected:
+  /// @brief Allocates tensor and variable arenas and sets up the model interpreter
+  /// @return True if successful, false otherwise
+  bool load_model_();
+  /// @brief Returns true if successfully registered the streaming model's TensorFlow operations
+  bool register_streaming_ops_(tflite::MicroMutableOpResolver<20> &op_resolver);
+
+  tflite::MicroMutableOpResolver<20> streaming_op_resolver_;
+
+  bool loaded_{false};
+  bool enabled_{true};
+  bool unprocessed_probability_status_{false};
   uint8_t current_stride_step_{0};
+  int16_t ignore_windows_{-MIN_SLICES_BEFORE_DETECTION};
 
-  float probability_cutoff_;
+  uint8_t default_probability_cutoff_;
+  uint8_t probability_cutoff_;
   size_t sliding_window_size_;
+
   size_t last_n_index_{0};
   size_t tensor_arena_size_;
   std::vector<uint8_t> recent_streaming_probabilities_;
@@ -50,32 +92,62 @@ class StreamingModel {
 
 class WakeWordModel final : public StreamingModel {
  public:
-  WakeWordModel(const uint8_t *model_start, float probability_cutoff, size_t sliding_window_average_size,
-                const std::string &wake_word, size_t tensor_arena_size);
+  /// @brief Constructs a wake word model object
+  /// @param id (std::string) identifier for this model
+  /// @param model_start (const uint8_t *) pointer to the start of the model's TFLite FlatBuffer
+  /// @param default_probability_cutoff (uint8_t) probability cutoff for acceping the wake word has been said
+  /// @param sliding_window_average_size (size_t) the length of the sliding window computing the mean rolling
+  ///                                    probability
+  /// @param wake_word (std::string) Friendly name of the wake word
+  /// @param tensor_arena_size (size_t) Size in bytes for allocating the tensor arena
+  /// @param default_enabled (bool) If true, it will be enabled by default on first boot
+  /// @param internal_only (bool) If true, the model will not be exposed to HomeAssistant as an available model
+  WakeWordModel(const std::string &id, const uint8_t *model_start, uint8_t default_probability_cutoff,
+                size_t sliding_window_average_size, const std::string &wake_word, size_t tensor_arena_size,
+                bool default_enabled, bool internal_only);
 
   void log_model_config() override;
 
   /// @brief Checks for the wake word by comparing the mean probability in the sliding window with the probability
   /// cutoff
   /// @return True if wake word is detected, false otherwise
-  bool determine_detected() override;
+  DetectionEvent determine_detected() override;
 
+  const std::string &get_id() const { return this->id_; }
   const std::string &get_wake_word() const { return this->wake_word_; }
 
+  void add_trained_language(const std::string &language) { this->trained_languages_.push_back(language); }
+  const std::vector<std::string> &get_trained_languages() const { return this->trained_languages_; }
+
+  /// @brief Enable the model and save to flash. The next performing_streaming_inference call will load it.
+  void enable() override;
+
+  /// @brief Disable the model and save to flash. The next performing_streaming_inference call will unload it.
+  void disable() override;
+
+  bool get_internal_only() { return this->internal_only_; }
+
  protected:
+  std::string id_;
   std::string wake_word_;
+  std::vector<std::string> trained_languages_;
+
+  bool internal_only_;
+
+  ESPPreferenceObject pref_;
 };
 
 class VADModel final : public StreamingModel {
  public:
-  VADModel(const uint8_t *model_start, float probability_cutoff, size_t sliding_window_size, size_t tensor_arena_size);
+  VADModel(const uint8_t *model_start, uint8_t default_probability_cutoff, size_t sliding_window_size,
+           size_t tensor_arena_size);
 
   void log_model_config() override;
 
   /// @brief Checks for voice activity by comparing the max probability in the sliding window with the probability
   /// cutoff
   /// @return True if voice activity is detected, false otherwise
-  bool determine_detected() override;
+  DetectionEvent determine_detected() override;
 };
 
 }  // namespace micro_wake_word

esphome/components/microphone/__init__.py

@@ -1,12 +1,21 @@
 from esphome import automation
 from esphome.automation import maybe_simple_id
 import esphome.codegen as cg
+from esphome.components import audio
 import esphome.config_validation as cv
-from esphome.const import CONF_ID, CONF_TRIGGER_ID
+from esphome.const import (
+    CONF_BITS_PER_SAMPLE,
+    CONF_CHANNELS,
+    CONF_GAIN_FACTOR,
+    CONF_ID,
+    CONF_MICROPHONE,
+    CONF_TRIGGER_ID,
+)
 from esphome.core import CORE
 from esphome.coroutine import coroutine_with_priority
 
-CODEOWNERS = ["@jesserockz"]
+AUTO_LOAD = ["audio"]
+CODEOWNERS = ["@jesserockz", "@kahrendt"]
 
 IS_PLATFORM_COMPONENT = True
 
@@ -15,6 +24,7 @@ CONF_ON_DATA = "on_data"
 microphone_ns = cg.esphome_ns.namespace("microphone")
 
 Microphone = microphone_ns.class_("Microphone")
+MicrophoneSource = microphone_ns.class_("MicrophoneSource")
 
 CaptureAction = microphone_ns.class_(
     "CaptureAction", automation.Action, cg.Parented.template(Microphone)
@@ -22,16 +32,23 @@ CaptureAction = microphone_ns.class_(
 StopCaptureAction = microphone_ns.class_(
     "StopCaptureAction", automation.Action, cg.Parented.template(Microphone)
 )
+MuteAction = microphone_ns.class_(
+    "MuteAction", automation.Action, cg.Parented.template(Microphone)
+)
+UnmuteAction = microphone_ns.class_(
+    "UnmuteAction", automation.Action, cg.Parented.template(Microphone)
+)
 
 
 DataTrigger = microphone_ns.class_(
     "DataTrigger",
-    automation.Trigger.template(cg.std_vector.template(cg.int16).operator("ref")),
+    automation.Trigger.template(cg.std_vector.template(cg.uint8).operator("ref")),
 )
 
 IsCapturingCondition = microphone_ns.class_(
     "IsCapturingCondition", automation.Condition
 )
+IsMutedCondition = microphone_ns.class_("IsMutedCondition", automation.Condition)
 
 
 async def setup_microphone_core_(var, config):
@@ -39,7 +56,7 @@ async def setup_microphone_core_(var, config):
         trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
         await automation.build_automation(
             trigger,
-            [(cg.std_vector.template(cg.int16).operator("ref").operator("const"), "x")],
+            [(cg.std_vector.template(cg.uint8).operator("ref").operator("const"), "x")],
             conf,
         )
 
@@ -50,7 +67,7 @@ async def register_microphone(var, config):
     await setup_microphone_core_(var, config)
 
 
-MICROPHONE_SCHEMA = cv.Schema(
+MICROPHONE_SCHEMA = cv.Schema.extend(audio.AUDIO_COMPONENT_SCHEMA).extend(
     {
         cv.Optional(CONF_ON_DATA): automation.validate_automation(
             {
@@ -64,7 +81,110 @@ MICROPHONE_SCHEMA = cv.Schema(
 MICROPHONE_ACTION_SCHEMA = maybe_simple_id({cv.GenerateID(): cv.use_id(Microphone)})
 
 
-async def media_player_action(config, action_id, template_arg, args):
+def microphone_source_schema(
+    min_bits_per_sample: int = 16,
+    max_bits_per_sample: int = 16,
+    min_channels: int = 1,
+    max_channels: int = 1,
+):
+    """Schema for a microphone source
+
+    Components requesting microphone data should use this schema instead of accessing a microphone directly.
+
+    Args:
+      min_bits_per_sample (int, optional): Minimum number of bits per sample the requesting component supports. Defaults to 16.
+      max_bits_per_sample (int, optional): Maximum number of bits per sample the requesting component supports. Defaults to 16.
+      min_channels (int, optional): Minimum number of channels the requesting component supports. Defaults to 1.
+      max_channels (int, optional): Maximum number of channels the requesting component supports. Defaults to 1.
+    """
+
+    def _validate_unique_channels(config):
+        if len(config) != len(set(config)):
+            raise cv.Invalid("Channels must be unique")
+        return config
+
+    return cv.All(
+        automation.maybe_conf(
+            CONF_MICROPHONE,
+            {
+                cv.GenerateID(CONF_ID): cv.declare_id(MicrophoneSource),
+                cv.GenerateID(CONF_MICROPHONE): cv.use_id(Microphone),
+                cv.Optional(CONF_BITS_PER_SAMPLE, default=16): cv.int_range(
+                    min_bits_per_sample, max_bits_per_sample
+                ),
+                cv.Optional(CONF_CHANNELS, default="0"): cv.All(
+                    cv.ensure_list(cv.int_range(0, 7)),
+                    cv.Length(min=min_channels, max=max_channels),
+                    _validate_unique_channels,
+                ),
+                cv.Optional(CONF_GAIN_FACTOR, default="1"): cv.int_range(1, 64),
+            },
+        ),
+    )
+
+
+def final_validate_microphone_source_schema(
+    component_name: str, sample_rate: int = cv.UNDEFINED
+):
+    """Validates that the microphone source can provide audio in the correct format. In particular it validates the sample rate and the enabled channels.
+
+    Note that:
+      - MicrophoneSource class automatically handles converting bits per sample, so no need to validate
+      - microphone_source_schema already validates that channels are unique and specifies the max number of channels the component supports
+
+    Args:
+        component_name (str): The name of the component requesting mic audio
+        sample_rate (int, optional): The sample rate the component requesting mic audio requires
+    """
+
+    def _validate_audio_compatability(config):
+        if sample_rate is not cv.UNDEFINED:
+            # Issues require changing the microphone configuration
+            #  - Verifies sample rates match
+            audio.final_validate_audio_schema(
+                component_name,
+                audio_device=CONF_MICROPHONE,
+                sample_rate=sample_rate,
+                audio_device_issue=True,
+            )(config)
+
+        # Issues require changing the MicrophoneSource configuration
+        # - Verifies that each of the enabled channels are available
+        audio.final_validate_audio_schema(
+            component_name,
+            audio_device=CONF_MICROPHONE,
+            enabled_channels=config[CONF_CHANNELS],
+            audio_device_issue=False,
+        )(config)
+
+        return config
+
+    return _validate_audio_compatability
+
+
+async def microphone_source_to_code(config, passive=False):
+    """Creates a MicrophoneSource variable for codegen.
+
+    Setting passive to true makes the MicrophoneSource never start/stop the microphone, but only receives audio when another component has actively started the Microphone. If false, then the microphone needs to be explicitly started/stopped.
+
+    Args:
+        config (Schema): Created with `microphone_source_schema` specifying bits per sample, channels, and gain factor
+        passive (bool): Enable passive mode for the MicrophoneSource
+    """
+    mic = await cg.get_variable(config[CONF_MICROPHONE])
+    mic_source = cg.new_Pvariable(
+        config[CONF_ID],
+        mic,
+        config[CONF_BITS_PER_SAMPLE],
+        config[CONF_GAIN_FACTOR],
+        passive,
+    )
+    for channel in config[CONF_CHANNELS]:
+        cg.add(mic_source.add_channel(channel))
+    return mic_source
+
+
+async def microphone_action(config, action_id, template_arg, args):
     var = cg.new_Pvariable(action_id, template_arg)
     await cg.register_parented(var, config[CONF_ID])
     return var
@@ -72,15 +192,25 @@ async def media_player_action(config, action_id, template_arg, args):
 
 automation.register_action(
     "microphone.capture", CaptureAction, MICROPHONE_ACTION_SCHEMA
-)(media_player_action)
+)(microphone_action)
 
 automation.register_action(
     "microphone.stop_capture", StopCaptureAction, MICROPHONE_ACTION_SCHEMA
-)(media_player_action)
+)(microphone_action)
+
+automation.register_action("microphone.mute", MuteAction, MICROPHONE_ACTION_SCHEMA)(
+    microphone_action
+)
+automation.register_action("microphone.unmute", UnmuteAction, MICROPHONE_ACTION_SCHEMA)(
+    microphone_action
+)
 
 automation.register_condition(
     "microphone.is_capturing", IsCapturingCondition, MICROPHONE_ACTION_SCHEMA
-)(media_player_action)
+)(microphone_action)
+automation.register_condition(
+    "microphone.is_muted", IsMutedCondition, MICROPHONE_ACTION_SCHEMA
+)(microphone_action)
 
 
 @coroutine_with_priority(100.0)

esphome/components/microphone/automation.h

@@ -16,10 +16,17 @@ template<typename... Ts> class StopCaptureAction : public Action<Ts...>, public
   void play(Ts... x) override { this->parent_->stop(); }
 };
 
-class DataTrigger : public Trigger<const std::vector<int16_t> &> {
+template<typename... Ts> class MuteAction : public Action<Ts...>, public Parented<Microphone> {
+  void play(Ts... x) override { this->parent_->set_mute_state(true); }
+};
+template<typename... Ts> class UnmuteAction : public Action<Ts...>, public Parented<Microphone> {
+  void play(Ts... x) override { this->parent_->set_mute_state(false); }
+};
+
+class DataTrigger : public Trigger<const std::vector<uint8_t> &> {
  public:
   explicit DataTrigger(Microphone *mic) {
-    mic->add_data_callback([this](const std::vector<int16_t> &data) { this->trigger(data); });
+    mic->add_data_callback([this](const std::vector<uint8_t> &data) { this->trigger(data); });
   }
 };
 
@@ -28,5 +35,10 @@ template<typename... Ts> class IsCapturingCondition : public Condition<Ts...>, p
   bool check(Ts... x) override { return this->parent_->is_running(); }
 };
 
+template<typename... Ts> class IsMutedCondition : public Condition<Ts...>, public Parented<Microphone> {
+ public:
+  bool check(Ts... x) override { return this->parent_->get_mute_state(); }
+};
+
 }  // namespace microphone
 }  // namespace esphome

esphome/components/microphone/microphone.cpp

@@ -0,0 +1,21 @@
+#include "microphone.h"
+
+namespace esphome {
+namespace microphone {
+
+void Microphone::add_data_callback(std::function<void(const std::vector<uint8_t> &)> &&data_callback) {
+  std::function<void(const std::vector<uint8_t> &)> mute_handled_callback =
+      [this, data_callback](const std::vector<uint8_t> &data) { data_callback(this->silence_audio_(data)); };
+  this->data_callbacks_.add(std::move(mute_handled_callback));
+}
+
+std::vector<uint8_t> Microphone::silence_audio_(std::vector<uint8_t> data) {
+  if (this->mute_state_) {
+    std::memset((void *) data.data(), 0, data.size());
+  }
+
+  return data;
+}
+
+}  // namespace microphone
+}  // namespace esphome

esphome/components/microphone/microphone.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include "esphome/components/audio/audio.h"
+
 #include <cstddef>
 #include <cstdint>
 #include <functional>
@@ -20,18 +22,25 @@ class Microphone {
  public:
   virtual void start() = 0;
   virtual void stop() = 0;
-  void add_data_callback(std::function<void(const std::vector<int16_t> &)> &&data_callback) {
-    this->data_callbacks_.add(std::move(data_callback));
-  }
-  virtual size_t read(int16_t *buf, size_t len) = 0;
+  void add_data_callback(std::function<void(const std::vector<uint8_t> &)> &&data_callback);
 
   bool is_running() const { return this->state_ == STATE_RUNNING; }
   bool is_stopped() const { return this->state_ == STATE_STOPPED; }
 
+  void set_mute_state(bool is_muted) { this->mute_state_ = is_muted; }
+  bool get_mute_state() { return this->mute_state_; }
+
+  audio::AudioStreamInfo get_audio_stream_info() { return this->audio_stream_info_; }
+
  protected:
+  std::vector<uint8_t> silence_audio_(std::vector<uint8_t> data);
+
   State state_{STATE_STOPPED};
+  bool mute_state_{false};
+
+  audio::AudioStreamInfo audio_stream_info_;
 
-  CallbackManager<void(const std::vector<int16_t> &)> data_callbacks_{};
+  CallbackManager<void(const std::vector<uint8_t> &)> data_callbacks_{};
 };
 
 }  // namespace microphone

esphome/components/microphone/microphone_source.cpp

@@ -0,0 +1,95 @@
+#include "microphone_source.h"
+
+namespace esphome {
+namespace microphone {
+
+static const int32_t Q25_MAX_VALUE = (1 << 25) - 1;
+static const int32_t Q25_MIN_VALUE = ~Q25_MAX_VALUE;
+
+void MicrophoneSource::add_data_callback(std::function<void(const std::vector<uint8_t> &)> &&data_callback) {
+  std::function<void(const std::vector<uint8_t> &)> filtered_callback =
+      [this, data_callback](const std::vector<uint8_t> &data) {
+        if (this->enabled_ || this->passive_) {
+          if (this->processed_samples_.use_count() == 0) {
+            // Create vector if its unused
+            this->processed_samples_ = std::make_shared<std::vector<uint8_t>>();
+          }
+
+          // Take temporary ownership of samples vector to avoid deallaction before the callback finishes
+          std::shared_ptr<std::vector<uint8_t>> output_samples = this->processed_samples_;
+          this->process_audio_(data, *output_samples);
+          data_callback(*output_samples);
+        }
+      };
+  this->mic_->add_data_callback(std::move(filtered_callback));
+}
+
+audio::AudioStreamInfo MicrophoneSource::get_audio_stream_info() {
+  return audio::AudioStreamInfo(this->bits_per_sample_, this->channels_.count(),
+                                this->mic_->get_audio_stream_info().get_sample_rate());
+}
+
+void MicrophoneSource::start() {
+  if (!this->enabled_ && !this->passive_) {
+    this->enabled_ = true;
+    this->mic_->start();
+  }
+}
+
+void MicrophoneSource::stop() {
+  if (this->enabled_ && !this->passive_) {
+    this->enabled_ = false;
+    this->mic_->stop();
+    this->processed_samples_.reset();
+  }
+}
+
+void MicrophoneSource::process_audio_(const std::vector<uint8_t> &data, std::vector<uint8_t> &filtered_data) {
+  // - Bit depth conversions are obtained by truncating bits or padding with zeros - no dithering is applied.
+  // - In the comments, Qxx refers to a fixed point number with xx bits of precision for representing fractional values.
+  //   For example, audio with a bit depth of 16 can store a sample in a int16, which can be considered a Q15 number.
+  // - All samples are converted to Q25 before applying the gain factor - this results in a small precision loss for
+  //   data with 32 bits per sample. Since the maximum gain factor is 64 = (1<<6), this ensures that applying the gain
+  //   will never overflow a 32 bit signed integer. This still retains more bit depth than what is audibly noticeable.
+  // - Loops for reading/writing data buffers are unrolled, assuming little endian, for a small performance increase.
+
+  const size_t source_bytes_per_sample = this->mic_->get_audio_stream_info().samples_to_bytes(1);
+  const uint32_t source_channels = this->mic_->get_audio_stream_info().get_channels();
+
+  const size_t source_bytes_per_frame = this->mic_->get_audio_stream_info().frames_to_bytes(1);
+
+  const uint32_t total_frames = this->mic_->get_audio_stream_info().bytes_to_frames(data.size());
+  const size_t target_bytes_per_sample = (this->bits_per_sample_ + 7) / 8;
+  const size_t target_bytes_per_frame = target_bytes_per_sample * this->channels_.count();
+
+  filtered_data.resize(target_bytes_per_frame * total_frames);
+
+  uint8_t *current_data = filtered_data.data();
+
+  for (uint32_t frame_index = 0; frame_index < total_frames; ++frame_index) {
+    for (uint32_t channel_index = 0; channel_index < source_channels; ++channel_index) {
+      if (this->channels_.test(channel_index)) {
+        // Channel's current sample is included in the target mask. Convert bits per sample, if necessary.
+
+        const uint32_t sample_index = frame_index * source_bytes_per_frame + channel_index * source_bytes_per_sample;
+
+        int32_t sample = audio::unpack_audio_sample_to_q31(&data[sample_index], source_bytes_per_sample);  // Q31
+        sample >>= 6;                                                                                      // Q31 -> Q25
+
+        // Apply gain using multiplication
+        sample *= this->gain_factor_;  // Q25
+
+        // Clamp ``sample`` in case gain multiplication overflows 25 bits
+        sample = clamp<int32_t>(sample, Q25_MIN_VALUE, Q25_MAX_VALUE);  // Q25
+
+        sample *= (1 << 6);  // Q25 -> Q31
+
+        audio::pack_q31_as_audio_sample(sample, current_data, target_bytes_per_sample);
+        current_data = current_data + target_bytes_per_sample;
+      }
+    }
+  }
+}
+
+}  // namespace microphone
+}  // namespace esphome

esphome/components/microphone/microphone_source.h

@@ -0,0 +1,80 @@
+#pragma once
+
+#include "microphone.h"
+
+#include "esphome/components/audio/audio.h"
+
+#include <bitset>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+namespace esphome {
+namespace microphone {
+
+static const int32_t MAX_GAIN_FACTOR = 64;
+
+class MicrophoneSource {
+  /*
+   * @brief Helper class that handles converting raw microphone data to a requested format.
+   * Components requesting microphone audio should register a callback through this class instead of registering a
+   * callback directly with the microphone if a particular format is required.
+   *
+   * Raw microphone data may have a different number of bits per sample and number of channels than the requesting
+   * component needs. This class handles the conversion by:
+   *   - Internally adds a callback to receive the raw microphone data
+   *   - The ``process_audio_`` handles the raw data
+   *     - Only the channels set in the ``channels_`` bitset are passed through
+   *     - Passed through samples have the bits per sample converted
+   *     - A gain factor is optionally applied to increase the volume - audio may clip!
+   *   - The processed audio is passed to the callback of the component requesting microphone data
+   *   - It tracks an internal enabled state, so it ignores raw microphone data when the component requesting
+   *     microphone data is not actively requesting audio.
+   *
+   * Note that this class cannot convert sample rates!
+   */
+ public:
+  MicrophoneSource(Microphone *mic, uint8_t bits_per_sample, int32_t gain_factor, bool passive)
+      : mic_(mic), bits_per_sample_(bits_per_sample), gain_factor_(gain_factor), passive_(passive) {}
+
+  /// @brief Enables a channel to be processed through the callback.
+  ///
+  /// If the microphone component only has reads from one channel, it is always in channel number 0, regardless if it
+  /// represents left or right. If the microphone reads from both left and right, channel number 0 and 1 represent the
+  /// left and right channels respectively.
+  ///
+  /// @param channel 0-indexed channel number to enable
+  void add_channel(uint8_t channel) { this->channels_.set(channel); }
+
+  void add_data_callback(std::function<void(const std::vector<uint8_t> &)> &&data_callback);
+
+  void set_gain_factor(int32_t gain_factor) { this->gain_factor_ = clamp<int32_t>(gain_factor, 1, MAX_GAIN_FACTOR); }
+  int32_t get_gain_factor() { return this->gain_factor_; }
+
+  /// @brief Gets the AudioStreamInfo of the data after processing
+  /// @return audio::AudioStreamInfo with the configured bits per sample, configured channel count, and source
+  ///         microphone's sample rate
+  audio::AudioStreamInfo get_audio_stream_info();
+
+  void start();
+  void stop();
+  bool is_passive() const { return this->passive_; }
+  bool is_running() const { return (this->mic_->is_running() && (this->enabled_ || this->passive_)); }
+  bool is_stopped() const { return !this->is_running(); };
+
+ protected:
+  void process_audio_(const std::vector<uint8_t> &data, std::vector<uint8_t> &filtered_data);
+
+  std::shared_ptr<std::vector<uint8_t>> processed_samples_;
+
+  Microphone *mic_;
+  uint8_t bits_per_sample_;
+  std::bitset<8> channels_;
+  int32_t gain_factor_;
+  bool enabled_{false};
+  bool passive_;  // Only pass audio if ``mic_`` is already running
+};
+
+}  // namespace microphone
+}  // namespace esphome