Use multiple detectors to find note onsets at given frequencies (with multithreading). More...

#include <detectorbank.h>

Collaboration diagram for DetectorBank:

Classes
struct	AbsZ_params
	Struct to pass absZ thread parameters to a worker thread. More...

struct	detector_components
	Metaparameters for a detector. More...

struct	GetZ_params
	Struct to pass getZ thread parameters to a worker thread. More...

Public Types
enum	Features { central_difference = 1, runge_kutta = 2, freq_unnormalized = 1 << 8, search_normalized = 2 << 8, amp_unnormalized = 1 << 16, amp_normalized = 2 << 16, defaults = runge_kutta \| freq_unnormalized \| amp_normalized }
	Specify numerical and normalisation methods for this detector bank. More...

Public Member Functions
	DetectorBank (const std::string &profile, const inputSample_t *inputBuffer, const std::size_t inputBufferSize)
	Construct a DetectorBank from archived parameters. More...

	DetectorBank (const parameter_t sr, const inputSample_t inputBuffer, const std::size_t inputBufferSize, std::size_t numThreads, const parameter_t freqs=EDO12_pf, parameter_t *bw=nullptr, const std::size_t numDetectors=EDO12_pf_size, Features features=Features::defaults, parameter_t damping=0.0001, const parameter_t gain=25.0)
	Construct a DetectorBank. More...

void	setInputBuffer (const inputSample_t *inputBuffer, const std::size_t inputBufferSize)
	Change the input, without recreating the detector bank. More...

int	getZ (discriminator_t *frames, std::size_t chans, std::size_t numFrames, const std::size_t startChan=0)
	Get the next numFrames of detector bank output. More...

result_t	absZ (result_t absFrames, std::size_t absChans, const std::size_t absNumFrames, discriminator_t frames, std::size_t maxThreads=0) const
	Take z-frames and fill a given array of the same dimensions (absFrames) with their absolute values. More...

bool	seek (long int offset)
	Set input sample at which to start the detection. More...

std::size_t	tell (void) const
	Get the index of current input sample. More...

parameter_t	getSR (void) const
	Get the sample rate associated with this DetectorBank. More...

std::size_t	getChans (void) const
	Return the number of detectors currently maintained by this DetectorBank. More...

std::size_t	getBuflen (void) const
	Find out the total number of samples currently available. More...

parameter_t	getW (std::size_t ch) const
	Find the frequency of a given channel's detector. More...

parameter_t	getFreqIn (std::size_t ch) const
	Find the input frequency of a given channel's detector. More...

std::string	toXML (void) const
	Return description of the detectorbank serialised in XML form.

void	fromXML (std::string xml)
	Set the state of the detectorbank according to a previously serialised XML description. More...

void	saveProfile (std::string name)
	Save the current profile so that a DetectorBank can be constructed conveniently in future. More...

Static Public Attributes
static constexpr int	solverMask { 0xff }
	Bit mask for specifying the solver method.

static constexpr int	freqNormalizationMask { 0xff << 8 }
	Bit mask for specifying the frequency normalisation method.

static constexpr int	ampNormalizationMask { 0xff << 16 }
	Bit mask for specifying the amplitude normalisation method.

Protected Member Functions
void	amplify (const inputSample_t *&signal, std::size_t signalSize, const parameter_t gain)
	Apply a gain to the inputBuffer. More...

void	worker (int id)

void	getZDelegate (void *args)
	Perform one thread's worth of work on the given channels. More...

void	stringToFeatures (const std::string &desc)
	Set this DetectorBank's features from a human-readable string using featuresToStringMap. More...

const std::string	featuresToString (void) const
	Produce a human-readable string describing this DetectorBank's features using featuresToStringMap. More...

template<class Archive >
void	save (Archive &archive) const
	Write the relevant properties of the detector bank to an archive. More...

template<class Archive >
void	load (Archive &archive)
	Write the relevant properties of the detector bank to an archive. More...

void	setDBComponents (const parameter_t frequencies, const parameter_t bandwidths, const std::size_t numDetectors)
	Create the detector_components required for each detector in the detector bank. More...

Protected Attributes
std::vector< std::unique_ptr< AbstractDetector > >	detectors
	Detectors to be run by this detector bank.

std::size_t	inBufSize
	Size of the current audio input buffer.

const inputSample_t *	inBuf
	The current input buffer.

std::unique_ptr< ThreadPool >	threadPool
	Thread manager for concurrent sections.

std::size_t	currentSample
	How far along the input for next read.

parameter_t	d
	Detector damping factor.

parameter_t	sr
	Operating sample rate.

Features	features
	Detector method & normalistion.

parameter_t *	bw
	Array of bandwidths.

parameter_t	gain
	Audio input gain to be applided.

std::unique_ptr< inputSample_t[]>	gainBuf
	If a gain is applied to the input signal, this pointer refers to the locally allocated buffer containing the amplified signal and inBuf is set to the same address.

std::vector< detector_components >	dbComponents
	Vector of detector_components describing each AbstractDetector in the vector detectors.

parameter_t	modF
	Frequency above which the signal should be modulated.

Static Protected Attributes
static const std::map< int, std::string >	featuresToStringMap
	Printable string representations of the flags in the Features enum Use the provided routines through preference to produce a human-readable readable format, as they will deal with combinations of flags.

static const parameter_t	EDO12_pf []
	Standard tuning set for a 12EDO piano keyboard.

static const int	EDO12_pf_size
	Size of standard 12EDO piano keyboard.

static ProfileManager	profileManager
	The profile manager responsible for loading and saving detectorbank properties.

Private Member Functions
void	makeDetectors (const std::size_t numDetectors, const parameter_t mu, const parameter_t d, const parameter_t sr, const Features features, const parameter_t gain)
	Utility routine to make the appropriate detectors and tune them according to the required feature set. More...

Private Attributes
std::map< int, std::unique_ptr< inputSample_t[]> >	input_pool
	Mapping of ratio of requested frequency to the maximum used detector frequency for this solver and normalization method.

bool	auto_bw
	Has DetectorBank created its own array of zeros for bandwidth?

Friends
class	cereal::access

Detailed Description

Use multiple detectors to find note onsets at given frequencies (with multithreading).

Definition at line 25 of file detectorbank.h.

Member Enumeration Documentation

◆ Features

enum DetectorBank::Features

Specify numerical and normalisation methods for this detector bank.

Please see DetectorBank Features for more information.

Enumerator
central_difference	Central-difference.
runge_kutta	Fourth order Runge-Kutta.
freq_unnormalized	Without frequency normalisation.
search_normalized	Iteratively adjust response.
amp_unnormalized	Without amplitude normalisation.
amp_normalized	Scale real and imaginary parts of the response.
defaults	Default is Runge-Kutta, unnormalised frequency, normalised amplitude.

Definition at line 37 of file detectorbank.h.

Constructor & Destructor Documentation

◆ DetectorBank() [1/2]

DetectorBank::DetectorBank	(	const std::string &	profile,
		const inputSample_t *	inputBuffer,
		const std::size_t	inputBufferSize
	)

Construct a DetectorBank from archived parameters.

Parameters

profile	The name of the profile to read from the archive
inputBuffer	Audio input
inputBufferSize	Length of audio input

Exceptions

std::string Profile 'profile' not found.

◆ DetectorBank() [2/2]

DetectorBank::DetectorBank	(	const parameter_t	sr,
		const inputSample_t *	inputBuffer,
		const std::size_t	inputBufferSize,
		std::size_t	numThreads,
		const parameter_t *	freqs = `EDO12_pf`,
		parameter_t *	bw = `nullptr`,
		const std::size_t	numDetectors = `EDO12_pf_size`,
		Features	features = `Features::defaults`,
		parameter_t	damping = `0.0001`,
		const parameter_t	gain = `25.0`
	)

Construct a DetectorBank.

Parameters

sr	Sample rate of audio. (This must be 44100 or 48000.)
inputBuffer	Audio input
inputBufferSize	Length of audio input
numThreads	Number of threads to execute concurrently to determine the detector outputs. Passing a value of less than 1 causes the number of threads to be set according to the number of reported CPU cores
freqs	Array of frequencies for the detector bank
bw	Array of bandwidths for each detector. If nullptr, minimum bandwidth detetors will be constructed
numDetectors	Length of the freqs and bandwidths arrays
features	Numerical method (runge_kutta or central_difference), freqency normalisation (freq_unnormalized or search_normalized) and amplitude normalisation (amp_unnormalized or amp_normalized). Default is runge_kutta\|freq_unnormalized\|amp_normalized. See DetectorBank Features for more information.
damping	Damping for all detectors
gain	Audio input gain to be applied. (Default value of 25 is recommended in order to keep the numbers used in the internal calculations within a sensible range.)

Exceptions

std::string	Sample rate should be 44100 or 48000
std::string	Central difference can only be used for minimum bandwidth detectors.

Member Function Documentation

◆ absZ()

result_t DetectorBank::absZ	(	result_t *	absFrames,
		std::size_t	absChans,
		const std::size_t	absNumFrames,
		discriminator_t *	frames,
		std::size_t	maxThreads = `0`
	)		const

Take z-frames and fill a given array of the same dimensions (absFrames) with their absolute values.

Also returns the maximum value in absFrames.

Parameters

absFrames	Output array
absChans	Height of the output array
absNumFrames	Length of the input array
frames	Input array of complex z values
maxThreads	The number of threads used to perform the calculations. 0 (the default) causes the value used when constructing the DetectorBank to be used. If only a small number of samples are to be converted, it might help to force single-thread operation because the abs(·) function is so light-weight.

Returns: The maximum value found while performing the conversion

◆ amplify()

void DetectorBank::amplify	(	const inputSample_t *&	signal,
		std::size_t	signalSize,
		const parameter_t	gain
	)

protected

Apply a gain to the inputBuffer.

Parameters

signal	Signal to be amplified
signalSize	Size of signal
gain	Gain to be applied

◆ featuresToString()

const std::string DetectorBank::featuresToString ( void ) const

protected

Produce a human-readable string describing this DetectorBank's features using featuresToStringMap.

Returns: Human-readable comma-separated string descibing the features

◆ fromXML()

void DetectorBank::fromXML ( std::string xml )

Set the state of the detectorbank according to a previously serialised XML description.

Parameters

xml	The description of the detector bank's new state

◆ getBuflen()

std::size_t DetectorBank::getBuflen ( void ) const

inline

Find out the total number of samples currently available.

Returns: The total number of samples in the audio buffer

Definition at line 171 of file detectorbank.h.

◆ getChans()

std::size_t DetectorBank::getChans ( void ) const

inline

Return the number of detectors currently maintained by this DetectorBank.

Returns: The number of detectors

Definition at line 167 of file detectorbank.h.

◆ getFreqIn()

parameter_t DetectorBank::getFreqIn ( std::size_t ch ) const

Find the input frequency of a given channel's detector.

Returns 0 if the channel number is invalid.

Parameters

ch	Channel number

Returns: f_in for the specified channel

◆ getSR()

parameter_t DetectorBank::getSR ( void ) const

inline

Get the sample rate associated with this DetectorBank.

Returns: The current sample rate

Definition at line 163 of file detectorbank.h.

◆ getW()

parameter_t DetectorBank::getW ( std::size_t ch ) const

Find the frequency of a given channel's detector.

If the signal has been modulated and/or normalised, the adjusted frequency will be returned. Returns 0 if the channel number is invalid.

Parameters

ch	Channel number

Returns: w = 2pi.f for the specified channel

◆ getZ()

int DetectorBank::getZ	(	discriminator_t *	frames,
		std::size_t	chans,
		std::size_t	numFrames,
		const std::size_t	startChan = `0`
	)

Get the next numFrames of detector bank output.

Parameters

frames	Output array
chans	Height of output array
numFrames	Length of output array
startChan	Channel from which to start

Returns: Number of frames processed

◆ getZDelegate()

void DetectorBank::getZDelegate ( void * args )

protected

Perform one thread's worth of work on the given channels.

Called by getZ(). Parameters are required as a pointer to a GetZ_params.

Parameters

args Arguments

◆ load()

template<class Archive >

void DetectorBank::load ( Archive & archive )

protected

Write the relevant properties of the detector bank to an archive.

Parameters

archive The archive from which properties should be read

◆ makeDetectors()

void DetectorBank::makeDetectors	(	const std::size_t	numDetectors,
		const parameter_t	mu,
		const parameter_t	d,
		const parameter_t	sr,
		const Features	features,
		const parameter_t	gain
	)

private

Utility routine to make the appropriate detectors and tune them according to the required feature set.

The detectors are pushed appended to the protected vector of detectors. Would normally only be called when then class is being constructed or deserialised. If the f is not provided (nullptr), the initial freqency is set to 0Hz in the expectation that it will be corrected later on during a deserialisation process. In this case, normalisation will also be skipped.

Parameters

numDetectors	Size of the array freqs
mu	Criticality
d	Damping
sr	Sample rate
features	Type of filter and normalisation method
b	First Lyapunov coeffcient

◆ save()

template<class Archive >

void DetectorBank::save ( Archive & archive ) const

protected

Write the relevant properties of the detector bank to an archive.

Parameters

archive The archive to which properties should be written

◆ saveProfile()

void DetectorBank::saveProfile ( std::string name )

Save the current profile so that a DetectorBank can be constructed conveniently in future.

Parameters

name	The name of the profile

◆ seek()

bool DetectorBank::seek ( long int offset )

Set input sample at which to start the detection.

Negative values seek from the end of the current input buffer

Parameters

offset New sample index

Returns: true for success; false if the requested offset is out of range

◆ setDBComponents()

void DetectorBank::setDBComponents	(	const parameter_t *	frequencies,
		const parameter_t *	bandwidths,
		const std::size_t	numDetectors
	)

protected

Create the detector_components required for each detector in the detector bank.

If the frequency requested for a detector exceeds an empirically defined constant (based on the normalization method and the type of solver in use) the results are obtained from a lower frequency detector operating on a frequency-shifted input buffer. This method initialises the dbComponents vector and generates the frequency-shifted input signals if required.

◆ setInputBuffer()

void DetectorBank::setInputBuffer	(	const inputSample_t *	inputBuffer,
		const std::size_t	inputBufferSize
	)

Change the input, without recreating the detector bank.

Parameters

inputBuffer	New input samples
inputBufferSize	Length of new input

◆ stringToFeatures()

void DetectorBank::stringToFeatures ( const std::string & desc )

protected

Set this DetectorBank's features from a human-readable string using featuresToStringMap.

Parameters

desc	Human-readable feature list of comma-separated features

Exceptions

Illegal feature name reading XML profile	if a feature in the list is unrecognised;
No valid features in feature list reading XML profile	if the feature list is empty

◆ tell()

std::size_t DetectorBank::tell ( void ) const

inline

Get the index of current input sample.

Returns: Current input sample index

Definition at line 159 of file detectorbank.h.

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

/home/keziah/onsets/DetectorBank/src/detectorbank.h

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ Features

Constructor & Destructor Documentation

◆ DetectorBank() [1/2]

◆ DetectorBank() [2/2]

Member Function Documentation

◆ absZ()

◆ amplify()

◆ featuresToString()

◆ fromXML()

◆ getBuflen()

◆ getChans()

◆ getFreqIn()

◆ getSR()

◆ getW()

◆ getZ()

◆ getZDelegate()

◆ load()

◆ makeDetectors()

◆ save()

◆ saveProfile()

◆ seek()

◆ setDBComponents()

◆ setInputBuffer()

◆ stringToFeatures()

◆ tell()