A frequency-dependent Ambisonic sound scene dynamic range compressor (DRC) More...

#include "_common.h"

Macros
#define	ENABLE_TF_DISPLAY
	Enable TF data display related function.

#define	AMBI_DRC_NUM_DISPLAY_SECONDS ( 8 )
	How many seconds the display will show historic TF data.

#define	AMBI_DRC_NUM_DISPLAY_TIME_SLOTS ( (int)(AMBI_DRC_NUM_DISPLAY_SECONDS*48000.0f/(float)128) )
	Number of time slots of historic TF data.

#define	AMBI_DRC_READ_OFFSET ( 200 )
	Number of samples to offset when reading TF data.

#define	AMBI_DRC_NUM_BANDS ( 133 )
	Number of frequency bands used during processing.

#define	AMBI_DRC_SPECTRAL_FLOOR (0.1585f)
	-16dB, maximum gain reduction for a given frequency band

#define	AMBI_DRC_IN_GAIN_MIN_VAL ( -40.0f )
	Minimum input gain, dB.

#define	AMBI_DRC_IN_GAIN_MAX_VAL ( 20.0f )
	Maximum input gain, dB.

#define	AMBI_DRC_THRESHOLD_MIN_VAL ( -60.0f )
	Minimum threshold, dB.

#define	AMBI_DRC_THRESHOLD_MAX_VAL ( 0.0f )
	Maximum threshold, dB.

#define	AMBI_DRC_RATIO_MIN_VAL ( 1.0f )
	Minimum ratio, X:1.

#define	AMBI_DRC_RATIO_MAX_VAL ( 30.0f )
	Maximum ratio, X:1.

#define	AMBI_DRC_KNEE_MIN_VAL ( 0.0f )
	Minimum knee, dB.

#define	AMBI_DRC_KNEE_MAX_VAL ( 10.0f )
	Maximum knee, dB.

#define	AMBI_DRC_ATTACK_MIN_VAL ( 10.0f )
	Minimum attack time, ms.

#define	AMBI_DRC_ATTACK_MAX_VAL ( 200.0f )
	Maximum attack time, ms.

#define	AMBI_DRC_RELEASE_MIN_VAL ( 50.0f )
	Minimum release time, ms.

#define	AMBI_DRC_RELEASE_MAX_VAL ( 1000.0f )
	Maximum release time, ms.

#define	AMBI_DRC_OUT_GAIN_MIN_VAL ( -20.0f )
	Minimum output gain, dB.

#define	AMBI_DRC_OUT_GAIN_MAX_VAL ( 40.0f )
	Maximum output gain, dB.

Functions
void	ambi_drc_create (void **const phAmbi)
	Creates an instance of the ambi_drc.

void	ambi_drc_destroy (void **const phAmbi)
	Destroys an instance of the ambi_drc.

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

void	ambi_drc_process (void const hAmbi, const float const inputs, float const *outputs, int nCH, int nSamples)
	Applies the frequency-dependent dynamic range compression to the input spherical harmonic signals.

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

void	ambi_drc_setThreshold (void *const hAmbi, float newValue)
	Sets the compressor threshold value in DECIBELS.

void	ambi_drc_setRatio (void *const hAmbi, float newValue)
	Sets the compression ratio.

void	ambi_drc_setKnee (void *const hAmbi, float newValue)
	Sets the compressor knee value; 0: hard knee, >0: soft knee, in DECIBELS.

void	ambi_drc_setInGain (void *const hAmbi, float newValue)
	Sets the compressor input gain value, in DECIBELS.

void	ambi_drc_setOutGain (void *const hAmbi, float newValue)
	Sets the compressor output gain value, in DECIBELS.

void	ambi_drc_setAttack (void *const hAmbi, float newValue)
	Sets the compressor envelope attack time, in miliseconds.

void	ambi_drc_setRelease (void *const hAmbi, float newValue)
	Sets the compressor envelope release time, in miliseconds.

void	ambi_drc_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_drc_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_drc_setInputPreset (void *const hAmbi, SH_ORDERS newPreset)
	Sets processing order.

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

float **	ambi_drc_getGainTF (void *const hAmbi)
	Returns pointers to historic time-frequency data, which may be used for plotting purposes.

int	ambi_drc_getGainTFwIdx (void *const hAmbi)
	Returns current TF gain data write index.

int	ambi_drc_getGainTFrIdx (void *const hAmbi)
	Returns current TF gain data read index.

float *	ambi_drc_getFreqVector (void const hAmbi, int nFreqPoints)
	Returns the frequency vector used by the processing.

float	ambi_drc_getThreshold (void *const hAmbi)
	Returns the compressor threshold value, in DECIBELS.

float	ambi_drc_getRatio (void *const hAmbi)
	Returns the compression ratio.

float	ambi_drc_getKnee (void *const hAmbi)
	Returns the compressor knee value 0: hard knee, >0: soft knee, in DECIBELS.

float	ambi_drc_getInGain (void *const hAmbi)
	Returns the compressor input gain value, in DECIBELS.

float	ambi_drc_getOutGain (void *const hAmbi)
	Returns the compressor output gain value, in DECIBELS.

float	ambi_drc_getAttack (void *const hAmbi)
	Returns the compressor envelope attack time, in miliseconds.

float	ambi_drc_getRelease (void *const hAmbi)
	Returns the compressor envelope release time, in miliseconds.

int	ambi_drc_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_drc_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)

SH_ORDERS	ambi_drc_getInputPreset (void *const hAmbi)
	Returns the current processing order (see SH_ORDERS enum)

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

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

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

Detailed Description

A frequency-dependent Ambisonic sound scene dynamic range compressor (DRC)

The implementation can also keep track of the frequency-dependent gain factors for the omnidirectional component over time (for optional plotting). The design is based on the algorithm presented in [1].

The DRC gain factors per band are determined based on the omnidirectional component, which are then applied to all of the higher-order components; thus, the spatial information of the Ambisonic sound scene is retained (although, your perception of them may change due to the DRC).

See also: [1] McCormack, L., & Välimäki, V. (2017). "FFT-Based Dynamic Range Compression". in Proceedings of the 14th Sound and Music Computing Conference, July 5-8, Espoo, Finland.

Author: Leo McCormack

Date: 07.01.2017

License: ISC

Definition in file ambi_drc.h.

Macro Definition Documentation

◆ AMBI_DRC_ATTACK_MAX_VAL

#define AMBI_DRC_ATTACK_MAX_VAL ( 200.0f )

Maximum attack time, ms.

Definition at line 87 of file ambi_drc.h.

◆ AMBI_DRC_ATTACK_MIN_VAL

#define AMBI_DRC_ATTACK_MIN_VAL ( 10.0f )

Minimum attack time, ms.

Definition at line 86 of file ambi_drc.h.

◆ AMBI_DRC_IN_GAIN_MAX_VAL

#define AMBI_DRC_IN_GAIN_MAX_VAL ( 20.0f )

Maximum input gain, dB.

Definition at line 79 of file ambi_drc.h.

◆ AMBI_DRC_IN_GAIN_MIN_VAL

#define AMBI_DRC_IN_GAIN_MIN_VAL ( -40.0f )

Minimum input gain, dB.

Definition at line 78 of file ambi_drc.h.

◆ AMBI_DRC_KNEE_MAX_VAL

#define AMBI_DRC_KNEE_MAX_VAL ( 10.0f )

Maximum knee, dB.

Definition at line 85 of file ambi_drc.h.

◆ AMBI_DRC_KNEE_MIN_VAL

#define AMBI_DRC_KNEE_MIN_VAL ( 0.0f )

Minimum knee, dB.

Definition at line 84 of file ambi_drc.h.

◆ AMBI_DRC_NUM_BANDS

#define AMBI_DRC_NUM_BANDS ( 133 )

Number of frequency bands used during processing.

Definition at line 73 of file ambi_drc.h.

◆ AMBI_DRC_NUM_DISPLAY_SECONDS

#define AMBI_DRC_NUM_DISPLAY_SECONDS ( 8 )

How many seconds the display will show historic TF data.

Definition at line 67 of file ambi_drc.h.

◆ AMBI_DRC_NUM_DISPLAY_TIME_SLOTS

#define AMBI_DRC_NUM_DISPLAY_TIME_SLOTS ( (int)(AMBI_DRC_NUM_DISPLAY_SECONDS*48000.0f/(float)128) )

Number of time slots of historic TF data.

Definition at line 69 of file ambi_drc.h.

◆ AMBI_DRC_OUT_GAIN_MAX_VAL

#define AMBI_DRC_OUT_GAIN_MAX_VAL ( 40.0f )

Maximum output gain, dB.

Definition at line 91 of file ambi_drc.h.

◆ AMBI_DRC_OUT_GAIN_MIN_VAL

#define AMBI_DRC_OUT_GAIN_MIN_VAL ( -20.0f )

Minimum output gain, dB.

Definition at line 90 of file ambi_drc.h.

◆ AMBI_DRC_RATIO_MAX_VAL

#define AMBI_DRC_RATIO_MAX_VAL ( 30.0f )

Maximum ratio, X:1.

Definition at line 83 of file ambi_drc.h.

◆ AMBI_DRC_RATIO_MIN_VAL

#define AMBI_DRC_RATIO_MIN_VAL ( 1.0f )

Minimum ratio, X:1.

Definition at line 82 of file ambi_drc.h.

◆ AMBI_DRC_READ_OFFSET

#define AMBI_DRC_READ_OFFSET ( 200 )

Number of samples to offset when reading TF data.

Definition at line 71 of file ambi_drc.h.

◆ AMBI_DRC_RELEASE_MAX_VAL

#define AMBI_DRC_RELEASE_MAX_VAL ( 1000.0f )

Maximum release time, ms.

Definition at line 89 of file ambi_drc.h.

◆ AMBI_DRC_RELEASE_MIN_VAL

#define AMBI_DRC_RELEASE_MIN_VAL ( 50.0f )

Minimum release time, ms.

Definition at line 88 of file ambi_drc.h.

◆ AMBI_DRC_SPECTRAL_FLOOR

#define AMBI_DRC_SPECTRAL_FLOOR (0.1585f)

-16dB, maximum gain reduction for a given frequency band

Definition at line 76 of file ambi_drc.h.

◆ AMBI_DRC_THRESHOLD_MAX_VAL

#define AMBI_DRC_THRESHOLD_MAX_VAL ( 0.0f )

Maximum threshold, dB.

Definition at line 81 of file ambi_drc.h.

◆ AMBI_DRC_THRESHOLD_MIN_VAL

#define AMBI_DRC_THRESHOLD_MIN_VAL ( -60.0f )

Minimum threshold, dB.

Definition at line 80 of file ambi_drc.h.

◆ ENABLE_TF_DISPLAY

#define ENABLE_TF_DISPLAY

Enable TF data display related function.

Definition at line 59 of file ambi_drc.h.

Function Documentation

◆ ambi_drc_create()

void ambi_drc_create ( void **const phAmbi )

Creates an instance of the ambi_drc.

Parameters

[in] phAmbi (&) address of ambi_drc handle

Examples: ambi_drc.h.

Definition at line 43 of file ambi_drc.c.

◆ ambi_drc_destroy()

void ambi_drc_destroy ( void **const phAmbi )

Destroys an instance of the ambi_drc.

Parameters

[in] phAmbi (&) address of ambi_drc handle

Examples: ambi_drc.h.

Definition at line 82 of file ambi_drc.c.

◆ ambi_drc_getAttack()

float ambi_drc_getAttack ( void *const hAmbi )

Returns the compressor envelope attack time, in miliseconds.

Examples: ambi_drc.h.

Definition at line 383 of file ambi_drc.c.

◆ ambi_drc_getChOrder()

int ambi_drc_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_drc.h.

Definition at line 395 of file ambi_drc.c.

◆ ambi_drc_getFrameSize()

int ambi_drc_getFrameSize ( void )

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

Examples: ambi_drc.h.

Definition at line 318 of file ambi_drc.c.

◆ ambi_drc_getInGain()

float ambi_drc_getInGain ( void *const hAmbi )

Returns the compressor input gain value, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 371 of file ambi_drc.c.

◆ ambi_drc_getInputPreset()

SH_ORDERS ambi_drc_getInputPreset ( void *const hAmbi )

Returns the current processing order (see SH_ORDERS enum)

Examples: ambi_drc.h.

Definition at line 407 of file ambi_drc.c.

◆ ambi_drc_getKnee()

float ambi_drc_getKnee ( void *const hAmbi )

Returns the compressor knee value 0: hard knee, >0: soft knee, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 365 of file ambi_drc.c.

◆ ambi_drc_getNormType()

int ambi_drc_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_drc.h.

Definition at line 401 of file ambi_drc.c.

◆ ambi_drc_getNSHrequired()

int ambi_drc_getNSHrequired ( void *const hAmbi )

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

Examples: ambi_drc.h.

Definition at line 413 of file ambi_drc.c.

◆ ambi_drc_getOutGain()

float ambi_drc_getOutGain ( void *const hAmbi )

Returns the compressor output gain value, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 377 of file ambi_drc.c.

◆ ambi_drc_getProcessingDelay()

int ambi_drc_getProcessingDelay ( void )

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

Examples: ambi_drc.h.

Definition at line 425 of file ambi_drc.c.

◆ ambi_drc_getRatio()

float ambi_drc_getRatio ( void *const hAmbi )

Returns the compression ratio.

Examples: ambi_drc.h.

Definition at line 359 of file ambi_drc.c.

◆ ambi_drc_getRelease()

float ambi_drc_getRelease ( void *const hAmbi )

Returns the compressor envelope release time, in miliseconds.

Examples: ambi_drc.h.

Definition at line 389 of file ambi_drc.c.

◆ ambi_drc_getSamplerate()

int ambi_drc_getSamplerate ( void *const hAmbi )

Returns the DAW/Host sample rate.

Examples: ambi_drc.h.

Definition at line 419 of file ambi_drc.c.

◆ ambi_drc_getThreshold()

float ambi_drc_getThreshold ( void *const hAmbi )

Returns the compressor threshold value, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 353 of file ambi_drc.c.

◆ ambi_drc_init()

void ambi_drc_init	(	void *const	hAmbi,
		int	samplerate )

Initialises an instance of ambi_drc with default settings.

Parameters

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

Examples: ambi_drc.h.

Definition at line 105 of file ambi_drc.c.

◆ ambi_drc_process()

void ambi_drc_process	(	void *const	hAmbi,
		const float const	inputs,
		float const	outputs,
		int	nCH,
		int	nSamples )

Applies the frequency-dependent dynamic range compression to the input spherical harmonic signals.

Parameters

[in]	hAmbi	ambi_drc handle
[in]	inputs	Input channel buffers; 2-D array: nCH x nSamples
[in]	outputs	Output channel buffers; 2-D array: nCH x nSamples
[in]	nCH	Number of input/output channels
[in]	nSamples	Number of samples in 'inputs'/'output' matrices

Examples: ambi_drc.h.

Definition at line 136 of file ambi_drc.c.

◆ ambi_drc_refreshSettings()

void ambi_drc_refreshSettings ( void *const hAmbi )

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

Examples: ambi_drc.h.

Definition at line 239 of file ambi_drc.c.

◆ ambi_drc_setAttack()

void ambi_drc_setAttack	(	void *const	hAmbi,
		float	newValue )

Sets the compressor envelope attack time, in miliseconds.

Examples: ambi_drc.h.

Definition at line 275 of file ambi_drc.c.

◆ ambi_drc_setChOrder()

void ambi_drc_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_drc.h.

Definition at line 287 of file ambi_drc.c.

◆ ambi_drc_setInGain()

void ambi_drc_setInGain	(	void *const	hAmbi,
		float	newValue )

Sets the compressor input gain value, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 263 of file ambi_drc.c.

◆ ambi_drc_setInputPreset()

void ambi_drc_setInputPreset	(	void *const	hAmbi,
		SH_ORDERS	newPreset )

Sets processing order.

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

Examples: ambi_drc.h.

Definition at line 301 of file ambi_drc.c.

◆ ambi_drc_setKnee()

void ambi_drc_setKnee	(	void *const	hAmbi,
		float	newValue )

Sets the compressor knee value; 0: hard knee, >0: soft knee, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 257 of file ambi_drc.c.

◆ ambi_drc_setNormType()

void ambi_drc_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_drc.h.

Definition at line 294 of file ambi_drc.c.

◆ ambi_drc_setOutGain()

void ambi_drc_setOutGain	(	void *const	hAmbi,
		float	newValue )

Sets the compressor output gain value, in DECIBELS.

Examples: ambi_drc.h.

Definition at line 269 of file ambi_drc.c.

◆ ambi_drc_setRatio()

void ambi_drc_setRatio	(	void *const	hAmbi,
		float	newValue )

Sets the compression ratio.

Examples: ambi_drc.h.

Definition at line 251 of file ambi_drc.c.

◆ ambi_drc_setRelease()

void ambi_drc_setRelease	(	void *const	hAmbi,
		float	newValue )

Sets the compressor envelope release time, in miliseconds.

Examples: ambi_drc.h.

Definition at line 281 of file ambi_drc.c.

◆ ambi_drc_setThreshold()

void ambi_drc_setThreshold	(	void *const	hAmbi,
		float	newValue )

Sets the compressor threshold value in DECIBELS.

Examples: ambi_drc.h.

Definition at line 245 of file ambi_drc.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ AMBI_DRC_ATTACK_MAX_VAL

◆ AMBI_DRC_ATTACK_MIN_VAL

◆ AMBI_DRC_IN_GAIN_MAX_VAL

◆ AMBI_DRC_IN_GAIN_MIN_VAL

◆ AMBI_DRC_KNEE_MAX_VAL

◆ AMBI_DRC_KNEE_MIN_VAL

◆ AMBI_DRC_NUM_BANDS

◆ AMBI_DRC_NUM_DISPLAY_SECONDS

◆ AMBI_DRC_NUM_DISPLAY_TIME_SLOTS

◆ AMBI_DRC_OUT_GAIN_MAX_VAL

◆ AMBI_DRC_OUT_GAIN_MIN_VAL

◆ AMBI_DRC_RATIO_MAX_VAL

◆ AMBI_DRC_RATIO_MIN_VAL

◆ AMBI_DRC_READ_OFFSET

◆ AMBI_DRC_RELEASE_MAX_VAL

◆ AMBI_DRC_RELEASE_MIN_VAL

◆ AMBI_DRC_SPECTRAL_FLOOR

◆ AMBI_DRC_THRESHOLD_MAX_VAL

◆ AMBI_DRC_THRESHOLD_MIN_VAL

◆ ENABLE_TF_DISPLAY

Function Documentation

◆ ambi_drc_create()

◆ ambi_drc_destroy()

◆ ambi_drc_getAttack()

◆ ambi_drc_getChOrder()

◆ ambi_drc_getFrameSize()

◆ ambi_drc_getInGain()

◆ ambi_drc_getInputPreset()

◆ ambi_drc_getKnee()

◆ ambi_drc_getNormType()

◆ ambi_drc_getNSHrequired()

◆ ambi_drc_getOutGain()

◆ ambi_drc_getProcessingDelay()

◆ ambi_drc_getRatio()

◆ ambi_drc_getRelease()

◆ ambi_drc_getSamplerate()

◆ ambi_drc_getThreshold()

◆ ambi_drc_init()

◆ ambi_drc_process()

◆ ambi_drc_refreshSettings()

◆ ambi_drc_setAttack()

◆ ambi_drc_setChOrder()

◆ ambi_drc_setInGain()

◆ ambi_drc_setInputPreset()

◆ ambi_drc_setKnee()

◆ ambi_drc_setNormType()

◆ ambi_drc_setOutGain()

◆ ambi_drc_setRatio()

◆ ambi_drc_setRelease()

◆ ambi_drc_setThreshold()