Polymorphic base for all matchers. More...

#include <hart_matcher.hpp>

Inheritance diagram for MatcherBase< SampleType >:

Public Member Functions
virtual	~MatcherBase ()=default

virtual void	prepare (double sampleRateHz, size_t numInputChannels, size_t numOutputChannels, size_t maxBlockSizeFrames)=0
	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.

	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	match (AnalysisContext< SampleType > analysisContext)
	Tells the host if the piece of audio satisfies Matcher's condition or not.

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

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

virtual MatcherFailureDetails	getFailureDetails () const =0
	Returns a description of why the match has failed.

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

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

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

virtual std::unique_ptr< MatcherBase< SampleType > >	copy () const =0
	Returns a smart pointer with a copy of this object.

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

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.

Public Attributes
const AudioBuffer< SampleType > &	observedOutputAudio

Protected Member Functions
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
ChannelFlags	m_channelsToMatch {true}

Detailed Description

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

Polymorphic base for all matchers.

Warning: This class exists only for type erasure and polymorphism. Do NOT inherit custom matchers from this class directly. Inherit from hart::Matcher instead.

Definition at line 26 of file hart_matcher.hpp.

Constructor & Destructor Documentation

◆ ~MatcherBase()

template<typename SampleType >

virtual ~MatcherBase ( )

virtualdefault

Member Function Documentation

◆ prepare()

template<typename SampleType >

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

pure virtual

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)

Implemented in LatencyBelow< SampleType >, PolarityPreserved< SampleType >, EqualsTo< SampleType >, TruePeaksBelow< SampleType >, FundamentalEquals< SampleType >, MatcherFunction< SampleType >, NoDenormals< SampleType >, PeaksAt< SampleType >, and PeaksBelow< SampleType >.

◆ HART_DEPRECATED()

template<typename SampleType >

HART_DEPRECATED ( "This method is deprecated. Switch to the one that uses AnalysisContext instead." ) const &

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

inputAudio	A piece of input audio. Some matchers may be based on a relationship between input and output, rather than checking just the output audio. And in a lot of cases Matcher can ingore the input completely.
observedOutputAudio	A piece of observed output audio to check

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

Deprecated:: This method is deprecated. Switch to the one that uses AnalysisContext instead.

◆ match() [1/2]

template<typename SampleType >

return match ( analysisContext )

◆ match() [2/2]

template<typename SampleType >

virtual bool match ( AnalysisContext< SampleType > analysisContext )

inlinevirtual

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 in EqualsTo< SampleType >, FundamentalEquals< SampleType >, LatencyBelow< SampleType >, MatcherFunction< SampleType >, NoDenormals< SampleType >, PeaksAt< SampleType >, PeaksBelow< SampleType >, PolarityPreserved< SampleType >, and TruePeaksBelow< SampleType >.

Definition at line 66 of file hart_matcher.hpp.

◆ canOperatePerBlock()

template<typename SampleType >

virtual bool canOperatePerBlock ( ) const

pure virtual

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.

Implemented in EqualsTo< SampleType >, FundamentalEquals< SampleType >, LatencyBelow< SampleType >, MatcherFunction< SampleType >, NoDenormals< SampleType >, PeaksAt< SampleType >, PeaksBelow< SampleType >, PolarityPreserved< SampleType >, and TruePeaksBelow< SampleType >.

◆ reset()

template<typename SampleType >

virtual void reset ( )

inlinevirtual

Resets the matcher to its initial state.

Reimplemented in EqualsTo< SampleType >, FundamentalEquals< SampleType >, LatencyBelow< SampleType >, PolarityPreserved< SampleType >, and TruePeaksBelow< SampleType >.

Definition at line 81 of file hart_matcher.hpp.

◆ getFailureDetails()

template<typename SampleType >

virtual MatcherFailureDetails getFailureDetails ( ) const

pure virtual

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

Implemented in EqualsTo< SampleType >, FundamentalEquals< SampleType >, LatencyBelow< SampleType >, MatcherFunction< SampleType >, NoDenormals< SampleType >, PeaksAt< SampleType >, PeaksBelow< SampleType >, PolarityPreserved< SampleType >, and TruePeaksBelow< SampleType >.

◆ represent()

template<typename SampleType >

virtual void represent ( std::ostream & stream ) const

pure virtual

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

Implemented in FundamentalEquals< SampleType >, EqualsTo< SampleType >, LatencyBelow< SampleType >, MatcherFunction< SampleType >, PeaksAt< SampleType >, PeaksBelow< SampleType >, PolarityPreserved< SampleType >, and TruePeaksBelow< SampleType >.

◆ supportsChannelLayout()

template<typename SampleType >

virtual bool supportsChannelLayout	(	size_t	,
		size_t
	)		const

inlinevirtual

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 in LatencyBelow< SampleType >, PolarityPreserved< SampleType >, and EqualsTo< SampleType >.

Definition at line 112 of file hart_matcher.hpp.

◆ supportsSampleRate()

template<typename SampleType >

virtual bool supportsSampleRate ( double ) const

inlinevirtual

Tells whether this Matcher supports given sample rate.

It is guaranteed to be called before prepare()

Parameters

sampleRateHz sample rate at which the audio will be presented

Returns: true if matcher is capable of processing audio with a given sample rate, false otherwise

Reimplemented in EqualsTo< SampleType >.

Definition at line 118 of file hart_matcher.hpp.

◆ copy()

template<typename SampleType >

virtual std::unique_ptr< MatcherBase< SampleType > > copy ( ) const

pure virtual

Returns a smart pointer with a copy of this object.

Returns: Copy of this object wrapped in a smart pointer

◆ move()

template<typename SampleType >

virtual std::unique_ptr< MatcherBase< SampleType > > move ( )

pure virtual

Returns a smart pointer with a moved instance of this object.

Returns: This object, moved and wrapped in a smart pointer

◆ appliesToChannel()

template<typename SampleType >

bool appliesToChannel ( size_t channel )

inlineprotected

Indicates whether this matcher should check a specific channel.

You might want to use it in the match() callback. See atChannels(), atChannel(), atAllChannels(), atAllChannelsExcept().

Definition at line 134 of file hart_matcher.hpp.

◆ getChannelFlags()

template<typename SampleType >

ChannelFlags getChannelFlags ( ) const

inlineprotected

Returns flags for the channels that the matcher should apply to.

Handy to use with Metrics. Guaranteed to have number of channels equal to max (numInputChannels, numOutputChannels).

Definition at line 142 of file hart_matcher.hpp.

◆ prepareWithActiveChannels()

template<typename SampleType >

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

inline

Prepare for processing, meant to be called by a host.

For internal use by hosts

Definition at line 150 of file hart_matcher.hpp.

◆ representWithActiveChannels()

template<typename SampleType >

void representWithActiveChannels ( std::ostream & stream ) const

inline

Makes a text representation of this Matcher with optional "atChannels" appendix.

For internal use by hosts

Definition at line 158 of file hart_matcher.hpp.

Member Data Documentation

◆ observedOutputAudio

template<typename SampleType >

const AudioBuffer<SampleType>& observedOutputAudio

Initial value:

{

const AnalysisContext<SampleType> analysisContext (inputAudio, observedOutputAudio)

hart::MatcherBase::observedOutputAudio

const AudioBuffer< SampleType > & observedOutputAudio

Definition hart_matcher.hpp:54

Definition at line 53 of file hart_matcher.hpp.

◆ m_channelsToMatch

template<typename SampleType >

ChannelFlags m_channelsToMatch {true}

protected

Definition at line 129 of file hart_matcher.hpp.

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

include/matchers/hart_matcher.hpp

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~MatcherBase()

Member Function Documentation

◆ prepare()

◆ HART_DEPRECATED()

◆ match() [1/2]

◆ match() [2/2]

◆ canOperatePerBlock()

◆ reset()

◆ getFailureDetails()

◆ represent()

◆ supportsChannelLayout()

◆ supportsSampleRate()

◆ copy()

◆ move()

◆ appliesToChannel()

◆ getChannelFlags()

◆ prepareWithActiveChannels()

◆ representWithActiveChannels()

Member Data Documentation

◆ observedOutputAudio

◆ m_channelsToMatch