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

#include "ambi_dec.h"
#include "saf.h"
#include "saf_externals.h"

Data Structures
struct	ambi_dec_codecPars
	Contains variables for sofa file loading, HRTF interpolation, and the loudspeaker decoders. More...

struct	ambi_dec_data
	Main structure for ambi_dec. More...

Macros
#define	AMBI_DEC_FRAME_SIZE ( 128 )
	Framesize, in time-domain samples.

#define	HOP_SIZE ( 128 )
	STFT hop size.

#define	HYBRID_BANDS ( HOP_SIZE + 5 )
	Number of frequency bands.

#define	TIME_SLOTS ( AMBI_DEC_FRAME_SIZE / HOP_SIZE )
	Number of STFT timeslots.

#define	MAX_NUM_LOUDSPEAKERS ( MAX_NUM_OUTPUTS )
	Maximum permitted output channels.

#define	MIN_NUM_LOUDSPEAKERS ( 4 )
	To avoid triangulation errors when using AllRAD.

#define	NUM_DECODERS ( 2 )
	One for low-frequencies and another for high-frequencies.

Functions
void	ambi_dec_setCodecStatus (void *const hCmp, CODEC_STATUS newStatus)
	Sets codec status (see CODEC_STATUS enum)

void	ambi_dec_interpHRTFs (void *const hAmbi, float azimuth_deg, float elevation_deg, float_complex h_intrp[HYBRID_BANDS][NUM_EARS])
	Interpolates between the 3 nearest HRTFs using amplitude-preserving VBAP gains.

void	loadLoudspeakerArrayPreset (LOUDSPEAKER_ARRAY_PRESETS preset, float dirs_deg[MAX_NUM_LOUDSPEAKERS][2], int nCH, int nDims)
	Returns the loudspeaker directions for a specified loudspeaker array preset.

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_internal.h.

Macro Definition Documentation

◆ AMBI_DEC_FRAME_SIZE

#define AMBI_DEC_FRAME_SIZE ( 128 )

Framesize, in time-domain samples.

Definition at line 65 of file ambi_dec_internal.h.

◆ HOP_SIZE

#define HOP_SIZE ( 128 )

STFT hop size.

Definition at line 68 of file ambi_dec_internal.h.

◆ HYBRID_BANDS

#define HYBRID_BANDS ( HOP_SIZE + 5 )

Number of frequency bands.

Definition at line 69 of file ambi_dec_internal.h.

◆ MAX_NUM_LOUDSPEAKERS

#define MAX_NUM_LOUDSPEAKERS ( MAX_NUM_OUTPUTS )

Maximum permitted output channels.

Definition at line 71 of file ambi_dec_internal.h.

◆ MIN_NUM_LOUDSPEAKERS

#define MIN_NUM_LOUDSPEAKERS ( 4 )

To avoid triangulation errors when using AllRAD.

Definition at line 72 of file ambi_dec_internal.h.

◆ NUM_DECODERS

#define NUM_DECODERS ( 2 )

One for low-frequencies and another for high-frequencies.

Definition at line 73 of file ambi_dec_internal.h.

◆ TIME_SLOTS

#define TIME_SLOTS ( AMBI_DEC_FRAME_SIZE / HOP_SIZE )

Number of STFT timeslots.

Definition at line 70 of file ambi_dec_internal.h.

Function Documentation

◆ ambi_dec_interpHRTFs()

void ambi_dec_interpHRTFs	(	void *const	hAmbi,
		float	azimuth_deg,
		float	elevation_deg,
		float_complex	h_intrp[HYBRID_BANDS][NUM_EARS] )

Interpolates between the 3 nearest HRTFs using amplitude-preserving VBAP gains.

The HRTF magnitude responses and HRIR ITDs are interpolated seperately before being re-combined.

Parameters

[in]	hAmbi	ambi_dec handle
[in]	azimuth_deg	Interpolation direction azimuth in DEGREES
[in]	elevation_deg	Interpolation direction elevation in DEGREES
[out]	h_intrp	Interpolated HRTF

Definition at line 59 of file ambi_dec_internal.c.

◆ ambi_dec_setCodecStatus()

void ambi_dec_setCodecStatus	(	void *const	hCmp,
		CODEC_STATUS	newStatus )

Sets codec status (see CODEC_STATUS enum)

Definition at line 48 of file ambi_dec_internal.c.

◆ loadLoudspeakerArrayPreset()

void loadLoudspeakerArrayPreset	(	LOUDSPEAKER_ARRAY_PRESETS	preset,
		float	dirs_deg[MAX_NUM_LOUDSPEAKERS][2],
		int *	nCH,
		int *	nDims )

Returns the loudspeaker directions for a specified loudspeaker array preset.

The function also returns the number of loudspeakers in the array, and a crude estimate of whether it is 2D or 3D (based on whether the sum of the absolute loudspeaker elevation angle is not zero). Note: 2-D setups which are not on the horizontal plane (i.e. all elevations==0) will be registered as a 3-D setup. Further Note: default uniformly distributed points are used to pad the dirs_deg matrix up to the MAX_NUM_LOUDSPEAKERS, if nCH is less than this. This can help avoid scenarios of many sources being panned in the same direction, or triangulations errors.