Convolves input audio (up to 64 channels) with interpolated HRTFs in the time-frequency domain, and applies optional near-field binaural filtering, as described in [1]. More...

#include <binauraliser.h>

Functions
void	binauraliserNF_create (void **const phBin)
	Creates an instance of the binauraliser.

void	binauraliserNF_destroy (void **const phBin)
	Destroys an instance of the binauraliser.

void	binauraliserNF_init (void *const hBin, int samplerate)
	Initialises an instance of binauraliser with default settings.

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

void	binauraliserNF_process (void const hBin, const float const inputs, float const *outputs, int nInputs, int nOutputs, int nSamples)
	Binauralises the input signals at the user specified directions.

void	binauraliserNF_processFD (void const hBin, const float const inputs, float const *outputs, int nInputs, int nOutputs, int nSamples)
	Alternate version of binauraliserNF_process() that performs frequency-domain DVF filtering.

void	binauraliserNF_setSourceDist_m (void *const hBin, int index, float newDist_m)
	Sets the panning distance for a specific channel index, in METERS.

void	binauraliserNF_setInputConfigPreset (void *const hBin, int newPresetID)
	Loads an input preset (see SOURCE_CONFIG_PRESETS enum)

float	binauraliserNF_getSourceDist_m (void *const hBin, int index)
	Returns the source elevation for a given index, in METERS.

float	binauraliserNF_getFarfieldThresh_m (void *const hBin)
	Returns the distance considered to be the far field (beyond which no near field filtering is applied), in METERS.

float	binauraliserNF_getFarfieldHeadroom (void *const hBin)
	Returns the scaling factor to give the far field threshold headroom (useful for UI range limits)

float	binauraliserNF_getNearfieldLimit_m (void *const hBin)
	Returns the minimum distance possible for near field filter, in METERS.

Detailed Description

Convolves input audio (up to 64 channels) with interpolated HRTFs in the time-frequency domain, and applies optional near-field binaural filtering, as described in [1].

The HRTFs are interpolated by applying amplitude-preserving VBAP gains to the HRTF magnitude responses and inter-aural time differences (ITDs) individually, before being re-combined. The example also allows the user to specify an external SOFA file for the convolution, and rotations of the source directions to accomodate head-tracking.

See also: [1] S. Spagnol, E. Tavazzi, and F. Avanzini, “Distance rendering and perception of nearby virtual sound sources with a near-field filter model,” Applied Acoustics, vol. 115, pp. 61–73, Jan. 2017, doi: 10.1016/j.apacoust.2016.08.015.

Author: Michael McCrea, Leo McCormack

Date: 22.02.2022

License: ISC

Definition in file binauraliser_nf.h.

Function Documentation

◆ binauraliserNF_create()

void binauraliserNF_create ( void **const phBin )

Creates an instance of the binauraliser.

Parameters

[in] phBin (&) address of binauraliserNF handle

Examples: binauraliser_nf.h.

Definition at line 41 of file binauraliser_nf.c.

◆ binauraliserNF_destroy()

void binauraliserNF_destroy ( void **const phBin )

Destroys an instance of the binauraliser.

Parameters

[in] phBin (&) address of binauraliser handle

Examples: binauraliser_nf.h.

Definition at line 139 of file binauraliser_nf.c.

◆ binauraliserNF_getFarfieldHeadroom()

float binauraliserNF_getFarfieldHeadroom ( void *const hBin )

Returns the scaling factor to give the far field threshold headroom (useful for UI range limits)

Examples: binauraliser_nf.h.

Definition at line 418 of file binauraliser_nf.c.

◆ binauraliserNF_getFarfieldThresh_m()

float binauraliserNF_getFarfieldThresh_m ( void *const hBin )

Returns the distance considered to be the far field (beyond which no near field filtering is applied), in METERS.

Examples: binauraliser_nf.h.

Definition at line 411 of file binauraliser_nf.c.

◆ binauraliserNF_getNearfieldLimit_m()

float binauraliserNF_getNearfieldLimit_m ( void *const hBin )

Returns the minimum distance possible for near field filter, in METERS.

Examples: binauraliser_nf.h.

Definition at line 425 of file binauraliser_nf.c.

◆ binauraliserNF_getSourceDist_m()

float binauraliserNF_getSourceDist_m	(	void *const	hBin,
		int	index )

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

Parameters

[in]	hBin	binauraliserNF handle
[in]	index	source index

Examples: binauraliser_nf.h.

Definition at line 404 of file binauraliser_nf.c.

◆ binauraliserNF_init()

void binauraliserNF_init	(	void *const	hBin,
		int	samplerate )

Initialises an instance of binauraliser with default settings.

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

Parameters

[in]	hBin	binauraliserNF handle
[in]	samplerate	Host samplerate.

Examples: binauraliser_nf.h.

Definition at line 175 of file binauraliser_nf.c.

◆ binauraliserNF_initCodec()

void binauraliserNF_initCodec ( void *const hBin )

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] hBin binauraliser handle

Examples: binauraliser_nf.h.

Definition at line 190 of file binauraliser_nf.c.

◆ binauraliserNF_process()

void binauraliserNF_process	(	void *const	hBin,
		const float const	inputs,
		float const	outputs,
		int	nInputs,
		int	nOutputs,
		int	nSamples )

Binauralises the input signals at the user specified directions.

Parameters

[in]	hBin	binauraliserNF 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: binauraliser_nf.h.

Definition at line 226 of file binauraliser_nf.c.

◆ binauraliserNF_processFD()

void binauraliserNF_processFD	(	void *const	hBin,
		const float const	inputs,
		float const	outputs,
		int	nInputs,
		int	nOutputs,
		int	nSamples )

Alternate version of binauraliserNF_process() that performs frequency-domain DVF filtering.

Not used but kept for posterity.

Examples: binauraliser_nf.h.

◆ binauraliserNF_setInputConfigPreset()

void binauraliserNF_setInputConfigPreset	(	void *const	hBin,
		int	newPresetID )

Loads an input preset (see SOURCE_CONFIG_PRESETS enum)

Parameters

[in]	hBin	binauraliserNF handle
[in]	newPresetID	index of the source preset

Examples: binauraliser_nf.h.

Definition at line 387 of file binauraliser_nf.c.

◆ binauraliserNF_setSourceDist_m()

void binauraliserNF_setSourceDist_m	(	void *const	hBin,
		int	index,
		float	newDist_m )

Sets the panning distance for a specific channel index, in METERS.

Parameters

[in]	hBin	binauraliserNF handle
[in]	index	source index
[in]	newDist_m	source distance in meter

Examples: binauraliser_nf.h.

Definition at line 377 of file binauraliser_nf.c.

Functions

Detailed Description

Function Documentation

◆ binauraliserNF_create()

◆ binauraliserNF_destroy()

◆ binauraliserNF_getFarfieldHeadroom()

◆ binauraliserNF_getFarfieldThresh_m()

◆ binauraliserNF_getNearfieldLimit_m()

◆ binauraliserNF_getSourceDist_m()

◆ binauraliserNF_init()

◆ binauraliserNF_initCodec()

◆ binauraliserNF_process()

◆ binauraliserNF_processFD()

◆ binauraliserNF_setInputConfigPreset()

◆ binauraliserNF_setSourceDist_m()