Source file for the HADES analysis (SAF_HADES_MODULE) More...

#include "saf_hades_analysis.h"
#include "saf_hades_internal.h"

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

Source file 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.c.

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.

Functions

Detailed Description

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()