SAF
Loading...
Searching...
No Matches
binauraliser.h File Reference

Convolves input audio (up to 64 channels) with interpolated HRTFs in the time-frequency domain. More...

#include "_common.h"

Go to the source code of this file.

Enumerations

enum  INTERP_MODES { INTERP_TRI = 1 , INTERP_TRI_PS }
 Available interpolation modes. More...
 

Functions

void binauraliser_create (void **const phBin)
 Creates an instance of the binauraliser.
 
void binauraliser_destroy (void **const phBin)
 Destroys an instance of the binauraliser.
 
void binauraliser_init (void *const hBin, int samplerate)
 Initialises an instance of binauraliser with default settings.
 
void binauraliser_initCodec (void *const hBin)
 Intialises the codec variables, based on current global/user parameters.
 
void binauraliser_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 binauraliser_refreshSettings (void *const hBin)
 Sets all intialisation flags to 1; re-initialising all settings/variables as binauraliser is currently configured, at next available opportunity.
 
void binauraliser_setSourceAzi_deg (void *const hBin, int index, float newAzi_deg)
 Sets the panning azimuth for a specific channel index, in DEGREES.
 
void binauraliser_setSourceElev_deg (void *const hBin, int index, float newElev_deg)
 Sets the panning elevation for a specific channel index, in DEGREES.
 
void binauraliser_setNumSources (void *const hBin, int new_nSources)
 Sets the number of input channels/sources to binauralise.
 
void binauraliser_setUseDefaultHRIRsflag (void *const hBin, 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 binauraliser_setSofaFilePath (void *const hBin, const char *path)
 Sets the file path for a .sofa file, in order to employ a custom HRIR set for the decoding.
 
void binauraliser_setEnableHRIRsDiffuseEQ (void *const hBin, int newState)
 Enable (1) or disable (0) the diffuse-field EQ applied to the HRTFs.
 
void binauraliser_setInputConfigPreset (void *const hBin, int newPresetID)
 Loads an input preset (see SOURCE_CONFIG_PRESETS enum)
 
void binauraliser_setEnableRotation (void *const hBin, int newState)
 Sets the flag to enable/disable (1 or 0) rotation.
 
void binauraliser_setYaw (void *const hBin, float newYaw)
 Sets the 'yaw' rotation angle, in DEGREES.
 
void binauraliser_setPitch (void *const hBin, float newPitch)
 Sets the 'pitch' rotation angle, in DEGREES.
 
void binauraliser_setRoll (void *const hBin, float newRoll)
 Sets the 'roll' rotation angle, in DEGREES.
 
void binauraliser_setFlipYaw (void *const hBin, int newState)
 Sets a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)
 
void binauraliser_setFlipPitch (void *const hBin, int newState)
 Sets a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)
 
void binauraliser_setFlipRoll (void *const hBin, int newState)
 Sets a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)
 
void binauraliser_setRPYflag (void *const hBin, int newState)
 Sets a flag as to whether to use "yaw-pitch-roll" (0) or "roll-pitch-yaw" (1) rotation order.
 
void binauraliser_setInterpMode (void *const hBin, int newMode)
 NOT IMPLEMENTED YET.
 
void binauraliser_setSourceGain (void *const hBin, int srcIdx, float newGain)
 Sets gain factor for an input source.
 
void binauraliser_setSourceSolo (void *const hBin, int srcIdx)
 Set a source to solo.
 
void binauraliser_setUnSolo (void *const hBin)
 Unsolo / unmute all sources.
 
int binauraliser_getFrameSize (void)
 Returns the processing framesize (i.e., number of samples processed with every _process() call )
 
CODEC_STATUS binauraliser_getCodecStatus (void *const hBin)
 Returns current codec status codec status (see CODEC_STATUS enum)
 
float binauraliser_getProgressBar0_1 (void *const hBin)
 (Optional) Returns current intialisation/processing progress, between 0..1
 
void binauraliser_getProgressBarText (void *const hBin, char *text)
 (Optional) Returns current intialisation/processing progress text
 
float binauraliser_getSourceAzi_deg (void *const hBin, int index)
 Returns the source azimuth for a given index, in DEGREES.
 
float binauraliser_getSourceElev_deg (void *const hBin, int index)
 Returns the source elevation for a given index, in DEGREES.
 
int binauraliser_getNumSources (void *const hBin)
 Returns the number of inputs/sources in the current layout.
 
int binauraliser_getMaxNumSources (void)
 Returns the maximum number of input sources supported by binauraliser.
 
int binauraliser_getNumEars (void)
 Returns the number of ears possessed by the average homo sapien.
 
int binauraliser_getNDirs (void *const hBin)
 Returns the number of directions in the currently used HRIR set.
 
int binauraliser_getNTriangles (void *const hBin)
 Returns the number of triangular groupings (faces) returned by the Convex Hull.
 
float binauraliser_getHRIRAzi_deg (void *const hBin, int index)
 Returns the HRIR/HRTF azimuth for a given index, in DEGREES.
 
float binauraliser_getHRIRElev_deg (void *const hBin, int index)
 Returns the HRIR/HRTF elevation for a given index, in DEGREES.
 
int binauraliser_getHRIRlength (void *const hBin)
 Returns the length of HRIRs in time-domain samples.
 
int binauraliser_getHRIRsamplerate (void *const hBin)
 Returns the HRIR sample rate.
 
int binauraliser_getUseDefaultHRIRsflag (void *const hBin)
 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 * binauraliser_getSofaFilePath (void *const hBin)
 Returns the file path for a .sofa file.
 
int binauraliser_getEnableHRIRsDiffuseEQ (void *const hBin)
 Returns the flag indicating whether the diffuse-field EQ applied to the HRTFs is enabled (1) or disabled (0).
 
int binauraliser_getDAWsamplerate (void *const hBin)
 Returns the DAW/Host sample rate.
 
int binauraliser_getEnableRotation (void *const hBin)
 Returns the flag value which dictates whether to enable/disable sound-field rotation (0: disabled, 1: enabled)
 
float binauraliser_getYaw (void *const hBin)
 Returns the 'yaw' rotation angle, in DEGREES.
 
float binauraliser_getPitch (void *const hBin)
 Returns the 'pitch' rotation angle, in DEGREES.
 
float binauraliser_getRoll (void *const hBin)
 Returns the 'roll' rotation angle, in DEGREES.
 
int binauraliser_getFlipYaw (void *const hBin)
 Returns a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)
 
int binauraliser_getFlipPitch (void *const hBin)
 Returns a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)
 
int binauraliser_getFlipRoll (void *const hBin)
 Returns a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)
 
int binauraliser_getRPYflag (void *const hBin)
 Returns a flag as to whether to use "yaw-pitch-roll" (0) or "roll-pitch-yaw" (1) rotation order.
 
int binauraliser_getInterpMode (void *const hBin)
 NOT IMPLEMENTED YET.
 
int binauraliser_getProcessingDelay (void)
 Returns the processing delay in samples (may be used for delay compensation purposes)
 

Detailed Description

Convolves input audio (up to 64 channels) with interpolated HRTFs in the time-frequency domain.

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.

Author
Leo McCormack
Date
25.09.2017
License
ISC

Definition in file binauraliser.h.

Enumeration Type Documentation

◆ INTERP_MODES

Available interpolation modes.

Enumerator
INTERP_TRI 

Triangular interpolation.

INTERP_TRI_PS 

Triangular interpolation (with phase-simplification)

Examples
binauraliser.h.

Definition at line 58 of file binauraliser.h.

Function Documentation

◆ binauraliser_create()

void binauraliser_create ( void **const phBin)

Creates an instance of the binauraliser.

Parameters
[in]phBin(&) address of binauraliser handle
Examples
binauraliser.h.

Definition at line 35 of file binauraliser.c.

◆ binauraliser_destroy()

void binauraliser_destroy ( void **const phBin)

Destroys an instance of the binauraliser.

Parameters
[in]phBin(&) address of binauraliser handle
Examples
binauraliser.h.

Definition at line 99 of file binauraliser.c.

◆ binauraliser_getCodecStatus()

CODEC_STATUS binauraliser_getCodecStatus ( void *const hBin)

Returns current codec status codec status (see CODEC_STATUS enum)

Examples
binauraliser.h.

Definition at line 485 of file binauraliser.c.

◆ binauraliser_getDAWsamplerate()

int binauraliser_getDAWsamplerate ( void *const hBin)

Returns the DAW/Host sample rate.

Examples
binauraliser.h.

Definition at line 594 of file binauraliser.c.

◆ binauraliser_getEnableHRIRsDiffuseEQ()

int binauraliser_getEnableHRIRsDiffuseEQ ( void *const hBin)

Returns the flag indicating whether the diffuse-field EQ applied to the HRTFs is enabled (1) or disabled (0).

Examples
binauraliser.h.

Definition at line 588 of file binauraliser.c.

◆ binauraliser_getEnableRotation()

int binauraliser_getEnableRotation ( void *const hBin)

Returns the flag value which dictates whether to enable/disable sound-field rotation (0: disabled, 1: enabled)

Examples
binauraliser.h.

Definition at line 600 of file binauraliser.c.

◆ binauraliser_getFlipPitch()

int binauraliser_getFlipPitch ( void *const hBin)

Returns a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)

Examples
binauraliser.h.

Definition at line 630 of file binauraliser.c.

◆ binauraliser_getFlipRoll()

int binauraliser_getFlipRoll ( void *const hBin)

Returns a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)

Examples
binauraliser.h.

Definition at line 636 of file binauraliser.c.

◆ binauraliser_getFlipYaw()

int binauraliser_getFlipYaw ( void *const hBin)

Returns a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)

Examples
binauraliser.h.

Definition at line 624 of file binauraliser.c.

◆ binauraliser_getFrameSize()

int binauraliser_getFrameSize ( void )

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

Examples
binauraliser.h.

Definition at line 480 of file binauraliser.c.

◆ binauraliser_getHRIRAzi_deg()

float binauraliser_getHRIRAzi_deg ( void *const hBin,
int index )

Returns the HRIR/HRTF azimuth for a given index, in DEGREES.

Examples
binauraliser.h.

Definition at line 543 of file binauraliser.c.

◆ binauraliser_getHRIRElev_deg()

float binauraliser_getHRIRElev_deg ( void *const hBin,
int index )

Returns the HRIR/HRTF elevation for a given index, in DEGREES.

Examples
binauraliser.h.

Definition at line 552 of file binauraliser.c.

◆ binauraliser_getHRIRlength()

int binauraliser_getHRIRlength ( void *const hBin)

Returns the length of HRIRs in time-domain samples.

Examples
binauraliser.h.

Definition at line 561 of file binauraliser.c.

◆ binauraliser_getHRIRsamplerate()

int binauraliser_getHRIRsamplerate ( void *const hBin)

Returns the HRIR sample rate.

Examples
binauraliser.h.

Definition at line 567 of file binauraliser.c.

◆ binauraliser_getInterpMode()

int binauraliser_getInterpMode ( void *const hBin)

NOT IMPLEMENTED YET.

Examples
binauraliser.h.

Definition at line 648 of file binauraliser.c.

◆ binauraliser_getMaxNumSources()

int binauraliser_getMaxNumSources ( void )

Returns the maximum number of input sources supported by binauraliser.

Examples
binauraliser.h.

Definition at line 521 of file binauraliser.c.

◆ binauraliser_getNDirs()

int binauraliser_getNDirs ( void *const hBin)

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

Examples
binauraliser.h.

Definition at line 531 of file binauraliser.c.

◆ binauraliser_getNTriangles()

int binauraliser_getNTriangles ( void *const hBin)

Returns the number of triangular groupings (faces) returned by the Convex Hull.

Examples
binauraliser.h.

Definition at line 537 of file binauraliser.c.

◆ binauraliser_getNumEars()

int binauraliser_getNumEars ( void )

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

Examples
binauraliser.h.

Definition at line 526 of file binauraliser.c.

◆ binauraliser_getNumSources()

int binauraliser_getNumSources ( void *const hBin)

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

Examples
binauraliser.h.

Definition at line 515 of file binauraliser.c.

◆ binauraliser_getPitch()

float binauraliser_getPitch ( void *const hBin)

Returns the 'pitch' rotation angle, in DEGREES.

Examples
binauraliser.h.

Definition at line 612 of file binauraliser.c.

◆ binauraliser_getProcessingDelay()

int binauraliser_getProcessingDelay ( void )

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

Examples
binauraliser.h.

Definition at line 654 of file binauraliser.c.

◆ binauraliser_getProgressBar0_1()

float binauraliser_getProgressBar0_1 ( void *const hBin)

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

  • 0: intialisation/processing has started
  • 1: intialisation/processing has ended
Examples
binauraliser.h.

Definition at line 491 of file binauraliser.c.

◆ binauraliser_getProgressBarText()

void binauraliser_getProgressBarText ( void *const hBin,
char * text )

(Optional) Returns current intialisation/processing progress text

Note
"text" string should be (at least) of length: PROGRESSBARTEXT_CHAR_LENGTH
Examples
binauraliser.h.

Definition at line 497 of file binauraliser.c.

◆ binauraliser_getRoll()

float binauraliser_getRoll ( void *const hBin)

Returns the 'roll' rotation angle, in DEGREES.

Examples
binauraliser.h.

Definition at line 618 of file binauraliser.c.

◆ binauraliser_getRPYflag()

int binauraliser_getRPYflag ( void *const hBin)

Returns a flag as to whether to use "yaw-pitch-roll" (0) or "roll-pitch-yaw" (1) rotation order.

Examples
binauraliser.h.

Definition at line 642 of file binauraliser.c.

◆ binauraliser_getSofaFilePath()

char * binauraliser_getSofaFilePath ( void *const hBin)

Returns the file path for a .sofa file.

Note
If the custom set fails to load correctly, binauraliser will revert to the defualt set. Use 'binauraliser_getUseDefaultHRIRsflag()' to check if loading was successful.
Parameters
[in]hBinbinauraliser handle
Returns
File path to .sofa file (WITH file extension)
Examples
binauraliser.h.

Definition at line 579 of file binauraliser.c.

◆ binauraliser_getSourceAzi_deg()

float binauraliser_getSourceAzi_deg ( void *const hBin,
int index )

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

Examples
binauraliser.h.

Definition at line 503 of file binauraliser.c.

◆ binauraliser_getSourceElev_deg()

float binauraliser_getSourceElev_deg ( void *const hBin,
int index )

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

Examples
binauraliser.h.

Definition at line 509 of file binauraliser.c.

◆ binauraliser_getUseDefaultHRIRsflag()

int binauraliser_getUseDefaultHRIRsflag ( void *const hBin)

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, binauraliser will revert to the defualt set, so this will be '1'
Examples
binauraliser.h.

Definition at line 573 of file binauraliser.c.

◆ binauraliser_getYaw()

float binauraliser_getYaw ( void *const hBin)

Returns the 'yaw' rotation angle, in DEGREES.

Examples
binauraliser.h.

Definition at line 606 of file binauraliser.c.

◆ binauraliser_init()

void binauraliser_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]hBinbinauraliser handle
[in]samplerateHost samplerate.
Examples
binauraliser.h.

Definition at line 137 of file binauraliser.c.

◆ binauraliser_initCodec()

void binauraliser_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]hBinbinauraliser handle
Examples
binauraliser.h.

Definition at line 157 of file binauraliser.c.

◆ binauraliser_process()

void binauraliser_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]hBinbinauraliser handle
[in]inputsInput channel buffers; 2-D array: nInputs x nSamples
[in]outputsOutput channel buffers; 2-D array: nOutputs x nSamples
[in]nInputsNumber of input channels
[in]nOutputsNumber of output channels
[in]nSamplesNumber of samples in 'inputs'/'output' matrices
Examples
binauraliser.h.

Definition at line 193 of file binauraliser.c.

◆ binauraliser_refreshSettings()

void binauraliser_refreshSettings ( void *const hBin)

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

Examples
binauraliser.h.

Definition at line 291 of file binauraliser.c.

◆ binauraliser_setEnableHRIRsDiffuseEQ()

void binauraliser_setEnableHRIRsDiffuseEQ ( void *const hBin,
int newState )

Enable (1) or disable (0) the diffuse-field EQ applied to the HRTFs.

Examples
binauraliser.h.

Definition at line 354 of file binauraliser.c.

◆ binauraliser_setEnableRotation()

void binauraliser_setEnableRotation ( void *const hBin,
int newState )

Sets the flag to enable/disable (1 or 0) rotation.

Examples
binauraliser.h.

Definition at line 376 of file binauraliser.c.

◆ binauraliser_setFlipPitch()

void binauraliser_setFlipPitch ( void *const hBin,
int newState )

Sets a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)

Examples
binauraliser.h.

Definition at line 418 of file binauraliser.c.

◆ binauraliser_setFlipRoll()

void binauraliser_setFlipRoll ( void *const hBin,
int newState )

Sets a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)

Examples
binauraliser.h.

Definition at line 427 of file binauraliser.c.

◆ binauraliser_setFlipYaw()

void binauraliser_setFlipYaw ( void *const hBin,
int newState )

Sets a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)

Examples
binauraliser.h.

Definition at line 409 of file binauraliser.c.

◆ binauraliser_setInputConfigPreset()

void binauraliser_setInputConfigPreset ( void *const hBin,
int newPresetID )

Loads an input preset (see SOURCE_CONFIG_PRESETS enum)

Examples
binauraliser.h.

Definition at line 363 of file binauraliser.c.

◆ binauraliser_setInterpMode()

void binauraliser_setInterpMode ( void *const hBin,
int newMode )

NOT IMPLEMENTED YET.

Examples
binauraliser.h.

Definition at line 443 of file binauraliser.c.

◆ binauraliser_setNumSources()

void binauraliser_setNumSources ( void *const hBin,
int new_nSources )

Sets the number of input channels/sources to binauralise.

Examples
binauraliser.h.

Definition at line 327 of file binauraliser.c.

◆ binauraliser_setPitch()

void binauraliser_setPitch ( void *const hBin,
float newPitch )

Sets the 'pitch' rotation angle, in DEGREES.

Examples
binauraliser.h.

Definition at line 395 of file binauraliser.c.

◆ binauraliser_setRoll()

void binauraliser_setRoll ( void *const hBin,
float newRoll )

Sets the 'roll' rotation angle, in DEGREES.

Examples
binauraliser.h.

Definition at line 402 of file binauraliser.c.

◆ binauraliser_setRPYflag()

void binauraliser_setRPYflag ( void *const hBin,
int newState )

Sets a flag as to whether to use "yaw-pitch-roll" (0) or "roll-pitch-yaw" (1) rotation order.

Examples
binauraliser.h.

Definition at line 436 of file binauraliser.c.

◆ binauraliser_setSofaFilePath()

void binauraliser_setSofaFilePath ( void *const hBin,
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, binauraliser will revert to the defualt set. Use binauraliser_getUseDefaultHRIRsflag() to check if loading was successful.
Parameters
[in]hBinbinauraliser handle
[in]pathFile path to .sofa file (WITH file extension)
Examples
binauraliser.h.

Definition at line 344 of file binauraliser.c.

◆ binauraliser_setSourceAzi_deg()

void binauraliser_setSourceAzi_deg ( void *const hBin,
int index,
float newAzi_deg )

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

Examples
binauraliser.h.

Definition at line 301 of file binauraliser.c.

◆ binauraliser_setSourceElev_deg()

void binauraliser_setSourceElev_deg ( void *const hBin,
int index,
float newElev_deg )

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

Examples
binauraliser.h.

Definition at line 315 of file binauraliser.c.

◆ binauraliser_setSourceGain()

void binauraliser_setSourceGain ( void *const hBin,
int srcIdx,
float newGain )

Sets gain factor for an input source.

Examples
binauraliser.h.

Definition at line 452 of file binauraliser.c.

◆ binauraliser_setSourceSolo()

void binauraliser_setSourceSolo ( void *const hBin,
int srcIdx )

Set a source to solo.

Examples
binauraliser.h.

Definition at line 458 of file binauraliser.c.

◆ binauraliser_setUnSolo()

void binauraliser_setUnSolo ( void *const hBin)

Unsolo / unmute all sources.

Examples
binauraliser.h.

Definition at line 470 of file binauraliser.c.

◆ binauraliser_setUseDefaultHRIRsflag()

void binauraliser_setUseDefaultHRIRsflag ( void *const hBin,
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, binauraliser will revert to the defualt set. Use binauraliser_getUseDefaultHRIRsflag() to check if loading was successful.
Examples
binauraliser.h.

Definition at line 335 of file binauraliser.c.

◆ binauraliser_setYaw()

void binauraliser_setYaw ( void *const hBin,
float newYaw )

Sets the 'yaw' rotation angle, in DEGREES.

Examples
binauraliser.h.

Definition at line 388 of file binauraliser.c.