DRAFT GoerzelStream

pschatzmann · pschatzmann · commit efa7d8f66ab8 · 2025-06-30T11:30:37.000+02:00
diff --git a/src/AudioTools/CoreAudio/GoerzelStream.h b/src/AudioTools/CoreAudio/GoerzelStream.h
@@ -13,18 +13,24 @@ namespace audio_tools {
 
 /**
  * @brief Configuration for Goertzel algorithm detectors
+ * 
+ * This structure extends AudioInfo to include Goertzel-specific parameters.
+ * It defines the frequency detection behavior, audio format, and processing
+ * parameters for the Goertzel algorithm implementation.
+ * 
  * @ingroup dsp
  * @author pschatzmann
  * @copyright GPLv3
  */
 struct GoertzelConfig : public AudioInfo {
   /// Target frequency to detect in Hz (same for all channels)
   float target_frequency = 440.0f;
-  /// Number of samples to process per block (N)
+  /// Number of samples to process per block (N) - affects detection latency and accuracy
   int block_size = 205;
-  /// Detection threshold for magnitude (normalized samples, typically 0.1
-  /// to 1.0)
+  /// Detection threshold for magnitude (normalized samples, typically 0.1 to 1.0)
   float threshold = 0.5f;
+  /// Volume factor for normalization - scales input samples before processing
+  float volume = 1.0f;
 
   GoertzelConfig() = default;
   /// Copy constructor from AudioInfo
@@ -184,6 +190,15 @@ class GoertzelStream : public AudioStream {
  public:
   GoertzelStream() = default;
 
+  /**
+   * @brief Set audio format and initialize detector array
+   * 
+   * This method is called when the audio format changes. It updates the
+   * internal configuration and resizes the detector array to match the
+   * number of audio channels.
+   * 
+   * @param info Audio format information (sample rate, channels, bits per sample)
+   */
   void setAudioInfo(AudioInfo info) override {
     AudioStream::setAudioInfo(info);
     single_config.copyFrom(info);
@@ -193,7 +208,13 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Initialize with GoertzelConfig
+   * 
+   * Sets up the stream with specific Goertzel algorithm parameters.
+   * This method configures the audio format and detection parameters
+   * in one call.
+   * 
    * @param config Configuration object containing all parameters
+   * @return true if initialization successful, false otherwise
    */
   bool begin(const GoertzelConfig& config) {
     this->single_config = config;
@@ -202,6 +223,15 @@ class GoertzelStream : public AudioStream {
     return begin();
   }
 
+  /**
+   * @brief Initialize detectors for all channels
+   * 
+   * Creates and configures individual Goertzel detectors for each audio
+   * channel. Each detector will independently analyze its channel for
+   * the target frequency.
+   * 
+   * @return true if at least one channel is configured, false otherwise
+   */
   bool begin() {
     for (int i = 0; i < info.channels; i++) {
       detectors[i].begin(single_config);
@@ -219,10 +249,13 @@ class GoertzelStream : public AudioStream {
   void setOutput(Print& out) { p_print = &out; }
 
   /**
-   * @brief Set detection callback function for channel-aware frequency
-   * detection
-   * @param callback Function to call when frequency is detected, includes
-   * channel info
+   * @brief Set detection callback function for channel-aware frequency detection
+   * 
+   * Registers a callback function that will be called when the target frequency
+   * is detected on any channel. The callback receives the channel number,
+   * detected frequency, magnitude, and a user reference pointer.
+   * 
+   * @param callback Function to call when frequency is detected, includes channel info
    */
   void setChannelDetectionCallback(void (*callback)(
       int channel, float frequency, float magnitude, void* ref)) {
@@ -231,9 +264,15 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Process audio data and pass it through
-   * @param data Input audio data
-   * @param len Length of data
-   * @return Number of bytes written to output
+   * 
+   * This method receives audio data, processes it through the Goertzel
+   * detectors for frequency analysis, and then passes the unmodified
+   * data to the output stream. This allows for real-time frequency
+   * detection without affecting the audio flow.
+   * 
+   * @param data Input audio data buffer
+   * @param len Length of data in bytes
+   * @return Number of bytes written to output stream
    */
   size_t write(const uint8_t* data, size_t len) override {
     if (p_print == nullptr) return 0;
@@ -250,9 +289,15 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Read data from input stream and process it
-   * @param data Output buffer
-   * @param len Length to read
-   * @return Number of bytes read
+   * 
+   * Reads audio data from the input stream, processes it through the
+   * Goertzel detectors for frequency analysis, and returns the data
+   * to the caller. This allows for frequency detection in pull-mode
+   * audio processing.
+   * 
+   * @param data Output buffer to store read data
+   * @param len Maximum number of bytes to read
+   * @return Number of bytes actually read
    */
   size_t readBytes(uint8_t* data, size_t len) override {
     if (p_stream == nullptr) return 0;
@@ -267,7 +312,13 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Get the current magnitude for frequency detection
-   * @param channel Channel index (default: 0)
+   * 
+   * Returns the most recent magnitude calculation for the specified channel.
+   * The magnitude represents the strength of the target frequency in the
+   * last processed block of samples.
+   * 
+   * @param channel Channel index (0-based, default: 0 for mono)
+   * @return Magnitude value (0.0 if channel invalid or no detection)
    */
   float getCurrentMagnitude(int channel = 0) {
     if (channel >= 0 && channel < detectors.size()) {
@@ -278,7 +329,12 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Check if frequency is currently detected
-   * @param channel Channel index (default: 0)
+   * 
+   * Compares the current magnitude against the configured threshold
+   * to determine if the target frequency is present on the specified channel.
+   * 
+   * @param channel Channel index (0-based, default: 0 for mono)
+   * @return true if frequency detected above threshold, false otherwise
    */
   bool isFrequencyDetected(int channel = 0) {
     if (channel >= 0 && channel < detectors.size()) {
@@ -289,28 +345,47 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Get the current configuration
+   * 
+   * Returns a reference to the current Goertzel configuration, including
+   * audio format, detection parameters, and processing settings.
+   * 
+   * @return Reference to the current GoertzelConfig
    */
   const GoertzelConfig& getConfig() const { return single_config; }
 
-  /// Defines a reference to any object that should be available in the callback
+  /**
+   * @brief Set reference pointer for callback context
+   * 
+   * Defines a reference to any object that should be available in the
+   * detection callback. This allows the callback to access application
+   * context or other objects.
+   * 
+   * @param ref Pointer to user-defined context object
+   */
   void setReference(void* ref) { this->ref = ref; }
 
  protected:
-  Vector<GoertzelDetector> detectors;
-  // Configuration objects
-  GoertzelConfig single_config;
-  // Stream pointers
-  Stream* p_stream = nullptr;
-  Print* p_print = nullptr;
-
-  // Callback functions
+  // Core detection components
+  Vector<GoertzelDetector> detectors;  ///< One detector per audio channel
+  GoertzelConfig single_config;        ///< Current algorithm configuration
+  
+  // Stream I/O components
+  Stream* p_stream = nullptr;  ///< Input stream for reading audio data
+  Print* p_print = nullptr;   ///< Output stream for writing audio data
+
+  // Callback system
   void (*channel_detection_callback)(int channel, float frequency,
-                                     float magnitude, void* ref) = nullptr;
-  void* ref = this;
+                                     float magnitude, void* ref) = nullptr;  ///< User callback for detection events
+  void* ref = this;  ///< User-defined reference for callback context
 
   /**
    * @brief Helper method to check detection and call callback
-   * @param channel Channel index
+   * 
+   * Examines the magnitude from a detector and triggers the user callback
+   * if the magnitude exceeds the configured threshold. This method is
+   * called after each complete block is processed.
+   * 
+   * @param channel Channel index that completed a detection block
    */
   void checkDetection(int channel) {
     if (channel >= 0 && channel < detectors.size()) {
@@ -326,6 +401,16 @@ class GoertzelStream : public AudioStream {
 
   /**
    * @brief Template helper to process samples of a specific type
+   * 
+   * Converts audio samples from their native format to normalized floats,
+   * applies volume scaling, and feeds them to the appropriate channel
+   * detectors. This method handles the format conversion and channel
+   * distribution automatically.
+   * 
+   * @tparam T Sample data type (uint8_t, int16_t, int24_t, int32_t)
+   * @param data Raw audio data buffer
+   * @param data_len Length of data buffer in bytes
+   * @param channels Number of audio channels (for sample distribution)
    */
   template <typename T>
   void processSamplesOfType(const uint8_t* data, size_t data_len,
@@ -334,16 +419,48 @@ class GoertzelStream : public AudioStream {
     size_t num_samples = data_len / sizeof(T);
 
     for (size_t i = 0; i < num_samples; i++) {
-      float normalized = NumberConverter::toFloatT<T>(samples[i]);
+      // Convert to normalized float and apply volume scaling
+      float normalized = clip(NumberConverter::toFloatT<T>(samples[i]) * single_config.volume);
+      // Distribute samples to channels in interleaved format
       int channel = i % channels;
       if (detectors[channel].processSample(normalized)) {
         checkDetection(channel);
       }
     }
   }
 
+  /**
+   * @brief Clip audio values to prevent overflow
+   * 
+   * Ensures that normalized audio samples stay within the valid range
+   * of [-1.0, 1.0] to prevent algorithm instability.
+   * 
+   * @param value Input audio sample value
+   * @return Clipped value in range [-1.0, 1.0]
+   */
+  float clip(float value) {
+    // Clip the value to the range [-1.0, 1.0]
+    if (value > 1.0f) return 1.0f;
+    if (value < -1.0f) return -1.0f;
+    return value;
+  }
+
   /**
    * @brief Generic sample processing method for both write and readBytes
+   * 
+   * This method serves as the central dispatcher for audio sample processing.
+   * It examines the configured sample format and routes the data to the
+   * appropriate type-specific processing method. This approach eliminates
+   * code duplication between write() and readBytes() methods.
+   * 
+   * Supported formats:
+   * - 8-bit: Unsigned samples (0-255)
+   * - 16-bit: Signed samples (-32768 to 32767)  
+   * - 24-bit: Signed samples in 3-byte packed format
+   * - 32-bit: Signed samples (-2^31 to 2^31-1)
+   * 
+   * @param data Raw audio data buffer
+   * @param data_len Length of data buffer in bytes
    */
   void processSamples(const uint8_t* data, size_t data_len) {
     int channels = single_config.channels;
