Analyzes audio stream quality by detecting clicks/pops, gaps/dropouts, and clipping/corruption. More...

#include <QualityAnalysisStream.h>

Inheritance diagram for QualityAnalysisStream:

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.

virtual void	end ()

virtual void	flush () override

bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.

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	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)

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	setSilenceThreshold (float ratio)
	Samples below this ratio of max value are considered silent.

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	setWriteBufferSize (int size)

const QualityStats &	stats () const
	Access the accumulated quality statistics.

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)

virtual int	not_supported (int out, const char *msg="")

void	notifyAudioChange (AudioInfo info)

void	printReport ()

void	refillReadBuffer ()
	Refill small read buffer (e.g. 8 bytes) to avoid single byte reads when calling read()

void	reportIfDue ()

void	resetState ()

Protected Attributes
int	_timeout = 10

QualityCallback	callback = nullptr

float	click_threshold = 0.5f

float	clipping_margin = 0.01f

int	clipping_min_samples = 3

int	consecutive_clipped = 0

int	consecutive_silent = 0

int	dropout_min_samples = 10

bool	has_prev_sample = false

bool	in_clipping = false

bool	in_dropout = false

AudioInfo	info

bool	is_notify_active = true

uint32_t	last_report_time = 0

float	max_value = 32767.0f

Vector< AudioInfoSupport * >	notify_vector

Print *	p_out = nullptr

Print *	p_report = nullptr

Stream *	p_stream = nullptr

Vector< float >	prev_sample

int	report_period_ms = 0

float	silence_threshold = 0.01f

QualityStats	stats_data

RingBuffer< uint8_t >	tmp_in {0}

RingBuffer< uint8_t >	tmp_out {0}

int	write_buffer_size = MAX_SINGLE_CHARS

Detailed Description

Analyzes audio stream quality by detecting clicks/pops, gaps/dropouts, and clipping/corruption.

Insert this stream into an audio pipeline to monitor signal quality in real time. Data passes through unmodified.

Clicks/Pops: detected when the sample-to-sample delta exceeds a configurable threshold (as a ratio of the maximum sample value).
Gaps/Dropouts: detected when consecutive near-zero samples exceed a configurable minimum length.
Clipping: detected when consecutive samples are at (or near) the maximum representable value.

Results are available via stats() or through a callback.

Author: Phil Schatzmann

Copyright: GPLv3

Constructor & Destructor Documentation

◆ QualityAnalysisStream() [1/3]

QualityAnalysisStream ( )

default

◆ QualityAnalysisStream() [2/3]

QualityAnalysisStream ( Print & print )

inline

◆ QualityAnalysisStream() [3/3]

QualityAnalysisStream ( Stream & stream )

inline

Member Function Documentation

◆ addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport & bi )

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.

◆ analyze()

void analyze	(	const uint8_t *	data,
		size_t	len
	)

inlineprotected

◆ analyzeT()

template<typename T >

void analyzeT	(	const uint8_t *	buffer,
		size_t	size
	)

inlineprotected

◆ audioInfo()

virtual AudioInfo audioInfo ( )

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 >.

◆ audioInfoOut()

virtual AudioInfo audioInfoOut ( )

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, and ResampleStreamT< TInterpolator >.

◆ available()

int available ( )

inlineoverridevirtual

Reimplemented from BaseStream.

◆ availableForWrite()

int availableForWrite ( )

inlineoverridevirtual

Reimplemented from BaseStream.

◆ begin() [1/2]

bool begin ( )

inlineoverridevirtual

Reimplemented from BaseStream.

◆ begin() [2/2]

bool begin ( AudioInfo info )

inline

◆ clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ clearStats()

void clearStats ( )

inline

Reset all statistics and detection state.

◆ end()

virtual void end ( )

inlinevirtualinherited

Reimplemented in FaustStream< DSP >, AudioMP34DT05, I2SCodecStream, MozziStream, PureDataStream, SPDIFOutput, VS1053Stream, WM8960Stream, AdaptiveResamplingStream, AudioLoRa, ESPNowStream, BufferedTaskStream, URLStreamBufferedT< T >, URLStreamBufferedT< ICYStream >, USBAudioDeviceBase, Equalizer3Bands, I2SStream, AudioStreamWrapper, TimerCallbackAudioStream, FormatConverterStream, GoertzelStream, FileLoopT< FileType >, FileLoopT< File >, EqualizerNBands< SampleT, AccT, NUM_TAPS, NUM_BANDS >, LoRaStream, EncodedAudioStream, AudioFFTBase, AudioKitStream, MiniAudioStream, PortAudioStream, StdioStream, A2DPStream, HLSStreamT< URLStream >, HttpRequest, ICYStreamT< T >, URLStream, URLStreamESP32, NRF24Stream, SPIAudioSlave, AnalogAudioStream, AudioEffectStreamT< T >, Equalizer3BandsPerChannel, 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, VolumeStream, AudioBLEClient, AudioBLEClient, AudioBLEServer, AudioBLEServer, AbstractURLStream, and AudioBLEStream.

◆ flush()

virtual void flush ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in PureDataStream, URLStreamBufferedT< T >, URLStreamBufferedT< ICYStream >, ReformatBaseStream, AudioStreamWrapper, ResampleStream, EncodedAudioStream, URLStream, BufferedTaskStream, I2SStream, MemoryStream, RingBufferStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, and BufferedStream.

◆ isNotifyActive()

bool isNotifyActive ( )

inlineinherited

Checks if the automatic AudioInfo update is active.

◆ not_supported()

virtual int not_supported	(	int	out,
		const char *	msg = `""`
	)

inlineprotectedvirtualinherited

◆ notifyAudioChange()

void notifyAudioChange ( AudioInfo info )

inlineprotectedinherited

◆ operator bool()

virtual operator bool ( )

inlinevirtualinherited

Reimplemented in A2DPStream, ICYStreamT< T >, AudioBLEStream, AudioFFTBase, PortAudioStream, URLStream, USBAudioDeviceBase, I2SStream, AdapterAudioOutputToAudioStream, TimedStream, MemoryStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, and Pipeline.

◆ printReport()

void printReport ( )

inlineprotected

◆ readBytes()

size_t readBytes	(	uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Reimplemented from AudioStream.

◆ readSilence()

virtual size_t readSilence	(	uint8_t *	buffer,
		size_t	length
	)

inlinevirtualinherited

Source to generate silence: just sets the buffer to 0.

◆ refillReadBuffer()

void refillReadBuffer ( )

inlineprotectedinherited

Refill small read buffer (e.g. 8 bytes) to avoid single byte reads when calling read()

◆ removeNotifyAudioChange()

virtual bool removeNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Removes a target in order not to be notified about audio changes.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ reportIfDue()

void reportIfDue ( )

inlineprotected

◆ resetState()

void resetState ( )

inlineprotected

◆ setAudioInfo()

void setAudioInfo ( AudioInfo info )

inlineoverridevirtual

Defines the input AudioInfo.

Reimplemented from AudioStream.

◆ setCallback()

void setCallback ( QualityCallback cb )

inline

Register a callback for quality issue notifications.

◆ setClickThreshold()

void setClickThreshold ( float ratio )

inline

Sample-to-sample jump threshold as ratio of max value (0.0 to 1.0)

◆ setClippingMargin()

void setClippingMargin ( float ratio )

inline

Clipping is detected when sample >= max_value * (1 - margin)

◆ setClippingMinSamples()

void setClippingMinSamples ( int samples )

inline

Minimum consecutive samples at max to count as clipping.

◆ setDropoutMinSamples()

void setDropoutMinSamples ( int samples )

inline

Minimum consecutive near-silent samples to count as a dropout.

◆ setNotifyActive()

void setNotifyActive ( bool flag )

inlineinherited

Deactivate/Reactivate automatic AudioInfo updates: (default is active)

◆ setOutput() [1/2]

void setOutput ( AudioOutput & out )

inlinevirtual

Defines/Changes the output target and registers for audio change notifications.

Reimplemented from ModifyingStream.

◆ setOutput() [2/2]

void setOutput ( Print & out )

inlineoverridevirtual

Defines/Changes the output target.

Implements ModifyingStream.

◆ setReporting()

void setReporting	(	int	period_ms,
		Print &	output
	)

inline

Enable periodic reporting of quality KPIs

Parameters

period_ms	Reporting interval in milliseconds
output	Print target (e.g. Serial)

◆ setSilenceThreshold()

void setSilenceThreshold ( float ratio )

inline

Samples below this ratio of max value are considered silent.

◆ setStream() [1/2]

void setStream ( AudioStream & io )

inlinevirtual

Defines/Changes the input & output and registers for audio change notifications.

Reimplemented from ModifyingStream.

◆ setStream() [2/2]

void setStream ( Stream & in )

inlineoverridevirtual

Defines/Changes the input & output.

Implements ModifyingStream.

◆ setWriteBufferSize()

void setWriteBufferSize ( int size )

inlineinherited

◆ stats()

const QualityStats & stats ( ) const

inline

Access the accumulated quality statistics.

◆ write() [1/2]

size_t write	(	const uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Reimplemented from AudioStream.

◆ write() [2/2]

virtual size_t write ( uint8_t ch )

inlineoverridevirtualinherited

Reimplemented in MemoryStream, AudioStreamWrapper, BufferedTaskStream, RingBufferStream, BufferedStream, and URLStream.

◆ writeSilence()

virtual void writeSilence ( size_t len )

inlinevirtualinherited

Writes len bytes of silence (=0).

Member Data Documentation

◆ _timeout

int _timeout = 10

protectedinherited

◆ callback

QualityCallback callback = nullptr

protected

◆ click_threshold

float click_threshold = 0.5f

protected

◆ clipping_margin

float clipping_margin = 0.01f

protected

◆ clipping_min_samples

int clipping_min_samples = 3

protected

◆ consecutive_clipped

int consecutive_clipped = 0

protected

◆ consecutive_silent

int consecutive_silent = 0

protected

◆ dropout_min_samples

int dropout_min_samples = 10

protected

◆ has_prev_sample

bool has_prev_sample = false

protected

◆ in_clipping

bool in_clipping = false

protected

◆ in_dropout

bool in_dropout = false

protected

◆ info

AudioInfo info

protectedinherited

◆ is_notify_active

bool is_notify_active = true

protectedinherited

◆ last_report_time

uint32_t last_report_time = 0

protected

◆ max_value

float max_value = 32767.0f

protected

◆ notify_vector

Vector<AudioInfoSupport*> notify_vector

protectedinherited

◆ p_out

Print* p_out = nullptr

protected

◆ p_report

Print* p_report = nullptr

protected

◆ p_stream

Stream* p_stream = nullptr

protected

◆ prev_sample

Vector<float> prev_sample

protected

◆ report_period_ms

int report_period_ms = 0

protected

◆ silence_threshold

float silence_threshold = 0.01f

protected

◆ stats_data

QualityStats stats_data

protected

◆ tmp_in

RingBuffer<uint8_t> tmp_in {0}

protectedinherited

◆ tmp_out

RingBuffer<uint8_t> tmp_out {0}

protectedinherited

◆ write_buffer_size

int write_buffer_size = MAX_SINGLE_CHARS

protectedinherited

The documentation for this class was generated from the following file:

src/AudioTools/CoreAudio/QualityAnalysisStream.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QualityAnalysisStream() [1/3]

◆ QualityAnalysisStream() [2/3]

◆ QualityAnalysisStream() [3/3]

Member Function Documentation

◆ addNotifyAudioChange()

◆ analyze()

◆ analyzeT()

◆ audioInfo()

◆ audioInfoOut()

◆ available()

◆ availableForWrite()

◆ begin() [1/2]

◆ begin() [2/2]

◆ clearNotifyAudioChange()

◆ clearStats()

◆ end()

◆ flush()

◆ isNotifyActive()

◆ not_supported()

◆ notifyAudioChange()

◆ operator bool()

◆ printReport()

◆ readBytes()

◆ readSilence()

◆ refillReadBuffer()

◆ removeNotifyAudioChange()

◆ reportIfDue()

◆ resetState()

◆ setAudioInfo()

◆ setCallback()

◆ setClickThreshold()

◆ setClippingMargin()

◆ setClippingMinSamples()

◆ setDropoutMinSamples()

◆ setNotifyActive()

◆ setOutput() [1/2]

◆ setOutput() [2/2]

◆ setReporting()

◆ setSilenceThreshold()

◆ setStream() [1/2]

◆ setStream() [2/2]

◆ setWriteBufferSize()

◆ stats()

◆ write() [1/2]

◆ write() [2/2]

◆ writeSilence()

Member Data Documentation

◆ _timeout

◆ callback

◆ click_threshold

◆ clipping_margin

◆ clipping_min_samples

◆ consecutive_clipped

◆ consecutive_silent

◆ dropout_min_samples

◆ has_prev_sample

◆ in_clipping

◆ in_dropout

◆ info

◆ is_notify_active

◆ last_report_time

◆ max_value

◆ notify_vector

◆ p_out

◆ p_report

◆ p_stream

◆ prev_sample

◆ report_period_ms

◆ silence_threshold

◆ stats_data

◆ tmp_in

◆ tmp_out

◆ write_buffer_size