arduino-audio-tools
|
AudioStream-based multi-frequency Goertzel detector for real-time audio analysis. More...
#include <GoerzelStream.h>
Public Member Functions | |
GoertzelStream (AudioOutput &out) | |
GoertzelStream (AudioStream &io) | |
GoertzelStream (Print &out) | |
GoertzelStream (Stream &io) | |
void | addFrequency (float freq) |
Add a frequency to the detection list. | |
void | addFrequency (float freq, void *ref) |
Add a frequency to the detection list with a custom reference pointer. | |
virtual void | addNotifyAudioChange (AudioInfoSupport &bi) |
Adds target to be notified about audio changes. | |
virtual AudioInfo | audioInfo () override |
provides the actual input AudioInfo | |
virtual AudioInfo | audioInfoOut () |
virtual int | available () override |
virtual int | availableForWrite () override |
bool | begin () |
Initialize detectors for all frequencies. | |
bool | begin (GoertzelConfig config) |
Initialize with GoertzelConfig. | |
virtual void | clearNotifyAudioChange () |
Deletes all change notify subscriptions. | |
GoertzelConfig | defaultConfig () |
Returns a default GoertzelConfig instance with standard parameters. | |
void | end () |
Stop the Goertzel detectors and clear resources. | |
virtual void | flush () override |
const GoertzelConfig & | getConfig () const |
Get the current configuration. | |
GoertzelDetector & | getDetector (int no) |
Get detector for specific channel. | |
bool | isNotifyActive () |
Checks if the automatic AudioInfo update is active. | |
virtual | operator bool () |
size_t | readBytes (uint8_t *data, size_t len) override |
Read data from input stream and process it. | |
virtual size_t | readSilence (uint8_t *buffer, size_t length) |
Source to generate silence: just sets the buffer to 0. | |
virtual bool | removeNotifyAudioChange (AudioInfoSupport &bi) |
Removes a target in order not to be notified about audio changes. | |
void | setAudioInfo (AudioInfo info) override |
Set audio format and initialize detector array. | |
void | setFrequencyDetectionCallback (void(*callback)(float frequency, float magnitude, void *ref)) |
Set detection callback function for channel-aware frequency detection. | |
void | setNotifyActive (bool flag) |
Deactivate/Reactivate automatic AudioInfo updates: (default is active) | |
void | setOutput (AudioOutput &out) |
Defines/Changes the output target. | |
void | setOutput (Print &out) |
Defines/Changes the output target. | |
void | setReference (void *ref) |
Set reference pointer for callback context. | |
void | setStream (AudioStream &io) |
Defines/Changes the input & output. | |
void | setStream (Stream &in) |
Defines/Changes the input & output. | |
void | setWriteBufferSize (int size) |
size_t | write (const uint8_t *data, size_t len) override |
Process audio data and pass it through. | |
virtual size_t | write (uint8_t ch) override |
virtual void | writeSilence (size_t len) |
Writes len bytes of silence (=0). | |
Protected Member Functions | |
void | checkDetection (GoertzelDetector &detector) |
Check if a detector has detected its frequency and invoke callback. | |
float | clip (float value) |
Clip audio values to prevent overflow. | |
virtual int | not_supported (int out, const char *msg="") |
void | notifyAudioChange (AudioInfo info) |
void | processSamples (const uint8_t *data, size_t data_len) |
Generic sample processing method for both write and readBytes. | |
template<typename T > | |
void | processSamplesOfType (const uint8_t *data, size_t data_len, int channels) |
Template helper to process samples of a specific type. | |
void | refillReadBuffer () |
Protected Attributes | |
int | _timeout = 10 |
GoertzelConfig | default_config |
Current algorithm configuration. | |
Vector< GoertzelDetector > | detectors |
One detector per frequency in frequencies. | |
Vector< float > | frequencies |
List of frequencies to detect. | |
void(* | frequency_detection_callback )(float frequency, float magnitude, void *ref) |
User callback for detection events. | |
AudioInfo | info |
bool | is_notify_active = true |
Vector< AudioInfoSupport * > | notify_vector |
Print * | p_print = nullptr |
Output stream for writing audio data. | |
Stream * | p_stream = nullptr |
Input stream for reading audio data. | |
void * | ref = this |
User-defined reference for callback context. | |
Vector< void * > | references |
List of frequencies to detect. | |
size_t | sample_no = 0 |
Sample counter for channel selection. | |
RingBuffer< uint8_t > | tmp_in {0} |
RingBuffer< uint8_t > | tmp_out {0} |
int | write_buffer_size = MAX_SINGLE_CHARS |
AudioStream-based multi-frequency Goertzel detector for real-time audio analysis.
GoertzelStream enables efficient detection of one or more target frequencies in a continuous audio stream. It acts as a transparent filter: audio data flows through unchanged, while the class analyzes the signal for specified tones.
Key Features:
Usage:
Supported sample formats:
|
inline |
Add a frequency to the detection list.
freq | Frequency in Hz to add to the detection list |
|
inline |
Add a frequency to the detection list with a custom reference pointer.
This method allows you to associate a user-defined reference (context pointer) with a specific frequency. The reference will be passed to the detection callback when this frequency is detected, enabling per-frequency context handling.
freq | Frequency in Hz to add to the detection list |
ref | Pointer to user-defined context object for this frequency |
|
inlinevirtualinherited |
Adds target to be notified about audio changes.
Reimplemented in CodecNOP, EncodedAudioOutput, EncodedAudioStream, AACDecoderFDK, DecoderBasic, CodecChain, MP3DecoderHelix, MP3DecoderMAD, OggContainerDecoder, RTSPClient< TcpClient, UdpSocket >, Pipeline, and Pipeline::ModifyingStreamAdapter.
|
inlineoverridevirtualinherited |
provides the actual input AudioInfo
Implements AudioInfoSupport.
Reimplemented in JupyterAudioT< T >, MozziStream, TimerCallbackAudioStream, EncodedAudioStream, PureDataStream, AdapterAudioOutputToAudioStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, and InputMerge< T >.
|
inlinevirtualinherited |
provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream
Reimplemented in PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.
|
inlineoverridevirtualinherited |
Reimplemented from Stream.
Reimplemented in AudioKitStream, AudioFFTBase, I2SCodecStream, TfLiteAudioStream, A2DPStream, HLSStreamT< URLStream >, ICYStreamT< T >, BufferedTaskStream, UDPStream, Equalizer3Bands, Equalizer3BandsPerChannel, I2SStream, TimedStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, BufferedStream, ConverterStream< T >, InputMerge< T >, FrequencyDetectorAutoCorrelation, FrequencyDetectorZeroCrossing, Pipeline::ModifyingStreamAdapter, and VolumeStream.
|
inlineoverridevirtualinherited |
Reimplemented from Print.
Reimplemented in UDPStream, AudioFFTBase, I2SCodecStream, A2DPStream, AbstractURLStream, URLStreamESP32, Equalizer3Bands, Equalizer3BandsPerChannel, I2SStream, MeasuringStream, ProgressStream, FrequencyDetectorAutoCorrelation, FrequencyDetectorZeroCrossing, and VolumeStream.
|
inlinevirtual |
Initialize detectors for all frequencies.
Creates and configures individual Goertzel detectors for frequency. Each detector will independently for the target frequency.
Reimplemented from BaseStream.
|
inline |
Initialize with GoertzelConfig.
Sets up the stream with specific Goertzel algorithm parameters. This method configures the audio format and detection parameters in one call.
config | Configuration object containing all parameters |
|
inlinevirtualinherited |
Deletes all change notify subscriptions.
Reimplemented in RTSPClient< TcpClient, UdpSocket >.
|
inlineprotected |
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.
value | Input audio sample value |
|
inline |
Returns a default GoertzelConfig instance with standard parameters.
This utility method provides a convenient way to obtain a default configuration for the Goertzel algorithm. The returned config can be customized before use.
|
inlinevirtual |
Stop the Goertzel detectors and clear resources.
Reimplemented from BaseStream.
|
inlineoverridevirtualinherited |
Reimplemented from Print.
Reimplemented in ResampleStream, BufferedTaskStream, and BufferedStream.
|
inline |
Get the current configuration.
Returns a reference to the current Goertzel configuration, including audio format, detection parameters, and processing settings.
|
inline |
Get detector for specific channel.
Provides access to the GoertzelDetector instance for a given channel. This allows for direct inspection of detector state and results.
no | Channel index (0-based) |
|
inlinevirtualinherited |
Reimplemented in A2DPStream, ICYStreamT< T >, I2SStream, MemoryStream, and Pipeline.
|
inlineprotected |
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:
data | Raw audio data buffer |
data_len | Length of data buffer in bytes |
|
inlineprotected |
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.
T | Sample data type (uint8_t, int16_t, int24_t, int32_t) |
data | Raw audio data buffer |
data_len | Length of data buffer in bytes |
channels | Number of audio channels (for sample distribution) |
|
inlineoverridevirtual |
Read data from input stream and process it.
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.
data | Output buffer to store read data |
len | Maximum number of bytes to read |
Reimplemented from AudioStream.
|
inlinevirtualinherited |
Removes a target in order not to be notified about audio changes.
Reimplemented in RTSPClient< TcpClient, UdpSocket >.
|
inlineoverridevirtual |
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.
info | Audio format information (sample rate, channels, bits per sample) |
Reimplemented from AudioStream.
|
inline |
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.
callback | Function to call when frequency is detected, includes channel info |
|
inline |
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.
ref | Pointer to user-defined context object |
|
inlineoverridevirtual |
Process audio data and pass it through.
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.
data | Input audio data buffer |
len | Length of data in bytes |
If there is no output stream, we just return the length
Reimplemented from AudioStream.
|
inlineoverridevirtualinherited |
Reimplemented in BufferedTaskStream, and BufferedStream.
|
protected |
User callback for detection events.