An arbitrary array panner (HRIRs, microphone array IRs, etc.) with coherent and incoherent spreading modes, as described in [1]. More...

#include "_common.h"

Macros
#define	SPREADER_MAX_NUM_SOURCES ( 8 )
	Maximum number of sources supported by the spreader example.

Enumerations
enum	SPREADER_PROC_MODES { SPREADER_MODE_NAIVE = 1 , SPREADER_MODE_OM , SPREADER_MODE_EVD }
	Available processing modes. More...

Functions
void	spreader_create (void **const phSpr)
	Creates an instance of the spreader.

void	spreader_destroy (void **const phSpr)
	Destroys an instance of the spreader.

void	spreader_init (void *const hSpr, int samplerate)
	Initialises an instance of spreader with default settings.

void	spreader_initCodec (void *const hSpr)
	Intialises the codec variables, based on current global/user parameters.

void	spreader_process (void const hSpr, const float const inputs, float const *outputs, int nInputs, int nOutputs, int nSamples)
	Spatialises and spreads the input signals in the user specified directions.

void	spreader_refreshSettings (void *const hSpr)
	Sets all intialisation flags to 1; re-initialising all settings/variables as spreader is currently configured, at next available opportunity.

void	spreader_setSpreadingMode (void *const hSpr, int newMode)
	Sets the spreading mode (see SPREADER_PROC_MODES)

void	spreader_setAveragingCoeff (void *const hSpr, float newValue)
	Sets the averaging coefficient [0..1].

void	spreader_setSourceAzi_deg (void *const hSpr, int index, float newAzi_deg)
	Sets the panning azimuth for a specific channel index, in DEGREES.

void	spreader_setSourceElev_deg (void *const hSpr, int index, float newElev_deg)
	Sets the panning elevation for a specific channel index, in DEGREES.

void	spreader_setSourceSpread_deg (void *const hSpr, int index, float newSpread_deg)
	Sets the source spread for a specific channel index, in DEGREES.

void	spreader_setNumSources (void *const hSpr, int new_nSources)
	Sets the number of input channels/sources to binauralise.

void	spreader_setUseDefaultHRIRsflag (void *const hSpr, int newState)
	Sets flag to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).

void	spreader_setSofaFilePath (void const hSpr, const char path)
	Sets the file path for a .sofa file, in order to employ a custom HRIR set for the decoding.

int	spreader_getFrameSize (void)
	Returns the processing framesize (i.e., number of samples processed with every _process() call )

CODEC_STATUS	spreader_getCodecStatus (void *const hSpr)
	Returns current codec status codec status (see CODEC_STATUS enum)

float	spreader_getProgressBar0_1 (void *const hSpr)
	(Optional) Returns current intialisation/processing progress, between 0..1

void	spreader_getProgressBarText (void const hSpr, char text)
	(Optional) Returns current intialisation/processing progress text

int *	spreader_getDirectionActivePtr (void *const hSpr, int index)
	Returns the pointer to a vector describing which directions are currently being used for the spreading, for a given source index.

int	spreader_getSpreadingMode (void *const hSpr)
	Returns the spreading mode (see SPREADER_PROC_MODES)

float	spreader_getAveragingCoeff (void *const hSpr)
	Returns the averaging coefficient [0..1].

float	spreader_getSourceAzi_deg (void *const hSpr, int index)
	Returns the source azimuth for a given source index, in DEGREES.

float	spreader_getSourceElev_deg (void *const hSpr, int index)
	Returns the source elevation for a given source index, in DEGREES.

float	spreader_getSourceSpread_deg (void *const hSpr, int index)
	Returns the source spread for a given source index, in DEGREES.

int	spreader_getNumSources (void *const hSpr)
	Returns the number of inputs/sources in the current config.

int	spreader_getMaxNumSources (void)
	Returns the maximum number of input sources supported by spreader.

int	spreader_getNumOutputs (void *const hSpr)
	Returns the number of ears possessed by the average homo sapien.

int	spreader_getNDirs (void *const hSpr)
	Returns the number of directions in the currently used HRIR set.

float	spreader_getIRAzi_deg (void *const hSpr, int index)
	Returns the IR/TF azimuth for a given index, in DEGREES.

float	spreader_getIRElev_deg (void *const hSpr, int index)
	Returns the IR/TF elevation for a given index, in DEGREES.

int	spreader_getIRlength (void *const hSpr)
	Returns the length of IRs in time-domain samples.

int	spreader_getIRsamplerate (void *const hSpr)
	Returns the IR sample rate.

int	spreader_getUseDefaultHRIRsflag (void *const hSpr)
	Returns the value of a flag used to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).

char *	spreader_getSofaFilePath (void *const hSpr)
	Returns the file path for a .sofa file.

int	spreader_getDAWsamplerate (void *const hSpr)
	Returns the DAW/Host sample rate.

int	spreader_getProcessingDelay (void)
	Returns the processing delay in samples (may be used for delay compensation purposes)

Detailed Description

An arbitrary array panner (HRIRs, microphone array IRs, etc.) with coherent and incoherent spreading modes, as described in [1].

See also: [1] McCormack, L. Politis, A., and Pulkki, V., 2021, October. Rendering of source spread for arbitrary playback setups based on spatial covariance matching. In 2021 IEEE Workshop on Applications of Signal Processing to Audio and Acoustics (WASPAA). IEEE

Author: Leo McCormack

Date: 07.04.2021

License: ISC

Definition in file spreader.h.

Macro Definition Documentation

◆ SPREADER_MAX_NUM_SOURCES

#define SPREADER_MAX_NUM_SOURCES ( 8 )

Maximum number of sources supported by the spreader example.

Definition at line 52 of file spreader.h.

Enumeration Type Documentation

◆ SPREADER_PROC_MODES

enum SPREADER_PROC_MODES

Available processing modes.

Enumerator
SPREADER_MODE_NAIVE	Simple coherent copies of the input signal(s) areassigned to the spreading areas.
SPREADER_MODE_OM	Optimal mixing solution.
SPREADER_MODE_EVD	Basic solution based on an Eigenvalue decomposition.

Examples: spreader.h.

Definition at line 55 of file spreader.h.

Function Documentation

◆ spreader_create()

void spreader_create ( void **const phSpr )

Creates an instance of the spreader.

Parameters

[in] phSpr (&) address of spreader handle

Examples: spreader.h.

Definition at line 34 of file spreader.c.

◆ spreader_destroy()

void spreader_destroy ( void **const phSpr )

Destroys an instance of the spreader.

Parameters

[in] phSpr (&) address of spreader handle

Examples: spreader.h.

Definition at line 119 of file spreader.c.

◆ spreader_getAveragingCoeff()

float spreader_getAveragingCoeff ( void *const hSpr )

Returns the averaging coefficient [0..1].

Examples: spreader.h.

Definition at line 806 of file spreader.c.

◆ spreader_getCodecStatus()

CODEC_STATUS spreader_getCodecStatus ( void *const hSpr )

Returns current codec status codec status (see CODEC_STATUS enum)

Examples: spreader.h.

Definition at line 776 of file spreader.c.

◆ spreader_getDAWsamplerate()

int spreader_getDAWsamplerate ( void *const hSpr )

Returns the DAW/Host sample rate.

Examples: spreader.h.

Definition at line 902 of file spreader.c.

◆ spreader_getDirectionActivePtr()

int * spreader_getDirectionActivePtr	(	void *const	hSpr,
		int	index )

Returns the pointer to a vector describing which directions are currently being used for the spreading, for a given source index.

Examples: spreader.h.

Definition at line 794 of file spreader.c.

◆ spreader_getFrameSize()

int spreader_getFrameSize ( void )

Returns the processing framesize (i.e., number of samples processed with every _process() call )

Examples: spreader.h.

Definition at line 771 of file spreader.c.

◆ spreader_getIRAzi_deg()

float spreader_getIRAzi_deg	(	void *const	hSpr,
		int	index )

Returns the IR/TF azimuth for a given index, in DEGREES.

Examples: spreader.h.

Definition at line 856 of file spreader.c.

◆ spreader_getIRElev_deg()

float spreader_getIRElev_deg	(	void *const	hSpr,
		int	index )

Returns the IR/TF elevation for a given index, in DEGREES.

Examples: spreader.h.

Definition at line 865 of file spreader.c.

◆ spreader_getIRlength()

int spreader_getIRlength ( void *const hSpr )

Returns the length of IRs in time-domain samples.

Examples: spreader.h.

Definition at line 874 of file spreader.c.

◆ spreader_getIRsamplerate()

int spreader_getIRsamplerate ( void *const hSpr )

Returns the IR sample rate.

Examples: spreader.h.

Definition at line 880 of file spreader.c.

◆ spreader_getMaxNumSources()

int spreader_getMaxNumSources ( void )

Returns the maximum number of input sources supported by spreader.

Examples: spreader.h.

Definition at line 839 of file spreader.c.

◆ spreader_getNDirs()

int spreader_getNDirs ( void *const hSpr )

Returns the number of directions in the currently used HRIR set.

Examples: spreader.h.

Definition at line 850 of file spreader.c.

◆ spreader_getNumOutputs()

int spreader_getNumOutputs ( void *const hSpr )

Returns the number of ears possessed by the average homo sapien.

Examples: spreader.h.

Definition at line 844 of file spreader.c.

◆ spreader_getNumSources()

int spreader_getNumSources ( void *const hSpr )

Returns the number of inputs/sources in the current config.

Examples: spreader.h.

Definition at line 833 of file spreader.c.

◆ spreader_getProcessingDelay()

int spreader_getProcessingDelay ( void )

Returns the processing delay in samples (may be used for delay compensation purposes)

Examples: spreader.h.

Definition at line 908 of file spreader.c.

◆ spreader_getProgressBar0_1()

float spreader_getProgressBar0_1 ( void *const hSpr )

(Optional) Returns current intialisation/processing progress, between 0..1

0: intialisation/processing has started
1: intialisation/processing has ended

Examples: spreader.h.

Definition at line 782 of file spreader.c.

◆ spreader_getProgressBarText()

void spreader_getProgressBarText	(	void *const	hSpr,
		char *	text )

(Optional) Returns current intialisation/processing progress text

Note: "text" string should be (at least) of length: PROGRESSBARTEXT_CHAR_LENGTH

Examples: spreader.h.

Definition at line 788 of file spreader.c.

◆ spreader_getSofaFilePath()

char * spreader_getSofaFilePath ( void *const hSpr )

Returns the file path for a .sofa file.

Note: If the custom set fails to load correctly, spreader will revert to the defualt set. Use 'spreader_getUseDefaultHRIRsflag()' to check if loading was successful.

Parameters

[in] hSpr spreader handle

Returns: File path to .sofa file (WITH file extension)

Examples: spreader.h.

Definition at line 892 of file spreader.c.

◆ spreader_getSourceAzi_deg()

float spreader_getSourceAzi_deg	(	void *const	hSpr,
		int	index )

Returns the source azimuth for a given source index, in DEGREES.

Examples: spreader.h.

Definition at line 812 of file spreader.c.

◆ spreader_getSourceElev_deg()

float spreader_getSourceElev_deg	(	void *const	hSpr,
		int	index )

Returns the source elevation for a given source index, in DEGREES.

Examples: spreader.h.

Definition at line 819 of file spreader.c.

◆ spreader_getSourceSpread_deg()

float spreader_getSourceSpread_deg	(	void *const	hSpr,
		int	index )

Returns the source spread for a given source index, in DEGREES.

Examples: spreader.h.

Definition at line 826 of file spreader.c.

◆ spreader_getSpreadingMode()

int spreader_getSpreadingMode ( void *const hSpr )

Returns the spreading mode (see SPREADER_PROC_MODES)

Examples: spreader.h.

Definition at line 800 of file spreader.c.

◆ spreader_getUseDefaultHRIRsflag()

int spreader_getUseDefaultHRIRsflag ( void *const hSpr )

Returns the value of a flag used to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).

Note: If the custom set fails to load correctly, spreader will revert to the defualt set, so this will be '1'

Examples: spreader.h.

Definition at line 886 of file spreader.c.

◆ spreader_init()

void spreader_init	(	void *const	hSpr,
		int	samplerate )

Initialises an instance of spreader with default settings.

Warning: This should not be called while _process() is on-going!

Parameters

[in]	hSpr	spreader handle
[in]	samplerate	Host samplerate.

Examples: spreader.h.

Definition at line 194 of file spreader.c.

◆ spreader_initCodec()

void spreader_initCodec ( void *const hSpr )

Intialises the codec variables, based on current global/user parameters.

Note: This function is fully threadsafe. It can even be called periodically via a timer on one thread, while calling _process() on another thread. Since, if a set function is called (that warrants a re-init), then a flag is triggered internally and the next time this function is called, it will wait until the current process() function has completed before reinitialising the relevant parameters. If the _initCodec() takes longer than the time it takes for process() to be called again, then process() is simply bypassed until the codec is ready.; This function does nothing if no re-initialisations are required.

Parameters

[in] hSpr spreader handle

Examples: spreader.h.

Definition at line 207 of file spreader.c.

◆ spreader_process()

void spreader_process	(	void *const	hSpr,
		const float const	inputs,
		float const	outputs,
		int	nInputs,
		int	nOutputs,
		int	nSamples )

Spatialises and spreads the input signals in the user specified directions.

Parameters

[in]	hSpr	spreader handle
[in]	inputs	Input channel buffers; 2-D array: nInputs x nSamples
[in]	outputs	Output channel buffers; 2-D array: nOutputs x nSamples
[in]	nInputs	Number of input channels
[in]	nOutputs	Number of output channels
[in]	nSamples	Number of samples in 'inputs'/'output' matrices

Examples: spreader.h.

Definition at line 360 of file spreader.c.

◆ spreader_refreshSettings()

void spreader_refreshSettings ( void *const hSpr )

Sets all intialisation flags to 1; re-initialising all settings/variables as spreader is currently configured, at next available opportunity.

Examples: spreader.h.

Definition at line 692 of file spreader.c.

◆ spreader_setAveragingCoeff()

void spreader_setAveragingCoeff	(	void *const	hSpr,
		float	newValue )

Sets the averaging coefficient [0..1].

Examples: spreader.h.

Definition at line 704 of file spreader.c.

◆ spreader_setNumSources()

void spreader_setNumSources	(	void *const	hSpr,
		int	new_nSources )

Sets the number of input channels/sources to binauralise.

Examples: spreader.h.

Definition at line 742 of file spreader.c.

◆ spreader_setSofaFilePath()

void spreader_setSofaFilePath	(	void *const	hSpr,
		const char *	path )

Sets the file path for a .sofa file, in order to employ a custom HRIR set for the decoding.

Note: If the custom set fails to load correctly, spreader will revert to the defualt set. Use spreader_getUseDefaultHRIRsflag() to check if loading was successful.

Parameters

[in]	hSpr	spreader handle
[in]	path	File path to .sofa file (WITH file extension)

Examples: spreader.h.

Definition at line 758 of file spreader.c.

◆ spreader_setSourceAzi_deg()

void spreader_setSourceAzi_deg	(	void *const	hSpr,
		int	index,
		float	newAzi_deg )

Sets the panning azimuth for a specific channel index, in DEGREES.

Examples: spreader.h.

Definition at line 710 of file spreader.c.

◆ spreader_setSourceElev_deg()

void spreader_setSourceElev_deg	(	void *const	hSpr,
		int	index,
		float	newElev_deg )

Sets the panning elevation for a specific channel index, in DEGREES.

Examples: spreader.h.

Definition at line 722 of file spreader.c.

◆ spreader_setSourceSpread_deg()

void spreader_setSourceSpread_deg	(	void *const	hSpr,
		int	index,
		float	newSpread_deg )

Sets the source spread for a specific channel index, in DEGREES.

Examples: spreader.h.

Definition at line 732 of file spreader.c.

◆ spreader_setSpreadingMode()

void spreader_setSpreadingMode	(	void *const	hSpr,
		int	newMode )

Sets the spreading mode (see SPREADER_PROC_MODES)

Examples: spreader.h.

Definition at line 697 of file spreader.c.

◆ spreader_setUseDefaultHRIRsflag()

void spreader_setUseDefaultHRIRsflag	(	void *const	hSpr,
		int	newState )

Sets flag to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).

Note: If the custom set fails to load correctly, spreader will revert to the defualt set. Use spreader_getUseDefaultHRIRsflag() to check if loading was successful.

Examples: spreader.h.

Definition at line 749 of file spreader.c.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SPREADER_MAX_NUM_SOURCES

Enumeration Type Documentation

◆ SPREADER_PROC_MODES

Function Documentation

◆ spreader_create()

◆ spreader_destroy()

◆ spreader_getAveragingCoeff()

◆ spreader_getCodecStatus()

◆ spreader_getDAWsamplerate()

◆ spreader_getDirectionActivePtr()

◆ spreader_getFrameSize()

◆ spreader_getIRAzi_deg()

◆ spreader_getIRElev_deg()

◆ spreader_getIRlength()

◆ spreader_getIRsamplerate()

◆ spreader_getMaxNumSources()

◆ spreader_getNDirs()

◆ spreader_getNumOutputs()

◆ spreader_getNumSources()

◆ spreader_getProcessingDelay()

◆ spreader_getProgressBar0_1()

◆ spreader_getProgressBarText()

◆ spreader_getSofaFilePath()

◆ spreader_getSourceAzi_deg()

◆ spreader_getSourceElev_deg()

◆ spreader_getSourceSpread_deg()

◆ spreader_getSpreadingMode()

◆ spreader_getUseDefaultHRIRsflag()

◆ spreader_init()

◆ spreader_initCodec()

◆ spreader_process()

◆ spreader_refreshSettings()

◆ spreader_setAveragingCoeff()

◆ spreader_setNumSources()

◆ spreader_setSofaFilePath()

◆ spreader_setSourceAzi_deg()

◆ spreader_setSourceElev_deg()

◆ spreader_setSourceSpread_deg()

◆ spreader_setSpreadingMode()

◆ spreader_setUseDefaultHRIRsflag()