Header for the HADES analysis (SAF_HADES_MODULE) More...

Macros
#define	HADES_MAX_NMICS ( 64 )
	Maximum number of microphones.

Typedefs
typedef struct _hades_analysis_data *	hades_analysis_handle
	Handle for the hades analysis data.

typedef struct _hades_param_container_data *	hades_param_container_handle
	Handle for the hades parameter container data.

typedef struct _hades_signal_container_data *	hades_signal_container_handle
	Handle for the hades signal container data.

Enumerations
enum	HADES_DIFFUSENESS_ESTIMATORS { HADES_USE_COMEDIE }
	Options for diffuseness estimation for hades_analysis. More...

enum	HADES_DOA_ESTIMATORS { HADES_USE_MUSIC }
	Options for DoA estimation for hades_analysis. More...

enum	HADES_FILTERBANKS { HADES_USE_AFSTFT_LD , HADES_USE_AFSTFT }
	Filterbank options. More...

Functions
void	hades_analysis_create (hades_analysis_handle const phAna, float fs, HADES_FILTERBANKS fbOption, int hopsize, int blocksize, int hybridmode, float h_array, float *grid_dirs_deg, int nGrid, int nMics, int h_len, HADES_DIFFUSENESS_ESTIMATORS diffOption, HADES_DOA_ESTIMATORS doaOption)
	Creates and returns a handle to an instance of a hades analysis object.

void	hades_analysis_destroy (hades_analysis_handle *const phAna)
	Destroys an instance of a hades analysis object.

void	hades_analysis_reset (hades_analysis_handle const hAna)
	Flushes run-time buffers with zeros.

void	hades_analysis_apply (hades_analysis_handle const hAna, float *input, int nChannels, int blocksize, void const hPCon, void *const hSCon)
	Performs hades encoding: forward time-frequency transform, diffuseness and DoA estimation per band.

const float *	hades_analysis_getFrequencyVectorPtr (hades_analysis_handle const hAna, int *nBands)
	Returns a pointer to the frequency vector (read-only)

int	hades_analysis_getNbands (hades_analysis_handle const hAna)
	Returns number of frequency bands (0 if hAna is not initialised)

float *	hades_analysis_getCovarianceAvagingCoeffPtr (hades_analysis_handle const hAna)
	Returns a pointer to the covariance matrix averaging scalar [0..1], which can be changed at run-time.

int	hades_analysis_getProcDelay (hades_analysis_handle const hAna)
	Returns the analyser processing delay, in samples.

void	hades_param_container_create (hades_param_container_handle *const phPCon, hades_analysis_handle const hAna)
	Creates an instance of a container used for storing the parameters estimated by an analyser for one 'blocksize'.

void	hades_param_container_destroy (hades_param_container_handle *const phPCon)
	Destroys an instance of a hades parameter container.

void	hades_signal_container_create (hades_signal_container_handle *const phSCon, hades_analysis_handle const hAna)
	Creates an instance of a container used for storing the TF-domain audio returned by an analyser for one 'blocksize'.

void	hades_signal_container_destroy (hades_signal_container_handle *const phSCon)
	Destroys an instance of a hades signal container.

Detailed Description

Header for the HADES analysis (SAF_HADES_MODULE)

The framework for binaural rendering of Hearing-Assistive/Augmented-reality Devices (HADES) is described further in [1].

See also: [1] Fernandez, J., McCormack, L., Hyvärinen, P., Politis, A., and Pulkki, V. 2022. “Enhancing binaural rendering of head-worn microphone arrays through the use of adaptive spatial covariance matching”, The Journal of the Acoustical Society of America 151, 2624-2635

Author: Leo McCormack and Janani Fernandez

Date: 01.02.2021

License: GNU GPLv2

Definition in file saf_hades_analysis.h.

Macro Definition Documentation

◆ HADES_MAX_NMICS

#define HADES_MAX_NMICS ( 64 )

Maximum number of microphones.

Definition at line 48 of file saf_hades_analysis.h.

Typedef Documentation

◆ hades_analysis_handle

typedef struct _hades_analysis_data* hades_analysis_handle

Handle for the hades analysis data.

Definition at line 51 of file saf_hades_analysis.h.

◆ hades_param_container_handle

typedef struct _hades_param_container_data* hades_param_container_handle

Handle for the hades parameter container data.

Definition at line 54 of file saf_hades_analysis.h.

◆ hades_signal_container_handle

typedef struct _hades_signal_container_data* hades_signal_container_handle

Handle for the hades signal container data.

Definition at line 57 of file saf_hades_analysis.h.

Enumeration Type Documentation

◆ HADES_DIFFUSENESS_ESTIMATORS

enum HADES_DIFFUSENESS_ESTIMATORS

Options for diffuseness estimation for hades_analysis.

See also: [1] Epain, N. and Jin, C.T., 2016. Spherical harmonic signal covariance and sound field diffuseness. IEEE/ACM Transactions on Audio, Speech, and Language Processing, 24(10), pp.1796-1807.

Enumerator
HADES_USE_COMEDIE	As in [1], after spatially whitening the array SCM.

Definition at line 70 of file saf_hades_analysis.h.

◆ HADES_DOA_ESTIMATORS

enum HADES_DOA_ESTIMATORS

Options for DoA estimation for hades_analysis.

Enumerator
HADES_USE_MUSIC	Use MUSIC.

Definition at line 75 of file saf_hades_analysis.h.

◆ HADES_FILTERBANKS

enum HADES_FILTERBANKS

Filterbank options.

Enumerator
HADES_USE_AFSTFT_LD	Alias-free STFT filterbank (low delay)
HADES_USE_AFSTFT	Alias-free STFT filterbank.

Definition at line 80 of file saf_hades_analysis.h.

Function Documentation

◆ hades_analysis_apply()

void hades_analysis_apply	(	hades_analysis_handle const	hAna,
		float **	input,
		int	nChannels,
		int	blocksize,
		void *const	hPCon,
		void *const	hSCon )

Performs hades encoding: forward time-frequency transform, diffuseness and DoA estimation per band.

Note: See hades_param_container_create() and hades_signal_container_create() for creating the parameter and signal containers, respectively. The former contains the estimated spatial parameters (a diffuseness measure, DoA for each source), while the latter contains the input signals in the time-frequency domain, and their spatial covariance matrices per band. These containers can then be passed to hades_synthesis_apply() to reproduce the encoded scene over the target setup.

Parameters

[in]	hAna	hades analysis handle
[in]	input	Input buffer; nChannels x blocksize
[in]	nChannels	Number of channels in input buffer
[in]	blocksize	Number of samples in input buffer
[out]	hPCon	hades parameter container handle
[out]	hSCon	hades signal container handle

Definition at line 244 of file saf_hades_analysis.c.

◆ hades_analysis_create()

void hades_analysis_create	(	hades_analysis_handle *const	phAna,
		float	fs,
		HADES_FILTERBANKS	fbOption,
		int	hopsize,
		int	blocksize,
		int	hybridmode,
		float *	h_array,
		float *	grid_dirs_deg,
		int	nGrid,
		int	nMics,
		int	h_len,
		HADES_DIFFUSENESS_ESTIMATORS	diffOption,
		HADES_DOA_ESTIMATORS	doaOption )

Creates and returns a handle to an instance of a hades analysis object.

Parameters

[in]	phAna	(&) address of hades analysis handle
[in]	fs	Samplerate, Hz
[in]	fbOption	Filterbank to use (see HADES_FILTERBANKS)
[in]	hopsize	Filterbank hopsize
[in]	blocksize	Number of time-domain samples to process at a time
[in]	hybridmode	1: enable filterbank hybrid-filtering, 0: disable
[in]	h_array	Array impulse responses; FLAT: nGrid x nMics x h_len
[in]	grid_dirs_deg	Measurement dirs [azi elev] degrees; FLAT: nGrid x 2
[in]	nGrid	Number of mesurement directions
[in]	nMics	Number of microphones
[in]	h_len	Length of impulse responses, in samples
[in]	diffOption	Diffusness parameter estimator to use (see HADES_DIFFUSENESS_ESTIMATORS)
[in]	doaOption	DoA estimator to use (see HADES_DOA_ESTIMATORS)

Definition at line 47 of file saf_hades_analysis.c.

◆ hades_analysis_destroy()

void hades_analysis_destroy ( hades_analysis_handle *const phAna )

Destroys an instance of a hades analysis object.

Parameters

[in] phAna (&) address of hades analysis handle

Definition at line 184 of file saf_hades_analysis.c.

◆ hades_analysis_getCovarianceAvagingCoeffPtr()

float * hades_analysis_getCovarianceAvagingCoeffPtr ( hades_analysis_handle const hAna )

Returns a pointer to the covariance matrix averaging scalar [0..1], which can be changed at run-time.

Parameters

[in] hAna hades analysis handle

Returns: pointer to the covariance matrix averaging scalar (or NULL if hAna is not initialised); 1 x 1

Definition at line 356 of file saf_hades_analysis.c.

◆ hades_analysis_getFrequencyVectorPtr()

const float * hades_analysis_getFrequencyVectorPtr	(	hades_analysis_handle const	hAna,
		int *	nBands )

Returns a pointer to the frequency vector (read-only)

Parameters

[in]	hAna	hades analysis handle
[out]	nBands	(&) Number of bands (set to NULL if not needed)

Returns: pointer to freqVector (or NULL if hAna is not initialised); nBands x 1

Definition at line 330 of file saf_hades_analysis.c.

◆ hades_analysis_getNbands()

int hades_analysis_getNbands ( hades_analysis_handle const hAna )

Returns number of frequency bands (0 if hAna is not initialised)

Definition at line 348 of file saf_hades_analysis.c.

◆ hades_analysis_getProcDelay()

int hades_analysis_getProcDelay ( hades_analysis_handle const hAna )

Returns the analyser processing delay, in samples.

Note: The total delay for an analyser -> synthesiser configuration is computed as: hades_analysis_getProcDelay() + hades_synthesis_getProcDelay().

Definition at line 368 of file saf_hades_analysis.c.

◆ hades_analysis_reset()

void hades_analysis_reset ( hades_analysis_handle const hAna )

Flushes run-time buffers with zeros.

Call this ONCE before calling hades_analysis_apply()

Parameters

[in] hAna hades analysis handle

Definition at line 229 of file saf_hades_analysis.c.

◆ hades_param_container_create()

void hades_param_container_create	(	hades_param_container_handle *const	phPCon,
		hades_analysis_handle const	hAna )

Creates an instance of a container used for storing the parameters estimated by an analyser for one 'blocksize'.

Note: There should be one container per analyser, but this container can be passed to multiple different synthesisers. You may also create multiple containers, fill them using an analyser, store them, and pass them to the synthesiser(s) later.

Parameters

[in]	phPCon	(&) address of hades parameter container handle
[in]	hAna	hades analysis handle

Definition at line 381 of file saf_hades_analysis.c.

◆ hades_param_container_destroy()

void hades_param_container_destroy ( hades_param_container_handle *const phPCon )

Destroys an instance of a hades parameter container.

Parameters

[in] phPCon (&) address of hades parameter container handle

Definition at line 404 of file saf_hades_analysis.c.

◆ hades_signal_container_create()

void hades_signal_container_create	(	hades_signal_container_handle *const	phSCon,
		hades_analysis_handle const	hAna )

Creates an instance of a container used for storing the TF-domain audio returned by an analyser for one 'blocksize'.

Note: There should be one container per analyser, but this container can be passed to multiple different synthesisers. You may also create multiple containers, fill them using an analyser, store them, and pass them to the synthesiser(s) later.

Parameters

[in]	phSCon	(&) address of hades signal container handle
[in]	hAna	hades analysis handle

Definition at line 425 of file saf_hades_analysis.c.

◆ hades_signal_container_destroy()

void hades_signal_container_destroy ( hades_signal_container_handle *const phSCon )

Destroys an instance of a hades signal container.

Parameters

[in] phSCon (&) address of hades signal container handle

Definition at line 447 of file saf_hades_analysis.c.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ HADES_MAX_NMICS

Typedef Documentation

◆ hades_analysis_handle

◆ hades_param_container_handle

◆ hades_signal_container_handle

Enumeration Type Documentation

◆ HADES_DIFFUSENESS_ESTIMATORS

◆ HADES_DOA_ESTIMATORS

◆ HADES_FILTERBANKS

Function Documentation

◆ hades_analysis_apply()

◆ hades_analysis_create()

◆ hades_analysis_destroy()

◆ hades_analysis_getCovarianceAvagingCoeffPtr()

◆ hades_analysis_getFrequencyVectorPtr()

◆ hades_analysis_getNbands()

◆ hades_analysis_getProcDelay()

◆ hades_analysis_reset()

◆ hades_param_container_create()

◆ hades_param_container_destroy()

◆ hades_signal_container_create()

◆ hades_signal_container_destroy()