|
arduino-audio-tools
|
Analyzes audio stream quality by detecting clicks/pops, gaps/dropouts, clipping/corruption, and whether the signal is genuine audio or just noise. More...
#include <QualityAnalysisStream.h>
Public Member Functions | |
| QualityAnalysisStream ()=default | |
| QualityAnalysisStream (Print &print) | |
| QualityAnalysisStream (Stream &stream) | |
| 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 () |
| int | available () override |
| int | availableForWrite () override |
| bool | begin () override |
| bool | begin (AudioInfo info) |
| virtual void | clearNotifyAudioChange () |
| Deletes all change notify subscriptions. | |
| void | clearStats () |
| Reset all statistics and detection state. | |
| void | clearTonalitySource () |
| virtual void | end () |
| void | flush () override |
| bool | isNotifyActive () |
| Checks if the automatic AudioInfo update is active. | |
| bool | isSignalPresent () const |
| virtual | operator bool () |
| size_t | readBytes (uint8_t *data, size_t len) override |
| 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 |
| Defines the input AudioInfo. | |
| void | setCallback (QualityCallback cb) |
| Register a callback for quality issue notifications. | |
| void | setClickThreshold (float ratio) |
| Sample-to-sample jump threshold as ratio of max value (0.0 to 1.0) | |
| void | setClippingMargin (float ratio) |
| Clipping is detected when sample >= max_value * (1 - margin) | |
| void | setClippingMinSamples (int samples) |
| Minimum consecutive samples at max to count as clipping. | |
| void | setDropoutMinSamples (int samples) |
| Minimum consecutive near-silent samples to count as a dropout. | |
| void | setNoiseFloorBlockSize (int samples) |
| Number of samples per RMS/noise-floor block (default 256) | |
| void | setNoiseFloorTracking (float attack, float release) |
| void | setNotifyActive (bool flag) |
| Deactivate/Reactivate automatic AudioInfo updates: (default is active) | |
| virtual void | setOutput (AudioOutput &out) |
| Defines/Changes the output target and registers for audio change notifications. | |
| void | setOutput (Print &out) override |
| Defines/Changes the output target. | |
| void | setReporting (int period_ms, Print &output) |
| void | setSignalMargin (float db) |
| void | setSignalPresenceMinBlocks (int blocks) |
| void | setSilenceThreshold (float ratio) |
| Samples below this ratio of max value are considered silent. | |
| virtual void | setStream (AudioStream &io) |
| Defines/Changes the input & output and registers for audio change notifications. | |
| void | setStream (Stream &io) override |
| Defines/Changes the input & output. | |
| void | setTonalityBufferSize (int samples) |
| void | setTonalityEnabled (bool enabled) |
| void | setTonalityMinConfidence (float min_confidence) |
| void | setTonalitySource (FrequencyDetectorAutoCorrelation &detector, float min_confidence=0.3f, int channel=0) |
| void | setWriteBufferSize (int size) |
| const QualityStats & | stats () const |
| Access the accumulated quality statistics. | |
| float | tonalityConfidence () const |
| size_t | write (const uint8_t *data, size_t len) override |
| virtual size_t | write (uint8_t ch) override |
| virtual void | writeSilence (size_t len) |
| Writes len bytes of silence (=0). | |
Protected Member Functions | |
| void | analyze (const uint8_t *data, size_t len) |
| template<typename T > | |
| void | analyzeT (const uint8_t *buffer, size_t size) |
| void | initTonality () |
| virtual int | not_supported (int out, const char *msg="") |
| void | notifyAudioChange (AudioInfo info) |
| void | printReport () |
| void | processRmsBlock () |
| void | refillReadBuffer () |
| Refill small read buffer (e.g. 8 bytes) to avoid single byte reads when calling read() | |
| void | reportIfDue () |
| void | resetState () |
Analyzes audio stream quality by detecting clicks/pops, gaps/dropouts, clipping/corruption, and whether the signal is genuine audio or just noise.
Insert this stream into an audio pipeline to monitor signal quality in real time. Data passes through unmodified.
Signal vs. noise: the RMS level is computed over rolling blocks of samples and used to track a slowly-adapting noise-floor estimate (it follows the level down quickly but only creeps up slowly, so it isn't fooled by short loud transients). A block is considered a valid signal once its RMS level stays above the noise floor by a configurable margin (setSignalMargin()) for a minimum number of blocks (setSignalPresenceMinBlocks()). The resulting SNR estimate, noise floor, RMS level and signal-present flag are all available via stats().
Level alone cannot tell audio content apart from loud broadband noise (wind, static, hiss) - both simply exceed the noise floor. To also require the signal to be periodic/tonal (voice, music, tones) rather than random, this class owns and feeds an internal FrequencyDetectorAutoCorrelation by default (enabled out of the box); its normalized autocorrelation confidence is combined with the level gate before signal_present is raised. Autocorrelation is real CPU cost (roughly O(sample_rate^2) per second of audio) - on constrained boards/high sample rates, tune it down with setTonalityBufferSize(), or turn it off entirely with setTonalityEnabled(false) to fall back to the level-only gate. Call setTonalitySource() instead if you want to share an externally-owned/pre-fed detector (e.g. one you already run elsewhere in the pipeline) rather than the built-in one.
Results are available via stats() or through a callback.
|
default |
|
inline |
|
inline |
|
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.
|
inlineprotected |
|
inlineprotected |
|
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 MP3EncoderShine, PureDataStream, PWMAudioOutput< PWMDriverT >, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, ResampleStreamT< TInterpolator >, and SupportedRatesStream.
|
inlineoverridevirtual |
Reimplemented from BaseStream.
|
inlineoverridevirtual |
Reimplemented from BaseStream.
|
inlineoverridevirtual |
Reimplemented from BaseStream.
|
inline |
|
inlinevirtualinherited |
Deletes all change notify subscriptions.
Reimplemented in RTSPClient< TcpClient, UdpSocket >.
|
inline |
Reset all statistics and detection state.
|
inline |
Reverts to the built-in tonality detector (the default), undoing a prior setTonalitySource().
|
inlinevirtualinherited |
Reimplemented in FaustStream< DSP >, AudioMP34DT05, I2SCodecStream, MozziStream, PureDataStream, SPDIFOutput, VS1053Stream, WM8960Stream, AdaptiveResamplingStream, AudioLoRa, ESPNowStream, BufferedTaskStream, URLStreamBufferedT< T >, URLStreamBufferedT< ICYStream >, USBAudioDeviceBase, GoertzelStream, Equalizer3BandsT< T >, I2SStream, AudioStreamWrapper, TimerCallbackAudioStream, FormatConverterStream, FileLoopT< FileType >, FileLoopT< File >, EqualizerNBands< SampleT, AccT, NUM_TAPS, NUM_BANDS >, EncodedAudioStream, AudioKitStream, MiniAudioStream, PortAudioStream, StdioStream, A2DPStream, HLSStreamT< URLStream >, HttpRequest, ICYStreamT< T >, URLStream, URLStreamESP32, NRF24Stream, SPIAudioSlave, AutomaticGainControlStream, VolumeStream, AnalogAudioStream, AudioEffectStreamT< T >, AudioEffectStream, Equalizer3BandsPerChannelT< T >, ReformatBaseStream, AdapterAudioOutputToAudioStream, MemoryStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, InputMixer< T, SumT >, InputMerge< T >, CallbackStream, FilteredStream< T, TF >, FilteredStream< int16_t, int16_t >, ChannelFormatConverterStream, NumberFormatConverterStream, CatStream, QueueStream< T >, QueueStream< uint8_t >, DynamicMemoryStream, Pipeline, Pipeline::ModifyingStreamAdapter, SupportedRatesStream, AudioFFTBase, AudioBLEClient, AudioBLEClient, AudioBLEServer, AudioBLEServer, AbstractURLStream, and AudioBLEStream.
|
inlineoverridevirtual |
Reimplemented from BaseStream.
|
inlineprotected |
(Re-)initializes the built-in tonality detector to match the current AudioInfo, unless an external one was set via setTonalitySource() or the tonality gate was disabled via setTonalityEnabled(false).
|
inlineinherited |
Checks if the automatic AudioInfo update is active.
|
inline |
True while the signal is currently considered present (see setSignalMargin())
|
inlineprotectedvirtualinherited |
|
inlineprotectedinherited |
|
inlinevirtualinherited |
|
inlineprotected |
|
inlineprotected |
Called once per rms_block_size samples: updates rms_level, noise_floor, snr_db and the signal_present flag/callbacks.
|
inlineoverridevirtual |
Reimplemented from AudioStream.
|
inlinevirtualinherited |
Source to generate silence: just sets the buffer to 0.
|
inlineprotectedinherited |
Refill small read buffer (e.g. 8 bytes) to avoid single byte reads when calling read()
|
inlinevirtualinherited |
Removes a target in order not to be notified about audio changes.
Reimplemented in RTSPClient< TcpClient, UdpSocket >.
|
inlineprotected |
|
inlineprotected |
|
inlineoverridevirtual |
Defines the input AudioInfo.
Reimplemented from AudioStream.
|
inline |
Register a callback for quality issue notifications.
|
inline |
Sample-to-sample jump threshold as ratio of max value (0.0 to 1.0)
|
inline |
Clipping is detected when sample >= max_value * (1 - margin)
|
inline |
Minimum consecutive samples at max to count as clipping.
|
inline |
Minimum consecutive near-silent samples to count as a dropout.
|
inline |
Number of samples per RMS/noise-floor block (default 256)
|
inline |
How quickly the noise floor tracks a falling level (0.0-1.0, default 0.3). Higher = faster. How slowly it tracks a rising level (0.0-1.0, default 0.01). Lower = slower, so brief loud transients don't raise the estimated floor.
|
inlineinherited |
Deactivate/Reactivate automatic AudioInfo updates: (default is active)
|
inlinevirtualinherited |
Defines/Changes the output target and registers for audio change notifications.
Reimplemented in TimedStream, VolumeMeter, AudioInputMonitor, ReformatBaseStream, FormatConverterStream, and EncodedAudioStream.
|
inlineoverridevirtual |
Defines/Changes the output target.
Implements ModifyingStream.
|
inline |
Enable periodic reporting of quality KPIs
| period_ms | Reporting interval in milliseconds |
| output | Print target (e.g. Serial) |
|
inline |
dB the RMS level must stay above the noise floor to count as signal (default 6dB)
|
inline |
Consecutive blocks required above/below the margin before toggling signal_present (default 3)
|
inline |
Samples below this ratio of max value are considered silent.
|
inlinevirtualinherited |
Defines/Changes the input & output and registers for audio change notifications.
Reimplemented in VolumeMeter, AudioInputMonitor, FormatConverterStream, ReformatBaseStream, TimedStream, and EncodedAudioStream.
|
inlineoverridevirtual |
Defines/Changes the input & output.
Implements ModifyingStream.
|
inline |
Analysis buffer size (in samples) used by the built-in tonality detector. Larger = more accurate/expensive, smaller = cheaper/less accurate. Only relevant while using the built-in detector (i.e. before calling setTonalitySource()). Applied on the next begin()/setAudioInfo().
|
inline |
Enable/disable the tonality gate (enabled by default using a built-in FrequencyDetectorAutoCorrelation). When disabled, signal_present depends only on the level/noise-floor gate. Re-enabling restores the built-in detector unless an external one was set via setTonalitySource().
|
inline |
Minimum tonality confidence (0.0-1.0, default 0.3) for a block to count as signal rather than noise.
|
inline |
Overrides the built-in tonality detector with an externally-owned one that you feed yourself (e.g. because you already run it elsewhere in the pipeline). You are responsible for calling begin()/write() on it; this class only reads its confidence().
| detector | The autocorrelation detector to query. |
| min_confidence | Minimum tonality confidence (0.0-1.0, default 0.3). |
| channel | Channel to query on the detector (default 0). |
|
inlineinherited |
|
inline |
Access the accumulated quality statistics.
|
inline |
Last tonality/periodicity confidence reported by the tonality source (0 if none is set), see setTonalitySource()
|
inlineoverridevirtual |
Reimplemented from AudioStream.
|
inlineoverridevirtualinherited |
Reimplemented in MemoryStream, AudioStreamWrapper, BufferedTaskStream, RingBufferStream, BufferedStream, and URLStream.
|
inlinevirtualinherited |
Writes len bytes of silence (=0).
|
protectedinherited |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protectedinherited |
|
protectedinherited |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protectedinherited |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protectedinherited |
|
protectedinherited |
|
protected |
|
protected |
|
protected |
|
protectedinherited |