Communication between algorithms

Algorithms within one chain can share variables for communication with other algorithms. More...

Collaboration diagram for Communication between algorithms:

Files
file	mha_algo_comm.hh
	Header file for Algorithm Communication.

Classes
struct	MHA_AC::comm_var_t
	Algorithm communication variable structure. More...
class	MHA_AC::spectrum_t
	Convenience class for inserting a spectrum into the AC space. More...
class	MHA_AC::waveform_t
	Convenience class for inserting a waveform (a block of time-domain audio signal) into the AC space. More...
class	MHA_AC::ac2matrix_t
	Copy AC variable to a matrix. More...
class	MHA_AC::acspace2matrix_t
	Copy all or a subset of all numeric AC variables into an array of matrixes. More...
class	MHA_AC::scalar_t< numeric_t, MHA_AC_TYPECODE >
	Template for convenience classes for inserting a numeric scalar into the AC space. More...

Functions
mha_spec_t	MHA_AC::get_var_spectrum (algo_comm_t &ac, const std::string &name)
	Convert an AC variable into a spectrum. More...
mha_wave_t	MHA_AC::get_var_waveform (algo_comm_t &ac, const std::string &name)
	Convert an AC variable into a waveform. More...
int	MHA_AC::get_var_int (algo_comm_t &ac, const std::string &name)
	Return value of an integer scalar AC variable. More...
float	MHA_AC::get_var_float (algo_comm_t &ac, const std::string &name)
	Return value of an floating point scalar AC variable. More...
std::vector< float >	MHA_AC::get_var_vfloat (algo_comm_t &ac, const std::string &name)
	Return value of an floating point vector AC variable as standard vector of floats. More...

Detailed Description

Algorithms within one chain can share variables for communication with other algorithms.

This mechanism allows interaction between algorithms (i.e. separation of noise estimation and noise reduction algorithms, combination of dynamic compression and noise estimation). Through a set of simple C functions, algorithms can propagate variables of any type, even C++ classes, to other algorithms.

An algorithm communication handle (algo_comm_t) is passed at initialisation time to the constructor of each plugin class constructor. This handle contains a reference handle, algo_comm_t::handle, and a number of function pointers, algo_comm_t::insert_var etc.. An algorithm communication variable is accessed through objects of type comm_var_t.

For openMHA users, openMHA provides generic plugins to inspect and store AC variables of numeric types:

• plugin acmon mirrors AC variables of numeric types in readonly configuration variables (called monitors),
• plugin acsave stores AC variables into Matlab or text files. Plugin developers may also want to use these plugins to inspect any AC variables published by their own plugins during testing.

As a developer of openMHA plugin(s), please observe the following best practices in plugins using AC variables:

1. Plugins publishing AC variables:
   • insert all variables during prepare()
   • re-insert all variables during each process()
   • memory used for storing AC variable values is allocated and owned by the publishing plugin and needs to remain valid until the next call to process() or release() of the same plugin.
2. Plugins consuming AC variable published by other plugins:
   • poll required variables (and check validity) again during each process() before accessing their values.

Function Documentation

get_var_spectrum()

mha_spec_t MHA_AC::get_var_spectrum	(	algo_comm_t &	ac,
		const std::string &	name
	)

Convert an AC variable into a spectrum.

This function reads an AC variable and tries to convert it into a valid spectrum. The spectrum variable is only valid during the current call of the plugin's process() method and should not be stored for later reuse.

The stride of the AC variable is used as the number of spectral bins per channel. The complex values of the spectrum are not copied, the buf pointer of the returned spectrum points to the original memory of the AC variable.

Parameters

ac	AC handle
name	Name of the variable

Returns

Spectrum structure

get_var_waveform()

mha_wave_t MHA_AC::get_var_waveform	(	algo_comm_t &	ac,
		const std::string &	name
	)

Convert an AC variable into a waveform.

This function reads an AC variable and tries to convert it into a valid block of waveform signal. The waveform variable only valid during the current call of the plugin's process() method and should not be stored for later reuse.

The stride of the AC variable is used as the number of audio channels. The single-precision floating-point sample values are not copied, the buf pointer of the returned waveform points to the original memory of the AC variable.

Parameters

ac	AC handle
name	Name of the variable

Returns

waveform structure

get_var_int()

int MHA_AC::get_var_int	(	algo_comm_t &	ac,
		const std::string &	name
	)

Return value of an integer scalar AC variable.

Parameters

ac	AC handle
name	Name of the variable

Returns

Variable value

get_var_float()

float MHA_AC::get_var_float	(	algo_comm_t &	ac,
		const std::string &	name
	)

Return value of an floating point scalar AC variable.

Parameters

ac	AC handle
name	Name of the variable

Returns

Variable value

get_var_vfloat()

std::vector< float > MHA_AC::get_var_vfloat	(	algo_comm_t &	ac,
		const std::string &	name
	)

Return value of an floating point vector AC variable as standard vector of floats.

Because this function allocates memory for the return value, it should not be called during signal processing, but only from the plugin prepare() method.

Parameters

ac	AC handle
name	Name of the variable

Returns

Variable value