new class: AudioInputMonitor

Author: pschatzmann

src/AudioTools/CoreAudio/AudioStreams.h

@@ -449,9 +449,7 @@ class GeneratedSoundStream : public AudioStream {
   AudioInfo audioInfo() override { return generator_ptr->audioInfo(); }
 
   /// This is unbounded so we just return the buffer size
-  virtual int available() override {
-    return active ? buffer_size : 0;
-  }
+  virtual int available() override { return active ? buffer_size : 0; }
 
   /// privide the data as byte stream
   size_t readBytes(uint8_t *data, size_t len) override {
@@ -472,7 +470,8 @@ class GeneratedSoundStream : public AudioStream {
  protected:
   bool active = true;  // support for legacy sketches
   SoundGenerator<T> *generator_ptr;
-  int buffer_size = DEFAULT_BUFFER_SIZE * 100; // there is no reason to limit this
+  int buffer_size =
+      DEFAULT_BUFFER_SIZE * 100;  // there is no reason to limit this
   const char *source_not_defined_error = "Source not defined";
 };
 
@@ -579,15 +578,15 @@ class BufferedStream : public ModifyingStream {
     }
   }
 
-  /// Provides data w/o consuming 
+  /// Provides data w/o consuming
   size_t peekBytes(uint8_t *data, size_t len) {
     if (buffer.isEmpty()) {
       refill();
-    } 
+    }
     return buffer.peekArray(data, len);
   }
 
-  /// Returns the available bytes 
+  /// Returns the available bytes
   int available() override {
     if (p_in == nullptr) return 0;
     return buffer.available() + p_in->available();
@@ -599,10 +598,9 @@ class BufferedStream : public ModifyingStream {
   /// Resize the buffer
   void resize(int size) { buffer.resize(size); }
 
-  /// Defines the minimum direct unbuffered read size to the original source (default is 1024)
-  void setMinUnbufferedReadSize(size_t size) {
-    minReadBufferSize = size;
-  }
+  /// Defines the minimum direct unbuffered read size to the original source
+  /// (default is 1024)
+  void setMinUnbufferedReadSize(size_t size) { minReadBufferSize = size; }
 
  protected:
   SingleBuffer<uint8_t> buffer{0};
@@ -1258,7 +1256,7 @@ class InputMixer : public AudioStream {
   void setRetryCount(int retry) { retry_count = retry; }
 
   /// Removes a stream by index position
-  bool remove(int idx){
+  bool remove(int idx) {
     if (idx < 0 || idx >= size()) {
       return false;
     }
@@ -1313,11 +1311,11 @@ class InputMixer : public AudioStream {
 
   /// Recalculate the weights
   void recalculateWeights() {
-      int total = 0;
-      for (int j = 0; j < weights.size(); j++) {
-        total += weights[j];
-      }
-      total_weights = total;
+    int total = 0;
+    for (int j = 0; j < weights.size(); j++) {
+      total += weights[j];
+    }
+    total_weights = total;
   }
 
   /// mixing using a vector of samples
@@ -1753,14 +1751,8 @@ class FilteredStream : public ModifyingStream {
 class VolumeMeter : public ModifyingStream {
  public:
   VolumeMeter() = default;
-  VolumeMeter(AudioStream &as) {
-    addNotifyAudioChange(as);
-    setStream(as);
-  }
-  VolumeMeter(AudioOutput &ao) {
-    addNotifyAudioChange(ao);
-    setOutput(ao);
-  }
+  VolumeMeter(AudioStream &as) { setStream(as); }
+  VolumeMeter(AudioOutput &ao) { setOutput(ao); }
   VolumeMeter(Print &print) { setOutput(print); }
   VolumeMeter(Stream &stream) { setStream(stream); }
 
@@ -1875,6 +1867,14 @@ class VolumeMeter : public ModifyingStream {
     }
   }
 
+  void setOutput(AudioOutput &out) {
+    addNotifyAudioChange(out);
+    setOutput((Print &)out);
+  }
+  void setStream(AudioStream &io) {
+    addNotifyAudioChange(io);
+    setStream((Stream &)io);
+  }
   void setOutput(Print &out) override { p_out = &out; }
   void setStream(Stream &io) override {
     p_out = &io;
@@ -1953,10 +1953,178 @@ class VolumeMeter : public ModifyingStream {
 /// @ingroup io
 using VolumePrint = VolumeMeter;
 
-/// @brief Legacy alias for VolumeMeter  
+/// @brief Legacy alias for VolumeMeter
 /// @ingroup io
 using VolumeOutput = VolumeMeter;
 
+/**
+ * @brief Monitors audio input and reports if the volume exceeds a specified
+ * limit within a given period.
+ *
+ * This class uses a VolumeMeter internally and tracks if the input volume has
+ * exceeded the specified limit during the last period. It can be used in an
+ * audio processing chain as a ModifyingStream.
+ * @ingroup io
+ * @ingroup volume
+ * @author Phil Schatzmann
+ * @copyright GPLv3
+ */
+class AudioInputMonitor : public ModifyingStream {
+ public:
+  /**
+   * @brief Construct a new AudioInputMonitor with a volume limit in percent
+   * @param limitPercent The volume threshold as percent (default: 20)
+   */
+  AudioInputMonitor(uint8_t limitPercent = 20) {
+    setLimitPercent(limitPercent);
+    volume_meter.addNotifyAudioChange(*this);
+  }
+  /**
+   * @brief Construct a new AudioInputMonitor with an input stream
+   * @param as Reference to an AudioStream
+   * @param limitPercent The volume threshold as percent (default: 20)
+   */
+  AudioInputMonitor(AudioStream &as, uint8_t limitPercent = 20)
+      : AudioInputMonitor(limitPercent) {
+    setStream(as);
+  }
+  /**
+   * @brief Construct a new AudioInputMonitor with an output
+   * @param ao Reference to an AudioOutput
+   * @param limitPercent The volume threshold as percent (default: 20)
+   */
+  AudioInputMonitor(AudioOutput &ao, uint8_t limitPercent = 20)
+      : AudioInputMonitor(limitPercent) {
+    setOutput(ao);
+  }
+  /**
+   * @brief Construct a new AudioInputMonitor with a Print output
+   * @param print Reference to a Print object
+   * @param limitPercent The volume threshold as percent (default: 20)
+   */
+  AudioInputMonitor(Print &print, uint8_t limitPercent = 20)
+      : AudioInputMonitor(limitPercent) {
+    setOutput(print);
+  }
+  /**
+   * @brief Construct a new AudioInputMonitor with a Stream input
+   * @param stream Reference to a Stream object
+   * @param limitPercent The volume threshold as percent (default: 20)
+   */
+  AudioInputMonitor(Stream &stream, uint8_t limitPercent = 20)
+      : AudioInputMonitor(limitPercent) {
+    setStream(stream);
+  }
+  /**
+   * @brief Set the volume threshold as percent
+   * @param percent The new volume threshold (0-100)
+   */
+  void setLimitPercent(uint8_t percent) { limit_percent = percent; }
+
+  /**
+   * @brief Get the current volume threshold as percent
+   * @return The current volume threshold (0-100)
+   */
+  uint8_t limitPercent() const { return limit_percent; }
+
+  /**
+   * @brief Begin processing with the given audio information
+   * @param info AudioInfo structure
+   * @return true if successful
+   */
+  bool begin(AudioInfo info) {
+    setAudioInfo(info);
+    return begin();
+  }
+
+  /**
+   * @brief Begin processing with the current audio information
+   * @return true if successful
+   */
+  bool begin() override {
+    volume_meter.begin(audioInfo());
+    return true;
+  }
+
+  /**
+   * @brief Set the audio information
+   * @param info AudioInfo structure
+   */
+  void setAudioInfo(AudioInfo info) override {
+    ModifyingStream::setAudioInfo(info);
+    volume_meter.setAudioInfo(info);
+  }
+
+  /**
+   * @brief Write audio data to the monitor (same as VolumeMeter)
+   * @param data Pointer to audio data
+   * @param len Number of bytes
+   * @return Number of bytes written
+   */
+  size_t write(const uint8_t *data, size_t len) override {
+    size_t result = volume_meter.write(data, len);
+    if (result > 0 && volume_meter.volumePercent() > limit_percent) {
+      time_over_last_volume_limit = millis();
+    }
+    return result;
+  }
+
+  /**
+   * @brief Read audio data from the monitor (same as VolumeMeter)
+   * @param data Pointer to buffer to fill
+   * @param len Number of bytes to read
+   * @return Number of bytes read
+   */
+  size_t readBytes(uint8_t *data, size_t len) override {
+    size_t result = volume_meter.readBytes(data, len);
+    if (result > 0 && volume_meter.volumePercent() > limit_percent) {
+      time_over_last_volume_limit = millis();
+    }
+    return result;
+  }
+
+  /**
+   * @brief Set the output target
+   * @param out Reference to a Print object
+   */
+  void setOutput(Print &out) override { volume_meter.setOutput(out); }
+  /**
+   * @brief Set the output target
+   * @param out Reference to a Print object
+   */
+  void setOutput(AudioOutput &out) { volume_meter.setOutput(out); }
+  /**
+   * @brief Set the input stream
+   * @param io Reference to a Stream object
+   */
+  void setStream(Stream &io) override { volume_meter.setStream(io); }
+  /**
+   * @brief Set the input stream
+   * @param io Reference to a Stream object
+   */
+  void setStream(AudioStream &io) { volume_meter.setStream(io); }
+
+  /**
+   * @brief Access the underlying VolumeMeter
+   * @return Reference to the internal VolumeMeter
+   */
+  VolumeMeter &getVolumeMeter() { return volume_meter; }
+
+  /**
+   * @brief Returns true if the volume exceeded the limit during the last period
+   * @param time_ms The period in milliseconds to check (default: 1000)
+   * @return true if the volume exceeded the limit during the period
+   */
+  bool isActive(uint16_t time_ms = 1000) {
+    return (millis() - time_over_last_volume_limit) < time_ms;
+  }
+
+protected:
+  VolumeMeter volume_meter; ///< Volume calculation
+  uint8_t limit_percent = 20; ///< Threshold percent
+  uint64_t time_over_last_volume_limit = 0; ///< Last over-limit time (ms)
+};
+
 #ifdef USE_TIMER
 /**
  * @brief TimerCallbackAudioStream Configuration