A frequency-dependent Ambisonic decoder for reproducing Ambisonic sound scenes over loudspeakers. More...

#include "_common.h"

Macros
#define	AMBI_DEC_NUM_DECODING_METHODS ( 4 )
	Number of decoding method options.

#define	AMBI_DEC_TRANSITION_MIN_VALUE ( 500.0f )
	Minimum transition value between low/high frequency decoders, in Hz.

#define	AMBI_DEC_TRANSITION_MAX_VALUE ( 2000.0f )
	Maximum transition value between low/high frequency decoders, in Hz.

Enumerations
enum	AMBI_DEC_DECODING_METHODS { DECODING_METHOD_SAD = 1 , DECODING_METHOD_MMD , DECODING_METHOD_EPAD , DECODING_METHOD_ALLRAD }
	Available decoding methods. More...

enum	AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH { AMPLITUDE_PRESERVING =1 , ENERGY_PRESERVING }
	When using mixed order decoding (i.e. More...

Functions
void	ambi_dec_create (void **const phAmbi)
	Creates an instance of the ambi_dec.

void	ambi_dec_destroy (void **const phAmbi)
	Destroys an instance of the ambi_dec.

void	ambi_dec_init (void *const hAmbi, int samplerate)
	Initialises an instance of ambi_dec with default settings.

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

void	ambi_dec_process (void const hAmbi, const float const inputs, float const *outputs, int nInputs, int nOutputs, int nSamples)
	Decodes input spherical harmonic signals to the loudspeaker channels.

void	ambi_dec_refreshSettings (void *const hAmbi)
	Sets all intialisation flags to 1.

void	ambi_dec_setMasterDecOrder (void *const hAmbi, int newValue)
	Sets the master decoding order.

void	ambi_dec_setDecOrder (void *const hAmbi, int newValue, int bandIdx)
	Sets the decoding order for a given frequency band.

void	ambi_dec_setDecOrderAllBands (void *const hAmbi, int newValue)
	Sets the decoding order for all frequency bands.

void	ambi_dec_setLoudspeakerAzi_deg (void *const hAmbi, int index, float newAzi_deg)
	Sets the azimuth of a specific loudspeaker.

void	ambi_dec_setLoudspeakerElev_deg (void *const hAmbi, int index, float newElev_deg)
	Sets the elevation of a specific loudspeaker.

void	ambi_dec_setNumLoudspeakers (void *const hAmbi, int new_nLoudspeakers)
	Sets the number of loudspeakers to decode to.

void	ambi_dec_setBinauraliseLSflag (void *const hAmbi, int newState)
	Sets flag to dictate whether the output loudspeaker signals should be binauralised.

void	ambi_dec_setUseDefaultHRIRsflag (void *const hAmbi, 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	ambi_dec_setSofaFilePath (void const hAmbi, const char path)
	Sets the file path for a .sofa file, in order to employ a custom HRIR set for the decoding.

void	ambi_dec_setEnableHRIRsPreProc (void *const hAmbi, int newState)
	Enable (1) or disable (0) the pre-processing applied to the HRTFs.

void	ambi_dec_setSourcePreset (void *const hAmbi, int newPresetID)
	Sets the source preset (ideal SH or SH signals derived from mic arrays)

void	ambi_dec_setOutputConfigPreset (void *const hAmbi, int newPresetID)
	Sets the output loudspeaker preset.

void	ambi_dec_setChOrder (void *const hAmbi, int newOrder)
	Sets the Ambisonic channel ordering convention to decode with, in order to match the convention employed by the input signals (see CH_ORDER enum)

void	ambi_dec_setNormType (void *const hAmbi, int newType)
	Sets the Ambisonic normalisation convention to decode with, in order to match with the convention employed by the input signals (see NORM_TYPES enum)

void	ambi_dec_setDecMethod (void *const hAmbi, int index, int newID)
	Sets the decoding method for a specific decoder.

void	ambi_dec_setDecEnableMaxrE (void *const hAmbi, int index, int newID)
	Sets a flag to enable/disable (1 or 0) the max_rE weighting for one of the decoders.

void	ambi_dec_setDecNormType (void *const hAmbi, int index, int newID)
	Sets the equalisation approach for one of the decoders.

void	ambi_dec_setTransitionFreq (void *const hAmbi, float newValue)
	Sets the frequeny at which to transition from the low frequency decoder to the high frequency decoder.

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

CODEC_STATUS	ambi_dec_getCodecStatus (void *const hAmbi)
	Returns current codec status (see CODEC_STATUS enum)

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

void	ambi_dec_getProgressBarText (void const hAmbi, char text)
	(Optional) Returns current intialisation/processing progress text

int	ambi_dec_getMasterDecOrder (void *const hAmbi)
	Returns the master/maximum decoding order (see SH_ORDERS enum)

int	ambi_dec_getDecOrder (void *const hAmbi, int bandIdx)
	Returns the decoding order for a given frequency band index (see SH_ORDERS enum)

int	ambi_dec_getDecOrderAllBands (void *const hAmbi)
	Returns the decoding order for the first band (see SH_ORDERS enum)

void	ambi_dec_getDecOrderHandle (void const hAmbi, float pX_vector, int pY_values, int pNpoints)
	Returns handles for the decoding orders and frequency vector.

int	ambi_dec_getNumberOfBands (void)
	Returns the number of frequency bands employed by ambi_dec.

float	ambi_dec_getLoudspeakerAzi_deg (void *const hAmbi, int index)
	Returns the loudspeaker azimuth in degrees for a given index.

float	ambi_dec_getLoudspeakerElev_deg (void *const hAmbi, int index)
	Returns the loudspeaker elevation in degrees for a given index.

int	ambi_dec_getNumLoudspeakers (void *const hAmbi)
	Returns the number of loudspeakers in the current layout.

int	ambi_dec_getMaxNumLoudspeakers (void)
	Returns the maximum number of loudspeakers supported by ambi_dec.

int	ambi_dec_getNSHrequired (void *const hAmbi)
	Returns the number of spherical harmonic signals required by the current decoding order: (current_order + 1)^2.

int	ambi_dec_getBinauraliseLSflag (void *const hAmbi)
	Returns the value of a flag used to dictate whether the loudspeaker signals should be binauralised (0: output loudspeaker signals, 1: output binaural signals).

int	ambi_dec_getUseDefaultHRIRsflag (void *const hAmbi)
	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 *	ambi_dec_getSofaFilePath (void *const hAmbi)
	Returns the file path for a .sofa file (WITH file extension)

int	ambi_dec_getEnableHRIRsPreProc (void *const hAmbi)
	Returns the flag indicating whether the pre-processing applied to the HRTFs is enabled (1) or disabled (0)

int	ambi_dec_getChOrder (void *const hAmbi)
	Returns the Ambisonic channel ordering convention currently being used to decode with, which should match the convention employed by the input signals (see CH_ORDER enum)

int	ambi_dec_getNormType (void *const hAmbi)
	Returns the Ambisonic normalisation convention currently being usedto decode with, which should match the convention employed by the input signals (see NORM_TYPES enum).

int	ambi_dec_getDecMethod (void *const hAmbi, int index)
	Returns the currently selected decoding method (see AMBI_DEC_DECODING_METHODS enum)

int	ambi_dec_getDecEnableMaxrE (void *const hAmbi, int index)
	Returns the value of a flag used to dictate whether the max_rE weighting is being applied by a given decoder.

int	ambi_dec_getDecNormType (void *const hAmbi, int index)
	Returns the current equalisation approach for one of the decoders (see AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH enum)

float	ambi_dec_getTransitionFreq (void *const hAmbi)
	Returns the frequency (in Hz) at which to transition from the low frequency decoder to the high frequency decoder.

int	ambi_dec_getHRIRsamplerate (void *const hAmbi)
	Returns the HRIR sample rate.

int	ambi_dec_getDAWsamplerate (void *const hAmbi)
	Returns the DAW/Host sample rate.

int	ambi_dec_getProcessingDelay (void)
	Returns the processing delay in samples; may be used for delay compensation features.

Detailed Description

A frequency-dependent Ambisonic decoder for reproducing Ambisonic sound scenes over loudspeakers.

Different decoder settings can be specified for the low and high frequencies. A number of decoding options are also offered, including [1,2]. When utilising spherical harmonic signals derived from real microphone arrays, this implementation also allows the decoding order to be specified per frequency band; of course, this may also be used creatively. An optional, loudspeaker channel binauraliser is included, along with with SOFA file loading, for headphone listening.

The algorithms utilised in this Ambisonic decoder were pieced together and developed in collaboration with Archontis Politis.

Test: test__saf_example_ambi_dec()

See also: [1] Zotter F, Pomberger H, Noisternig M. Energy–preserving ambisonic decoding. Acta Acustica united with Acustica. 2012 Jan 1; 98(1):37-47.; [2] Zotter F, Frank M. All-round ambisonic panning and decoding. Journal of the audio engineering society. 2012 Nov 26; 60(10):807-20.

Author: Leo McCormack

Date: 07.12.2017

License: ISC

Definition in file ambi_dec.h.

Macro Definition Documentation

◆ AMBI_DEC_NUM_DECODING_METHODS

#define AMBI_DEC_NUM_DECODING_METHODS ( 4 )

Number of decoding method options.

Definition at line 82 of file ambi_dec.h.

◆ AMBI_DEC_TRANSITION_MAX_VALUE

#define AMBI_DEC_TRANSITION_MAX_VALUE ( 2000.0f )

Maximum transition value between low/high frequency decoders, in Hz.

Definition at line 102 of file ambi_dec.h.

◆ AMBI_DEC_TRANSITION_MIN_VALUE

#define AMBI_DEC_TRANSITION_MIN_VALUE ( 500.0f )

Minimum transition value between low/high frequency decoders, in Hz.

Definition at line 99 of file ambi_dec.h.

Enumeration Type Documentation

◆ AMBI_DEC_DECODING_METHODS

enum AMBI_DEC_DECODING_METHODS

Available decoding methods.

See saf_hoa_internal.h for a more indepth description of each decoding approach.

Enumerator
DECODING_METHOD_SAD	Sampling Ambisonic Decoder (SAD)
DECODING_METHOD_MMD	Mode-Matching Decoder (MMD)
DECODING_METHOD_EPAD	Energy-Preserving Ambisonic Decoder (EPAD)
DECODING_METHOD_ALLRAD	All-Round Ambisonic Decoder (AllRAD)

Examples: ambi_dec.h.

Definition at line 73 of file ambi_dec.h.

◆ AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH

enum AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH

When using mixed order decoding (i.e.

different decoding orders for different frequencies), this equalisation helps maintain equal perceived "loudness"

At low frequencies, preserving amplitude is more favourable, whereas for high frequencies, preserving energy is better.

Enumerator
AMPLITUDE_PRESERVING	preserve omni amplitude
ENERGY_PRESERVING	preserve omni energy

Examples: ambi_dec.h.

Definition at line 92 of file ambi_dec.h.

Function Documentation

◆ ambi_dec_create()

void ambi_dec_create ( void **const phAmbi )

Creates an instance of the ambi_dec.

Parameters

[in] phAmbi (&) address of ambi_dec handle

Examples: ambi_dec.h.

Definition at line 48 of file ambi_dec.c.

◆ ambi_dec_destroy()

void ambi_dec_destroy ( void **const phAmbi )

Destroys an instance of the ambi_dec.

Parameters

[in] phAmbi (&) address of ambi_dec handle

Examples: ambi_dec.h.

Definition at line 119 of file ambi_dec.c.

◆ ambi_dec_getBinauraliseLSflag()

int ambi_dec_getBinauraliseLSflag ( void *const hAmbi )

Returns the value of a flag used to dictate whether the loudspeaker signals should be binauralised (0: output loudspeaker signals, 1: output binaural signals).

Examples: ambi_dec.h.

Definition at line 920 of file ambi_dec.c.

◆ ambi_dec_getChOrder()

int ambi_dec_getChOrder ( void *const hAmbi )

Returns the Ambisonic channel ordering convention currently being used to decode with, which should match the convention employed by the input signals (see CH_ORDER enum)

Examples: ambi_dec.h.

Definition at line 948 of file ambi_dec.c.

◆ ambi_dec_getCodecStatus()

CODEC_STATUS ambi_dec_getCodecStatus ( void *const hAmbi )

Returns current codec status (see CODEC_STATUS enum)

Examples: ambi_dec.h.

Definition at line 836 of file ambi_dec.c.

◆ ambi_dec_getDAWsamplerate()

int ambi_dec_getDAWsamplerate ( void *const hAmbi )

Returns the DAW/Host sample rate.

Examples: ambi_dec.h.

Definition at line 991 of file ambi_dec.c.

◆ ambi_dec_getDecEnableMaxrE()

int ambi_dec_getDecEnableMaxrE	(	void *const	hAmbi,
		int	index )

Returns the value of a flag used to dictate whether the max_rE weighting is being applied by a given decoder.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	Index for low (0) or high (1) frequency decoder

Returns: '0' if enabled, '1' if disabled

Examples: ambi_dec.h.

Definition at line 966 of file ambi_dec.c.

◆ ambi_dec_getDecMethod()

int ambi_dec_getDecMethod	(	void *const	hAmbi,
		int	index )

Returns the currently selected decoding method (see AMBI_DEC_DECODING_METHODS enum)

Examples: ambi_dec.h.

Definition at line 960 of file ambi_dec.c.

◆ ambi_dec_getDecNormType()

int ambi_dec_getDecNormType	(	void *const	hAmbi,
		int	index )

Returns the current equalisation approach for one of the decoders (see AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH enum)

Note: It is suggested to preserve amplitude at low-frequencies and energy at high-frequencies

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	Index for low (0) or high (1) frequency decoder

Returns: (see AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH enum)

Examples: ambi_dec.h.

Definition at line 972 of file ambi_dec.c.

◆ ambi_dec_getDecOrder()

int ambi_dec_getDecOrder	(	void *const	hAmbi,
		int	bandIdx )

Returns the decoding order for a given frequency band index (see SH_ORDERS enum)

Examples: ambi_dec.h.

Definition at line 860 of file ambi_dec.c.

◆ ambi_dec_getDecOrderAllBands()

int ambi_dec_getDecOrderAllBands ( void *const hAmbi )

Returns the decoding order for the first band (see SH_ORDERS enum)

Examples: ambi_dec.h.

Definition at line 866 of file ambi_dec.c.

◆ ambi_dec_getDecOrderHandle()

void ambi_dec_getDecOrderHandle	(	void *const	hAmbi,
		float **	pX_vector,
		int **	pY_values,
		int *	pNpoints )

Returns handles for the decoding orders and frequency vector.

Parameters

[in]	hAmbi	ambi_dec handle
[out]	pX_vector	(&) frequency vector; pNpoints x 1
[out]	pY_values	(&) decoding order per frequency; pNpoints x 1
[out]	pNpoints	(&) number of grid points.

Examples: ambi_dec.h.

Definition at line 872 of file ambi_dec.c.

◆ ambi_dec_getEnableHRIRsPreProc()

int ambi_dec_getEnableHRIRsPreProc ( void *const hAmbi )

Returns the flag indicating whether the pre-processing applied to the HRTFs is enabled (1) or disabled (0)

Examples: ambi_dec.h.

Definition at line 942 of file ambi_dec.c.

◆ ambi_dec_getFrameSize()

int ambi_dec_getFrameSize ( void )

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

Examples: ambi_dec.h.

Definition at line 831 of file ambi_dec.c.

◆ ambi_dec_getHRIRsamplerate()

int ambi_dec_getHRIRsamplerate ( void *const hAmbi )

Returns the HRIR sample rate.

Examples: ambi_dec.h.

Definition at line 984 of file ambi_dec.c.

◆ ambi_dec_getLoudspeakerAzi_deg()

float ambi_dec_getLoudspeakerAzi_deg	(	void *const	hAmbi,
		int	index )

Returns the loudspeaker azimuth in degrees for a given index.

Examples: ambi_dec.h.

Definition at line 891 of file ambi_dec.c.

◆ ambi_dec_getLoudspeakerElev_deg()

float ambi_dec_getLoudspeakerElev_deg	(	void *const	hAmbi,
		int	index )

Returns the loudspeaker elevation in degrees for a given index.

Examples: ambi_dec.h.

Definition at line 897 of file ambi_dec.c.

◆ ambi_dec_getMasterDecOrder()

int ambi_dec_getMasterDecOrder ( void *const hAmbi )

Returns the master/maximum decoding order (see SH_ORDERS enum)

Examples: ambi_dec.h.

Definition at line 854 of file ambi_dec.c.

◆ ambi_dec_getMaxNumLoudspeakers()

int ambi_dec_getMaxNumLoudspeakers ( void )

Returns the maximum number of loudspeakers supported by ambi_dec.

Examples: ambi_dec.h.

Definition at line 909 of file ambi_dec.c.

◆ ambi_dec_getNormType()

int ambi_dec_getNormType ( void *const hAmbi )

Returns the Ambisonic normalisation convention currently being usedto decode with, which should match the convention employed by the input signals (see NORM_TYPES enum).

Examples: ambi_dec.h.

Definition at line 954 of file ambi_dec.c.

◆ ambi_dec_getNSHrequired()

int ambi_dec_getNSHrequired ( void *const hAmbi )

Returns the number of spherical harmonic signals required by the current decoding order: (current_order + 1)^2.

Examples: ambi_dec.h.

Definition at line 914 of file ambi_dec.c.

◆ ambi_dec_getNumberOfBands()

int ambi_dec_getNumberOfBands ( void )

Returns the number of frequency bands employed by ambi_dec.

Examples: ambi_dec.h.

Definition at line 886 of file ambi_dec.c.

◆ ambi_dec_getNumLoudspeakers()

int ambi_dec_getNumLoudspeakers ( void *const hAmbi )

Returns the number of loudspeakers in the current layout.

Examples: ambi_dec.h.

Definition at line 903 of file ambi_dec.c.

◆ ambi_dec_getProcessingDelay()

int ambi_dec_getProcessingDelay ( void )

Returns the processing delay in samples; may be used for delay compensation features.

Examples: ambi_dec.h.

Definition at line 997 of file ambi_dec.c.

◆ ambi_dec_getProgressBar0_1()

float ambi_dec_getProgressBar0_1 ( void *const hAmbi )

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

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

Examples: ambi_dec.h.

Definition at line 842 of file ambi_dec.c.

◆ ambi_dec_getProgressBarText()

void ambi_dec_getProgressBarText	(	void *const	hAmbi,
		char *	text )

(Optional) Returns current intialisation/processing progress text

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

Examples: ambi_dec.h.

Definition at line 848 of file ambi_dec.c.

◆ ambi_dec_getSofaFilePath()

char * ambi_dec_getSofaFilePath ( void *const hAmbi )

Returns the file path for a .sofa file (WITH file extension)

Note: If the custom set failes to load correctly, ambi_dec will revert to the default set. Use ambi_dec_getUseDefaultHRIRsflag() to check if loading was successful.

Examples: ambi_dec.h.

Definition at line 932 of file ambi_dec.c.

◆ ambi_dec_getTransitionFreq()

float ambi_dec_getTransitionFreq ( void *const hAmbi )

Returns the frequency (in Hz) at which to transition from the low frequency decoder to the high frequency decoder.

Examples: ambi_dec.h.

Definition at line 978 of file ambi_dec.c.

◆ ambi_dec_getUseDefaultHRIRsflag()

int ambi_dec_getUseDefaultHRIRsflag ( void *const hAmbi )

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 failes to load correctly, ambi_dec will revert to the default set.

Examples: ambi_dec.h.

Definition at line 926 of file ambi_dec.c.

◆ ambi_dec_init()

void ambi_dec_init	(	void *const	hAmbi,
		int	samplerate )

Initialises an instance of ambi_dec with default settings.

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

Parameters

[in]	hAmbi	ambi_dec handle
[in]	samplerate	Host samplerate.

Examples: ambi_dec.h.

Definition at line 170 of file ambi_dec.c.

◆ ambi_dec_initCodec()

void ambi_dec_initCodec ( void *const hAmbi )

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] hAmbi ambi_dec handle

Examples: ambi_dec.h.

Definition at line 183 of file ambi_dec.c.

◆ ambi_dec_process()

void ambi_dec_process	(	void *const	hAmbi,
		const float const	inputs,
		float const	outputs,
		int	nInputs,
		int	nOutputs,
		int	nSamples )

Decodes input spherical harmonic signals to the loudspeaker channels.

Parameters

[in]	hAmbi	ambi_dec 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: ambi_dec.h.

Definition at line 469 of file ambi_dec.c.

◆ ambi_dec_refreshSettings()

void ambi_dec_refreshSettings ( void *const hAmbi )

Sets all intialisation flags to 1.

Re-initialising all settings/variables, as ambi_dec is currently configured, at next available opportunity.

Examples: ambi_dec.h.

Definition at line 597 of file ambi_dec.c.

◆ ambi_dec_setBinauraliseLSflag()

void ambi_dec_setBinauraliseLSflag	(	void *const	hAmbi,
		int	newState )

Sets flag to dictate whether the output loudspeaker signals should be binauralised.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	newState	'0' output loudspeaker signals, '1' output binaural signals

Examples: ambi_dec.h.

Definition at line 673 of file ambi_dec.c.

◆ ambi_dec_setChOrder()

void ambi_dec_setChOrder	(	void *const	hAmbi,
		int	newOrder )

Sets the Ambisonic channel ordering convention to decode with, in order to match the convention employed by the input signals (see CH_ORDER enum)

Examples: ambi_dec.h.

Definition at line 789 of file ambi_dec.c.

◆ ambi_dec_setDecEnableMaxrE()

void ambi_dec_setDecEnableMaxrE	(	void *const	hAmbi,
		int	index,
		int	newID )

Sets a flag to enable/disable (1 or 0) the max_rE weighting for one of the decoders.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	For low (0) or high (1) frequency decoder
[in]	newID	'0' disabled, '1' enabled

Examples: ambi_dec.h.

Definition at line 810 of file ambi_dec.c.

◆ ambi_dec_setDecMethod()

void ambi_dec_setDecMethod	(	void *const	hAmbi,
		int	index,
		int	newID )

Sets the decoding method for a specific decoder.

ambi_dec employs two decoders, one for low frequencies and one for high frequencies. (use ambi_dec_setTransitionFreq() to dictate the transition frequency)

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	Index for low (0) or high (1) frequency decoder
[in]	newID	New decoding method (see AMBI_DEC_DECODING_METHODS enum)

Examples: ambi_dec.h.

Definition at line 803 of file ambi_dec.c.

◆ ambi_dec_setDecNormType()

void ambi_dec_setDecNormType	(	void *const	hAmbi,
		int	index,
		int	newID )

Sets the equalisation approach for one of the decoders.

This is used to help keep the perceived loudness consistent, when using mixed decoding orders (i.e. different decoding orders for different frequency bands) ambi_dec either to preserves amplitude or energy for each order.

Note: It is suggested to preserve amplitude at low-frequencies and energy at high-frequencies.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	For low (0) or high (1) frequency decoder
[in]	newID	see AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH enum

Examples: ambi_dec.h.

Definition at line 816 of file ambi_dec.c.

◆ ambi_dec_setDecOrder()

void ambi_dec_setDecOrder	(	void *const	hAmbi,
		int	newValue,
		int	bandIdx )

Sets the decoding order for a given frequency band.

Note: The maximum order is dictated by ambi_dec_setMasterDecOrder()

Parameters

[in]	hAmbi	ambi_dec handle
[in]	newValue	New decoding order
[in]	bandIdx	Frequency band index

Examples: ambi_dec.h.

Definition at line 619 of file ambi_dec.c.

◆ ambi_dec_setDecOrderAllBands()

void ambi_dec_setDecOrderAllBands	(	void *const	hAmbi,
		int	newValue )

Sets the decoding order for all frequency bands.

Note: the maximum order is dictated by ambi_dec_setMasterDecOrder()

Parameters

[in]	hAmbi	ambi_dec handle
[in]	newValue	New decoding order

Examples: ambi_dec.h.

Definition at line 625 of file ambi_dec.c.

◆ ambi_dec_setEnableHRIRsPreProc()

void ambi_dec_setEnableHRIRsPreProc	(	void *const	hAmbi,
		int	newState )

Enable (1) or disable (0) the pre-processing applied to the HRTFs.

Examples: ambi_dec.h.

Definition at line 703 of file ambi_dec.c.

◆ ambi_dec_setLoudspeakerAzi_deg()

void ambi_dec_setLoudspeakerAzi_deg	(	void *const	hAmbi,
		int	index,
		float	newAzi_deg )

Sets the azimuth of a specific loudspeaker.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	Loudspeaker index
[in]	newAzi_deg	New azimuth in DEGREES

Examples: ambi_dec.h.

Definition at line 634 of file ambi_dec.c.

◆ ambi_dec_setLoudspeakerElev_deg()

void ambi_dec_setLoudspeakerElev_deg	(	void *const	hAmbi,
		int	index,
		float	newElev_deg )

Sets the elevation of a specific loudspeaker.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	index	Loudspeaker index
[in]	newElev_deg	New elevation in DEGREES

Examples: ambi_dec.h.

Definition at line 648 of file ambi_dec.c.

◆ ambi_dec_setMasterDecOrder()

void ambi_dec_setMasterDecOrder	(	void *const	hAmbi,
		int	newValue )

Sets the master decoding order.

However, the decoding order may be lower than this for any given frequency, this is just the maximum.

If decoding order is higher than the input signal order, the extra required channels are filled with zeros. If the decoding order is lower than the input signal order, the number input signals is truncated accordingly. (see SH_ORDERS enum)

Examples: ambi_dec.h.

Definition at line 607 of file ambi_dec.c.

◆ ambi_dec_setNormType()

void ambi_dec_setNormType	(	void *const	hAmbi,
		int	newType )

Sets the Ambisonic normalisation convention to decode with, in order to match with the convention employed by the input signals (see NORM_TYPES enum)

Examples: ambi_dec.h.

Definition at line 796 of file ambi_dec.c.

◆ ambi_dec_setNumLoudspeakers()

void ambi_dec_setNumLoudspeakers	(	void *const	hAmbi,
		int	new_nLoudspeakers )

Sets the number of loudspeakers to decode to.

Examples: ambi_dec.h.

Definition at line 660 of file ambi_dec.c.

◆ ambi_dec_setOutputConfigPreset()

void ambi_dec_setOutputConfigPreset	(	void *const	hAmbi,
		int	newPresetID )

Sets the output loudspeaker preset.

For conveinience, presets for several popular arrangements are included (see LOUDSPEAKER_ARRAY_PRESETS enum).

Examples: ambi_dec.h.

Definition at line 712 of file ambi_dec.c.

◆ ambi_dec_setSofaFilePath()

void ambi_dec_setSofaFilePath	(	void *const	hAmbi,
		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 failes to load correctly, ambi_dec will revert to the default set. Use ambi_dec_getUseDefaultHRIRsflag() to check if loading was successful.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	path	File path to .sofa file (WITH file extension)

Examples: ambi_dec.h.

Definition at line 692 of file ambi_dec.c.

◆ ambi_dec_setSourcePreset()

void ambi_dec_setSourcePreset	(	void *const	hAmbi,
		int	newPresetID )

Sets the source preset (ideal SH or SH signals derived from mic arrays)

By default the decoder will decode at the maximum order for all frequencies. However, in the case of spherical harmonic input derived from microphone arrays, the available order is frequency dependent, therefore, different bands require different decoding orders. For conveinience, presets for a handful of comerically available microphone array are included (see MIC_PRESETS enum).

Examples: ambi_dec.h.

Definition at line 723 of file ambi_dec.c.

◆ ambi_dec_setTransitionFreq()

void ambi_dec_setTransitionFreq	(	void *const	hAmbi,
		float	newValue )

Sets the frequeny at which to transition from the low frequency decoder to the high frequency decoder.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	newValue	New transition frequency, in Hz

Examples: ambi_dec.h.

Definition at line 822 of file ambi_dec.c.

◆ ambi_dec_setUseDefaultHRIRsflag()

void ambi_dec_setUseDefaultHRIRsflag	(	void *const	hAmbi,
		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, ambi_dec will revert to the default set. Use ambi_dec_getUseDefaultHRIRsflag() to check if loading was successful.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	newState	'0' use custom HRIR set, '1' use default HRIR set

Examples: ambi_dec.h.

Definition at line 682 of file ambi_dec.c.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AMBI_DEC_NUM_DECODING_METHODS

◆ AMBI_DEC_TRANSITION_MAX_VALUE

◆ AMBI_DEC_TRANSITION_MIN_VALUE

Enumeration Type Documentation

◆ AMBI_DEC_DECODING_METHODS

◆ AMBI_DEC_DIFFUSE_FIELD_EQ_APPROACH

Function Documentation

◆ ambi_dec_create()

◆ ambi_dec_destroy()

◆ ambi_dec_getBinauraliseLSflag()

◆ ambi_dec_getChOrder()

◆ ambi_dec_getCodecStatus()

◆ ambi_dec_getDAWsamplerate()

◆ ambi_dec_getDecEnableMaxrE()

◆ ambi_dec_getDecMethod()

◆ ambi_dec_getDecNormType()

◆ ambi_dec_getDecOrder()

◆ ambi_dec_getDecOrderAllBands()

◆ ambi_dec_getDecOrderHandle()

◆ ambi_dec_getEnableHRIRsPreProc()

◆ ambi_dec_getFrameSize()

◆ ambi_dec_getHRIRsamplerate()

◆ ambi_dec_getLoudspeakerAzi_deg()

◆ ambi_dec_getLoudspeakerElev_deg()

◆ ambi_dec_getMasterDecOrder()

◆ ambi_dec_getMaxNumLoudspeakers()

◆ ambi_dec_getNormType()

◆ ambi_dec_getNSHrequired()

◆ ambi_dec_getNumberOfBands()

◆ ambi_dec_getNumLoudspeakers()

◆ ambi_dec_getProcessingDelay()

◆ ambi_dec_getProgressBar0_1()

◆ ambi_dec_getProgressBarText()

◆ ambi_dec_getSofaFilePath()

◆ ambi_dec_getTransitionFreq()

◆ ambi_dec_getUseDefaultHRIRsflag()

◆ ambi_dec_init()

◆ ambi_dec_initCodec()

◆ ambi_dec_process()

◆ ambi_dec_refreshSettings()

◆ ambi_dec_setBinauraliseLSflag()

◆ ambi_dec_setChOrder()

◆ ambi_dec_setDecEnableMaxrE()

◆ ambi_dec_setDecMethod()

◆ ambi_dec_setDecNormType()

◆ ambi_dec_setDecOrder()

◆ ambi_dec_setDecOrderAllBands()

◆ ambi_dec_setEnableHRIRsPreProc()

◆ ambi_dec_setLoudspeakerAzi_deg()

◆ ambi_dec_setLoudspeakerElev_deg()

◆ ambi_dec_setMasterDecOrder()

◆ ambi_dec_setNormType()

◆ ambi_dec_setNumLoudspeakers()

◆ ambi_dec_setOutputConfigPreset()

◆ ambi_dec_setSofaFilePath()

◆ ambi_dec_setSourcePreset()

◆ ambi_dec_setTransitionFreq()

◆ ambi_dec_setUseDefaultHRIRsflag()