Equalizer3BandsPerChannel docu

Author: pschatzmann

src/AudioTools/CoreAudio/AudioFilter/Equalizer.h

@@ -14,9 +14,22 @@
 namespace audio_tools {
 
 /**
- * @brief Configuration for 3 Band Equalizer: Set
- * channels,bits_per_sample,sample_rate.  Set and update gain_low, gain_medium
- * and gain_high to value between 0 and 1.0
+ * @brief Configuration for 3 Band Equalizer
+ * 
+ * Configure the basic audio parameters (channels, bits_per_sample, sample_rate)
+ * and the equalizer settings. The frequency and gain parameters apply to all
+ * channels identically in the basic Equalizer3Bands class.
+ * 
+ * Frequency bands:
+ * - Low band: DC to freq_low Hz
+ * - Medium band: freq_low to freq_high Hz  
+ * - High band: freq_high to Nyquist frequency
+ * 
+ * Gain values should typically range from 0.0 to 2.0:
+ * - 0.0 = complete attenuation (silence)
+ * - 1.0 = no change (unity gain)
+ * - 2.0 = 6dB boost
+ * 
  * @ingroup equilizer
  * @author pschatzmann
  */
@@ -27,33 +40,59 @@ struct ConfigEqualizer3Bands : public AudioInfo {
     sample_rate = 44100;
   }
 
-  // Frequencies
+  /// Low-pass filter cutoff frequency in Hz. Frequencies below this are considered "low"
   int freq_low = 880;
+  
+  /// High-pass filter cutoff frequency in Hz. Frequencies above this are considered "high"
   int freq_high = 5000;
 
-  // Gain Controls
+  /// Gain multiplier for low frequencies (0.0-2.0, where 1.0 = unity gain)
   float gain_low = 1.0;
+  
+  /// Gain multiplier for medium frequencies (0.0-2.0, where 1.0 = unity gain)
   float gain_medium = 1.0;
+  
+  /// Gain multiplier for high frequencies (0.0-2.0, where 1.0 = unity gain)
   float gain_high = 1.0;
 };
 
 /**
- * @brief 3 Band Equalizer inspired from
+ * @brief 3 Band Equalizer with identical settings for all channels
+ * 
+ * Digital 3-band equalizer implementation inspired from
  * https://www.musicdsp.org/en/latest/Filters/236-3-band-equaliser.html
+ * 
+ * This equalizer applies the same frequency response and gain settings
+ * to all audio channels. The audio spectrum is divided into three bands:
+ * - Low: DC to freq_low Hz (controlled by gain_low)
+ * - Medium: freq_low to freq_high Hz (controlled by gain_medium)  
+ * - High: freq_high to Nyquist frequency (controlled by gain_high)
+ * 
+ * Each band uses a 4-pole filter implementation for smooth frequency response.
+ * If you need different settings per channel, use Equalizer3BandsPerChannel instead.
+ * 
  * @ingroup equilizer
  * @author pschatzmann
  */
 class Equalizer3Bands : public ModifyingStream {
  public:
+  /// Constructor with Print output stream
+  /// @param out Print stream where processed audio will be written
   Equalizer3Bands(Print &out) { setOutput(out); }
 
+  /// Constructor with bidirectional Stream
+  /// @param in Stream for both input and output
   Equalizer3Bands(Stream &in) { setStream(in); }
 
+  /// Constructor with AudioOutput (includes automatic audio format notifications)
+  /// @param out AudioOutput where processed audio will be written
   Equalizer3Bands(AudioOutput &out) {
     setOutput(out);
     out.addNotifyAudioChange(*this);
   }
 
+  /// Constructor with AudioStream (includes automatic audio format notifications)  
+  /// @param stream AudioStream for both input and output
   Equalizer3Bands(AudioStream &stream) {
     setStream(stream);
     stream.addNotifyAudioChange(*this);
@@ -63,19 +102,28 @@ class Equalizer3Bands : public ModifyingStream {
     if (state != nullptr) delete[] state;
   }
 
-  /// Defines/Changes the input & output
+  /// Defines/Changes the input & output stream
+  /// @param io Stream to use for both reading and writing audio data
   void setStream(Stream &io) override {
     p_print = &io;
     p_stream = &io;
   };
 
   /// Defines/Changes the output target
+  /// @param out Print stream where processed audio will be written
   void setOutput(Print &out) override { p_print = &out; }
 
+  /// Access to the current configuration
+  /// @return Reference to the configuration object
   ConfigEqualizer3Bands &config() { return cfg; }
 
+  /// Access to the default configuration
+  /// @return Reference to the default configuration object  
   ConfigEqualizer3Bands &defaultConfig() { return config(); }
 
+  /// Initialize the equalizer with the provided configuration
+  /// @param config Configuration settings including frequencies and gains
+  /// @return true if initialization was successful
   bool begin(ConfigEqualizer3Bands &config) {
     p_cfg = &config;
     if (p_cfg->channels > max_state_count) {
@@ -98,21 +146,32 @@ class Equalizer3Bands : public ModifyingStream {
     return true;
   }
 
+  /// Called automatically when audio format changes
+  /// @param info New audio format information
   virtual void setAudioInfo(AudioInfo info) override {
     p_cfg->sample_rate = info.sample_rate;
     p_cfg->channels = info.channels;
     p_cfg->bits_per_sample = info.bits_per_sample;
     begin(*p_cfg);
   }
 
+  /// Process and write audio data through the equalizer
+  /// @param data Pointer to audio data buffer
+  /// @param len Length of data in bytes
+  /// @return Number of bytes written
   size_t write(const uint8_t *data, size_t len) override {
     filterSamples(data, len);
     return p_print->write(data, len);
   }
 
+  /// Get available space for writing
+  /// @return Number of bytes available for writing
   int availableForWrite() override { return p_print->availableForWrite(); }
 
-  /// Provides the data from all streams mixed together
+  /// Read and process audio data through the equalizer
+  /// @param data Buffer to store processed audio data
+  /// @param len Maximum number of bytes to read
+  /// @return Number of bytes actually read and processed
   size_t readBytes(uint8_t *data, size_t len) override {
     size_t result = 0;
     if (p_stream != nullptr) {
@@ -122,42 +181,46 @@ class Equalizer3Bands : public ModifyingStream {
     return result;
   }
 
+  /// Get available data for reading
+  /// @return Number of bytes available for reading
   int available() override {
     return p_stream != nullptr ? p_stream->available() : 0;
   }
 
  protected:
-  ConfigEqualizer3Bands cfg;
-  ConfigEqualizer3Bands *p_cfg = &cfg;
-  const float vsa = (1.0 / 4294967295.0);  // Very small amount (Denormal Fix)
-  Print *p_print = nullptr;                // support for write
-  Stream *p_stream = nullptr;              // support for write
-  // AudioOutput *p_out=nullptr; // support for write
-  // AudioStream *p_in=nullptr; // support for readBytes
-  int max_state_count = 0;
-
+  ConfigEqualizer3Bands cfg;                           ///< Default configuration instance
+  ConfigEqualizer3Bands *p_cfg = &cfg;                 ///< Pointer to active configuration
+  const float vsa = (1.0 / 4294967295.0);              ///< Very small amount for denormal fix
+  Print *p_print = nullptr;                            ///< Output stream for write operations
+  Stream *p_stream = nullptr;                          ///< Input/output stream for read operations
+  int max_state_count = 0;                             ///< Maximum number of allocated channel states
+
+  /// Filter state for each channel
   struct EQSTATE {
-    // Filter #1 (Low band)
-    float lf;    // Frequency
-    float f1p0;  // Poles ...
-    float f1p1;
-    float f1p2;
-    float f1p3;
-
-    // Filter #2 (High band)
-    float hf;    // Frequency
-    float f2p0;  // Poles ...
-    float f2p1;
-    float f2p2;
-    float f2p3;
-
-    // Sample history buffer
-    float sdm1;  // Sample data minus 1
-    float sdm2;  //                   2
-    float sdm3;  //                   3
+    // Filter #1 (Low band) - 4-pole low-pass filter
+    float lf;    ///< Low frequency cutoff coefficient
+    float f1p0;  ///< Filter pole 0
+    float f1p1;  ///< Filter pole 1
+    float f1p2;  ///< Filter pole 2
+    float f1p3;  ///< Filter pole 3
+
+    // Filter #2 (High band) - 4-pole high-pass filter  
+    float hf;    ///< High frequency cutoff coefficient
+    float f2p0;  ///< Filter pole 0
+    float f2p1;  ///< Filter pole 1
+    float f2p2;  ///< Filter pole 2
+    float f2p3;  ///< Filter pole 3
+
+    // Sample history buffer for filter calculations
+    float sdm1;  ///< Sample data minus 1 (previous sample)
+    float sdm2;  ///< Sample data minus 2
+    float sdm3;  ///< Sample data minus 3
 
   } *state = nullptr;
 
+  /// Apply 3-band equalization to audio samples
+  /// @param data Pointer to audio data buffer (modified in-place)
+  /// @param len Length of data buffer in bytes
   void filterSamples(const uint8_t *data, size_t len) {
     if (state == nullptr){
       LOGE("You need to call begin() before using the equalizer");
@@ -198,8 +261,10 @@ class Equalizer3Bands : public ModifyingStream {
     }
   }
 
-
-  // calculates a single sample using the indicated state
+  /// Process a single audio sample through the 3-band equalizer
+  /// @param es Reference to the filter state for this channel
+  /// @param sample Input sample value (normalized float)
+  /// @return Processed sample value with equalization applied
   float sample(EQSTATE &es, float sample) {
     // Locals
     float l, m, h;  // Low / Mid / High - Sample Values
@@ -324,6 +389,9 @@ class Equalizer3BandsPerChannel : public ModifyingStream {
   }
 
   /// Set frequency parameters for a specific channel
+  /// @param channel Channel index (0-based)
+  /// @param freq_low_val Low frequency cutoff in Hz
+  /// @param freq_high_val High frequency cutoff in Hz
   void setChannelFrequencies(int channel, int freq_low_val, int freq_high_val) {
     ensureChannelArraysAllocated();
     if (channel >= 0 && channel < p_cfg->channels && !freq_low.empty()) {
@@ -339,6 +407,10 @@ class Equalizer3BandsPerChannel : public ModifyingStream {
   }
 
   /// Set gain parameters for a specific channel
+  /// @param channel Channel index (0-based)
+  /// @param gain_low_val Gain multiplier for low frequencies (0.0-2.0)
+  /// @param gain_medium_val Gain multiplier for medium frequencies (0.0-2.0)
+  /// @param gain_high_val Gain multiplier for high frequencies (0.0-2.0)
   void setChannelGains(int channel, float gain_low_val, float gain_medium_val, float gain_high_val) {
     ensureChannelArraysAllocated();
     if (channel >= 0 && channel < p_cfg->channels && !gain_low.empty()) {
@@ -349,6 +421,10 @@ class Equalizer3BandsPerChannel : public ModifyingStream {
   }
 
   /// Get frequency parameters for a specific channel
+  /// @param channel Channel index (0-based)
+  /// @param freq_low_val Reference to store the low frequency cutoff
+  /// @param freq_high_val Reference to store the high frequency cutoff
+  /// @return true if successful, false if channel index is invalid
   bool getChannelFrequencies(int channel, int &freq_low_val, int &freq_high_val) {
     if (channel >= 0 && channel < p_cfg->channels && !freq_low.empty()) {
       freq_low_val = freq_low[channel];
@@ -359,6 +435,11 @@ class Equalizer3BandsPerChannel : public ModifyingStream {
   }
 
   /// Get gain parameters for a specific channel
+  /// @param channel Channel index (0-based)
+  /// @param gain_low_val Reference to store the low frequency gain
+  /// @param gain_medium_val Reference to store the medium frequency gain
+  /// @param gain_high_val Reference to store the high frequency gain
+  /// @return true if successful, false if channel index is invalid
   bool getChannelGains(int channel, float &gain_low_val, float &gain_medium_val, float &gain_high_val) {
     if (channel >= 0 && channel < p_cfg->channels && !gain_low.empty()) {
       gain_low_val = gain_low[channel];
@@ -369,14 +450,23 @@ class Equalizer3BandsPerChannel : public ModifyingStream {
     return false;
   }
 
+  /// Process and write audio data through the per-channel equalizer
+  /// @param data Pointer to audio data buffer
+  /// @param len Length of data in bytes
+  /// @return Number of bytes written
   size_t write(const uint8_t *data, size_t len) override {
     filterSamples(data, len);
     return p_print->write(data, len);
   }
 
+  /// Get available space for writing
+  /// @return Number of bytes available for writing
   int availableForWrite() override { return p_print->availableForWrite(); }
 
-  /// Provides the data from all streams mixed together
+  /// Read and process audio data through the per-channel equalizer
+  /// @param data Buffer to store processed audio data
+  /// @param len Maximum number of bytes to read
+  /// @return Number of bytes actually read and processed
   size_t readBytes(uint8_t *data, size_t len) override {
     size_t result = 0;
     if (p_stream != nullptr) {
@@ -386,26 +476,26 @@ class Equalizer3BandsPerChannel : public ModifyingStream {
     return result;
   }
 
+  /// Get available data for reading
+  /// @return Number of bytes available for reading
   int available() override {
     return p_stream != nullptr ? p_stream->available() : 0;
   }
 
  protected:
-  ConfigEqualizer3Bands cfg;
-  ConfigEqualizer3Bands *p_cfg = &cfg;
-  const float vsa = (1.0 / 4294967295.0);  // Very small amount (Denormal Fix)
-  Print *p_print = nullptr;                // support for write
-  Stream *p_stream = nullptr;              // support for write
-  int max_state_count = 0;
-
-  // Per-channel frequency settings using Vector
-  Vector<int> freq_low;
-  Vector<int> freq_high;
-
-  // Per-channel gain controls using Vector
-  Vector<float> gain_low;
-  Vector<float> gain_medium;
-  Vector<float> gain_high;
+  ConfigEqualizer3Bands cfg;                           ///< Default configuration instance
+  ConfigEqualizer3Bands *p_cfg = &cfg;                 ///< Pointer to active configuration
+  const float vsa = (1.0 / 4294967295.0);              ///< Very small amount for denormal fix
+  Print *p_print = nullptr;                            ///< Output stream for write operations
+  Stream *p_stream = nullptr;                          ///< Input/output stream for read operations
+  int max_state_count = 0;                             ///< Maximum number of allocated channel states
+
+  // Per-channel frequency and gain settings using Vector containers
+  Vector<int> freq_low;                                 ///< Low frequency cutoffs per channel (Hz)
+  Vector<int> freq_high;                                ///< High frequency cutoffs per channel (Hz)
+  Vector<float> gain_low;                               ///< Low frequency gains per channel
+  Vector<float> gain_medium;                            ///< Medium frequency gains per channel
+  Vector<float> gain_high;                              ///< High frequency gains per channel
 
   struct EQSTATE {
     // Filter #1 (Low band)