Checks whether the output signal latency is below a specified amount. More...

#include <hart_latency_below.hpp>

Inheritance diagram for LatencyBelow< SampleType >:

Public Types
enum class	Method { onset , correlation }
	Selects the method used to detect latency. More...

Public Member Functions
	LatencyBelow (double maxLatencySeconds, Method method=Method::onset, double threshold=hart::nan< double >(), SilencePolicy silencePolicy=SilencePolicy::strict)
	Creates a matcher that expects latency between input and output below a specified value.

	LatencyBelow (const LatencyBelow &other)

	LatencyBelow (LatencyBelow &&other) noexcept=default

LatencyBelow &	operator= (const LatencyBelow &other)

LatencyBelow &	operator= (LatencyBelow &&other) noexcept=default

	~LatencyBelow () override=default

void	prepare (double sampleRateHz, size_t numInputChannels, size_t numOutputChannels, size_t maxBlockSizeFrames) override
	Prepare for processing It is guaranteed that all subsequent process() calls will be in line with the arguments received in this callback. This callback is guaranteed to be called after canOperatePerBlock() If any of the values supplied by this callback are not supported by the matcher, it is expected to act as if the match has failed when match() gets called.

bool	canOperatePerBlock () const override
	Tells the host if it can operate on a block-by-block basis.

void	reset () override
	Resets the matcher to its initial state.

bool	supportsChannelLayout (size_t numInputChannels, size_t numOutputChannels) const override
	Tells the host whether this Matcher is capable of operating on audio with a specific number of channels.

bool	match (AnalysisContext< SampleType > context) override
	Tells the host if the piece of audio satisfies Matcher's condition or not.

MatcherFailureDetails	getFailureDetails () const override
	Returns a description of why the match has failed.

void	represent (std::ostream &stream) const override
	Makes a text representation of this Matcher for test failure outputs.

Public Member Functions inherited from Matcher< SampleType, LatencyBelow< SampleType > >
virtual std::unique_ptr< MatcherBase< SampleType > >	copy () const override
	Returns a smart pointer with a copy of this object.

virtual std::unique_ptr< MatcherBase< SampleType > >	move () override
	Returns a smart pointer with a moved instance of this object.

LatencyBelow< SampleType > &	atChannels (std::initializer_list< size_t > channelsToMatch) &
	Makes this matcher check only specific channels, and ignore the rest.

LatencyBelow< SampleType > &&	atChannels (std::initializer_list< size_t > channelsToMatch) &&
	Makes this matcher check only specific channels, and ignore the rest.

LatencyBelow< SampleType > &	atChannel (size_t channelToMatch) &
	Makes this matcher check only one specific channel, and ignore the rest.

LatencyBelow< SampleType > &&	atChannel (size_t channelToMatch) &&
	Makes this matcher check only one specific channel, and ignore the rest.

LatencyBelow< SampleType > &	atAllChannels () &
	Makes this matcher check all channels.

LatencyBelow< SampleType > &&	atAllChannels () &&
	Makes this matcher check all channels.

LatencyBelow< SampleType > &	atAllChannelsExcept (std::initializer_list< size_t > channelsToSkip) &
	Makes this matcher check only specific channels, and ignore the rest.

LatencyBelow< SampleType > &&	atAllChannelsExcept (std::initializer_list< size_t > channelsToSkip) &&
	Makes this matcher check only specific channels, and ignore the rest.

Public Member Functions inherited from MatcherBase< SampleType >
virtual	~MatcherBase ()=default

	HART_DEPRECATED ("This method is deprecated. Switch to the one that uses AnalysisContext instead.") virtual bool match(const AudioBuffer< SampleType > &inputAudio
	Tells the host if the piece of audio satisfies Matcher's condition or not.

return	match (analysisContext)

virtual bool	supportsSampleRate (double) const
	Tells whether this Matcher supports given sample rate.

void	prepareWithActiveChannels (double sampleRateHz, size_t numInputChannels, size_t numOutputChannels, size_t maxBlockSizeFrames)
	Prepare for processing, meant to be called by a host.

void	representWithActiveChannels (std::ostream &stream) const
	Makes a text representation of this Matcher with optional "atChannels" appendix.

Additional Inherited Members
Public Attributes inherited from MatcherBase< SampleType >
const AudioBuffer< SampleType > &	observedOutputAudio

Protected Member Functions inherited from MatcherBase< SampleType >
bool	appliesToChannel (size_t channel)
	Indicates whether this matcher should check a specific channel.

ChannelFlags	getChannelFlags () const
	Returns flags for the channels that the matcher should apply to.

Protected Attributes inherited from MatcherBase< SampleType >
ChannelFlags	m_channelsToMatch {true}

Related Symbols inherited from Matcher< SampleType, LatencyBelow< SampleType > >
std::ostream &	operator<< (std::ostream &stream, const MatcherBase< SampleType > &matcher)
	Prints readable text representation of the Matcher object into the I/O stream.

Detailed Description

template<typename SampleType>
class hart::LatencyBelow< SampleType >

Checks whether the output signal latency is below a specified amount.

Compares input and output audio and measures the observed latency between them. In a multi-channel setup, latency is measured independently for every applicable channel, and the largest detected latency is used.

The latency detection method is selected via Method:

Method::onset detects latency as a difference between the first threshold crossing in the input and output signals.
Method::correlation uses normalized cross-correlation and finds the lag that best aligns the output waveform to the input.

SilencePolicy defines how the matcher behaves when latency cannot be reliably determined on one or more channels.

Template Parameters

SampleType Type of audio samples, typically float or double

Definition at line 34 of file hart_latency_below.hpp.

Member Enumeration Documentation

◆ Method

template<typename SampleType >

enum class Method

strong

Selects the method used to detect latency.

Enumerator
onset	Detect latency from the first threshold crossing in input and output.
correlation	Detect latency using best waveform alignment via cross-correlation.

Definition at line 39 of file hart_latency_below.hpp.

Constructor & Destructor Documentation

◆ LatencyBelow() [1/3]

template<typename SampleType >

LatencyBelow	(	double	maxLatencySeconds,
		Method	method = `Method::onset`,
		double	threshold = `hart::nan<double>()`,
		SilencePolicy	silencePolicy = `SilencePolicy::strict`
	)

inline

Creates a matcher that expects latency between input and output below a specified value.

Parameters

maxLatencySeconds	Maximum allowed detected latency in seconds
method	Latency detection method. See `Method` for details.
threshold	Method-specific detection threshold: for `Method::onset`, this is the minimal sample level in dB required to detect onset. for `Method::correlation`, this is the minimum absolute correlation required for latency detection to be considered valid

NaN value will trigger a sensible method-specific default, namely:

-120 (in dB) as sample value threshold for onset-based detection
0.5 as absolute normalized cross-correlation value threshold for correlation-based detection
Parameters

silencePolicy Defines how channels with insufficient measurable signal are handled:
SilencePolicy::strict fails if any applicable channel cannot produce a valid latency estimate
SilencePolicy::relaxed ignores such channels and uses valid ones only

Definition at line 59 of file hart_latency_below.hpp.

◆ LatencyBelow() [2/3]

template<typename SampleType >

LatencyBelow ( const LatencyBelow< SampleType > & other )

inline

Definition at line 95 of file hart_latency_below.hpp.

◆ LatencyBelow() [3/3]

template<typename SampleType >

LatencyBelow ( LatencyBelow< SampleType > && other )

defaultnoexcept

◆ ~LatencyBelow()

template<typename SampleType >

~LatencyBelow ( )

overridedefault

Member Function Documentation

◆ operator=() [1/2]

template<typename SampleType >

LatencyBelow & operator= ( const LatencyBelow< SampleType > & other )

inline

Definition at line 111 of file hart_latency_below.hpp.

◆ operator=() [2/2]

template<typename SampleType >

LatencyBelow & operator= ( LatencyBelow< SampleType > && other )

defaultnoexcept

◆ prepare()

template<typename SampleType >

void prepare	(	double	sampleRateHz,
		size_t	numInputChannels,
		size_t	numOutputChannels,
		size_t	maxBlockSizeFrames
	)

inlineoverridevirtual

Prepare for processing It is guaranteed that all subsequent process() calls will be in line with the arguments received in this callback. This callback is guaranteed to be called after canOperatePerBlock() If any of the values supplied by this callback are not supported by the matcher, it is expected to act as if the match has failed when match() gets called.

Parameters

sampleRateHz	sample rate at which the audio should be interpreted
numInputChannels	Number of channels in the input (reference) audio
numOutputChannels	Number of channels in the output (observed) audio
maxBlockSizeFrames	Maximum block size in frames (samples)

Implements MatcherBase< SampleType >.

Definition at line 135 of file hart_latency_below.hpp.

◆ canOperatePerBlock()

template<typename SampleType >

bool canOperatePerBlock ( ) const

inlineoverridevirtual

Tells the host if it can operate on a block-by-block basis.

Some types of conditions absolutely require having a full piece of audio to produce an appropriate response. For example, hart::PeaksAt matcher. Those types of matchers will return false on this callback. Matcher is guaranteed to receive a full piece of audio if this callback has returned false. Otherwise, it may receive audio either block-by-block basis, or still get a full piece of audio, if the host decides to do so.

Implements MatcherBase< SampleType >.

Definition at line 146 of file hart_latency_below.hpp.

◆ reset()

template<typename SampleType >

void reset ( )

inlineoverridevirtual

Resets the matcher to its initial state.

Reimplemented from MatcherBase< SampleType >.

Definition at line 151 of file hart_latency_below.hpp.

◆ supportsChannelLayout()

template<typename SampleType >

bool supportsChannelLayout	(	size_t	,
		size_t
	)		const

inlineoverridevirtual

Tells the host whether this Matcher is capable of operating on audio with a specific number of channels.

It is guaranteed that the matcher will not receive unsupported number of channels in match(). This method is guaranteed to be called at least once before prepare()

Parameters

numInputChannels	Number of channels in input (reference) buffer that will need to be processed
numOutputChannels	Number of channels in output (observed) buffer that will need to be processed

Returns: true if signal is capable of processing audio with requested number of channels, false otherwise

Reimplemented from MatcherBase< SampleType >.

Definition at line 157 of file hart_latency_below.hpp.

◆ match()

template<typename SampleType >

bool match ( AnalysisContext< SampleType > analysisContext )

inlineoverridevirtual

Tells the host if the piece of audio satisfies Matcher's condition or not.

It is guaranteed to be called only after prepare(), or not be called at all. It is guaranteed to be handed a pair of AudioBuffers in line with values set by the last prepare() call. If canOperatePerBlock() has returned false, this callback is guaranteed to be handed a full piece of audio to check. Otherwise, it may still get a full piece of audio, or get data on a block-by-block basis.

Parameters

analysisContext Carries everything matcher should know about the input and output audio.

Returns: true if the audio satisfies the Matcher's condition, false otherwise

Reimplemented from MatcherBase< SampleType >.

Definition at line 162 of file hart_latency_below.hpp.

◆ getFailureDetails()

template<typename SampleType >

MatcherFailureDetails getFailureDetails ( ) const

inlineoverridevirtual

Returns a description of why the match has failed.

It is guaranteed to be called strictly after calling match(), or not called at all

Note: This method is a callback for the test host, so you probably don't need to call it yourself ever. If you're making a custom matcher, use it to communicate the data with test host.

Return values

MatcherFailureDetails::frame	Index of frame at which the match has failed
MatcherFailureDetails::channel	Index of channel at which the failure was detected
MatcherFailureDetails::description	Readable description of why the match has failed. Do not include the value of observed frame value or its timing in the description, as well as any of values printed by represent(), as all of this will be added to the output anyway. Also, query hart::CLIConfig for number of displayed decimal places, whenever applicable.

See also: MatcherFailureDetails

Implements MatcherBase< SampleType >.

Definition at line 175 of file hart_latency_below.hpp.

◆ represent()

template<typename SampleType >

void represent ( std::ostream & stream ) const

inlineoverridevirtual

Makes a text representation of this Matcher for test failure outputs.

It is strongly encouraged to follow python's repr() conventions for returned text - basically, put something like "MyClass(value1, value2)" (with no quotes) into the stream whenever possible, or "<Readable info in angled brackets>" otherwise. Also, use built-in stream manipulators like hart::dbPrecision wherever applicable. Use HART_DEFINE_GENERIC_REPRESENT() to get a basic implementation for this method.

Parameters

[out] stream Output stream to write to

Implements MatcherBase< SampleType >.

Definition at line 181 of file hart_latency_below.hpp.

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

include/matchers/hart_latency_below.hpp

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Method

Constructor & Destructor Documentation

◆ LatencyBelow() [1/3]

◆ LatencyBelow() [2/3]

◆ LatencyBelow() [3/3]

◆ ~LatencyBelow()

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ prepare()

◆ canOperatePerBlock()

◆ reset()

◆ supportsChannelLayout()

◆ match()

◆ getFailureDetails()

◆ represent()