A modified version of afSTFTlib. More...

#include "../../modules/saf_utilities/saf_utilities.h"

Macros
#define	AFSTFT_USE_SAF_UTILITIES
	Remove the "AFSTFT_USE_SAF_UTILITIES" definition, and add the vecTools.h/c and fft4g.h/c to your project, if you want to use the original afSTFT vector code.

Enumerations
enum	AFSTFT_FDDATA_FORMAT { AFSTFT_BANDS_CH_TIME , AFSTFT_TIME_CH_BANDS }
	Options for how the frequency domain data is permuted when using afSTFT. More...

Functions
void	afSTFT_create (void **const phSTFT, int nCHin, int nCHout, int hopsize, int lowDelayMode, int hybridmode, AFSTFT_FDDATA_FORMAT format)
	Creates an instance of afSTFT.

void	afSTFT_destroy (void **const phSTFT)
	Destroys an instance of afSTFT.

void	afSTFT_forward (void const hSTFT, float dataTD, int framesize, float_complex **dataFD)
	Performs forward afSTFT transform.

void	afSTFT_forward_knownDimensions (void const hSTFT, float dataTD, int framesize, int dataFD_nCH, int dataFD_nHops, float_complex **dataFD)
	Performs forward afSTFT transform (dataFD dimensions are known)

void	afSTFT_forward_flat (void const hSTFT, float dataTD, int framesize, float_complex *dataFD)
	Performs forward afSTFT transform (flattened arrays)

void	afSTFT_backward (void const hSTFT, float_complex dataFD, int framesize, float dataTD)
	Performs backward afSTFT transform.

void	afSTFT_backward_knownDimensions (void const hSTFT, float_complex dataFD, int framesize, int dataFD_nCH, int dataFD_nHops, float dataTD)
	Performs backward afSTFT transform (dataFD dimensions are known)

void	afSTFT_backward_flat (void const hSTFT, float_complex dataFD, int framesize, float *dataTD)
	Performs backward afSTFT transform (flattened arrays)

void	afSTFT_channelChange (void *const hSTFT, int new_nCHin, int new_nCHout)
	Re-allocates memory to support a change in the number of input/output channels.

void	afSTFT_clearBuffers (void *const hSTFT)
	Flushes time-domain buffers with zeros.

int	afSTFT_getNBands (void *const hSTFT)
	Returns number of frequency bands.

int	afSTFT_getProcDelay (void *const hSTFT)
	Returns current processing delay, in samples.

void	afSTFT_getCentreFreqs (void const hSTFT, float fs, int nBands, float freqVector)
	Returns current frequency vector.

void	afSTFT_FIRtoFilterbankCoeffs (float hIR, int N_dirs, int nCH, int ir_len, int hopSize, int LDmode, int hybridmode, float_complex hFB)
	Converts FIR filters into Filterbank Coefficients by passing them through the afSTFT filterbank.

Variables
const float	__afSTFT_protoFilter1024 [10240]
	Prototype filter used by afSTFTlib.

const float	__afSTFT_protoFilter1024LD [10240]
	Prototype filter used by afSTFTlib (low-delay mode)

Detailed Description

A modified version of afSTFTlib.

The original afSTFT code (by Juha Vilkamo) can be found here: https://github.com/jvilkamo/afSTFT This version is slightly modified to be more in-line with how the rest of SAF is structured. The files afSTFTlib.h/.c act as the interface to afSTFT, which is then implemented in afSTFT_internal.h/.c.

This version also adds functionality to change the number of channels on the fly, flush the run-time buffers with zeros, return the current frequency vector and the current processing delay. It also incorporates SAF utilities (for the vectorisation and FFT).

The afSTFT design is also described in more detail in [1]

See also: [1] Vilkamo, J., & Ba"ckstro"m, T. (2018). Time–Frequency Processing: Methods and Tools. In Parametric Time–Frequency Domain Spatial Audio. John Wiley & Sons.

Author: Juha Vilkamo

Date: 08.04.2015

License: MIT

Definition in file afSTFTlib.h.

Macro Definition Documentation

◆ AFSTFT_USE_SAF_UTILITIES

#define AFSTFT_USE_SAF_UTILITIES

Remove the "AFSTFT_USE_SAF_UTILITIES" definition, and add the vecTools.h/c and fft4g.h/c to your project, if you want to use the original afSTFT vector code.

Note the vecTools.h/c and fft4g.h/c files, may be found here: https://github.com/jvilkamo/afSTFT

Definition at line 63 of file afSTFTlib.h.

Enumeration Type Documentation

◆ AFSTFT_FDDATA_FORMAT

enum AFSTFT_FDDATA_FORMAT

Options for how the frequency domain data is permuted when using afSTFT.

Enumerator
AFSTFT_BANDS_CH_TIME	nBands x nChannels x nTimeHops
AFSTFT_TIME_CH_BANDS	nTimeHops x nChannels x nBands

Definition at line 79 of file afSTFTlib.h.

Function Documentation

◆ afSTFT_backward()

void afSTFT_backward	(	void *const	hSTFT,
		float_complex ***	dataFD,
		int	framesize,
		float **	dataTD )

Performs backward afSTFT transform.

Parameters

[in]	hSTFT	afSTFT handle
[in]	dataFD	Frequency-domain input; AFSTFT_FDDATA_FORMAT
[in]	framesize	Frame size of time-domain data
[out]	dataTD	Time-domain output; nCHout x framesize

Definition at line 347 of file afSTFTlib.c.

◆ afSTFT_backward_flat()

void afSTFT_backward_flat	(	void *const	hSTFT,
		float_complex *	dataFD,
		int	framesize,
		float *	dataTD )

Performs backward afSTFT transform (flattened arrays)

Parameters

[in]	hSTFT	afSTFT handle
[in]	dataFD	Frequency-domain input; FLAT: AFSTFT_FDDATA_FORMAT
[in]	framesize	Frame size of time-domain data
[out]	dataTD	Time-domain output; FLAT: nCHout x framesize

Definition at line 433 of file afSTFTlib.c.

◆ afSTFT_backward_knownDimensions()

void afSTFT_backward_knownDimensions	(	void *const	hSTFT,
		float_complex ***	dataFD,
		int	framesize,
		int	dataFD_nCH,
		int	dataFD_nHops,
		float **	dataTD )

Performs backward afSTFT transform (dataFD dimensions are known)

Note: If the dimensions of dataFD are known, then this function will use the same dataFD format as used by afSTFT_backward(), but with the speed of afSTFT_backward_flat()

Parameters

[in]	hSTFT	afSTFT handle
[in]	dataFD	Frequency-domain input; AFSTFT_FDDATA_FORMAT
[in]	framesize	Frame size of time-domain data
[in]	dataFD_nCH	Number of channels dataFD is allocated (the max)
[in]	dataFD_nHops	Number of timeslots dataFD is allocated (the max)
[out]	dataTD	Time-domain output; nCHout x framesize

Definition at line 390 of file afSTFTlib.c.

◆ afSTFT_channelChange()

void afSTFT_channelChange	(	void *const	hSTFT,
		int	new_nCHin,
		int	new_nCHout )

Re-allocates memory to support a change in the number of input/output channels.

Parameters

[in]	hSTFT	afSTFT handle
[in]	new_nCHin	New number of input channels
[in]	new_nCHout	New number of output channels

Definition at line 476 of file afSTFTlib.c.

◆ afSTFT_clearBuffers()

void afSTFT_clearBuffers ( void *const hSTFT )

Flushes time-domain buffers with zeros.

Definition at line 518 of file afSTFTlib.c.

◆ afSTFT_create()

void afSTFT_create	(	void **const	phSTFT,
		int	nCHin,
		int	nCHout,
		int	hopsize,
		int	lowDelayMode,
		int	hybridmode,
		AFSTFT_FDDATA_FORMAT	format )

Creates an instance of afSTFT.

Test: test__afSTFT()

Parameters

[in]	phSTFT	(&) address of afSTFT handle
[in]	nCHin	Number of input channels
[in]	nCHout	Number of output channels
[in]	hopsize	Hop size, in samples
[in]	lowDelayMode	0: disabled, 1: low-delay mode enabled
[in]	hybridmode	0: disabled, 1: hybrid-filtering enabled
[in]	format	Frequency-domain frame format, see AFSTFT_FDDATA_FORMAT enum

Definition at line 142 of file afSTFTlib.c.

◆ afSTFT_destroy()

void afSTFT_destroy ( void **const phSTFT )

Destroys an instance of afSTFT.

Parameters

[in] phSTFT (&) address of afSTFT handle

Definition at line 198 of file afSTFTlib.c.

◆ afSTFT_FIRtoFilterbankCoeffs()

void afSTFT_FIRtoFilterbankCoeffs	(	float *	hIR,
		int	N_dirs,
		int	nCH,
		int	ir_len,
		int	hopSize,
		int	LDmode,
		int	hybridmode,
		float_complex *	hFB )

Converts FIR filters into Filterbank Coefficients by passing them through the afSTFT filterbank.

Parameters

[in]	hIR	Time-domain FIR; FLAT: N_dirs x nCH x ir_len
[in]	N_dirs	Number of FIR sets
[in]	nCH	Number of channels per FIR set
[in]	ir_len	Length of the FIR
[in]	hopSize	Hop size
[in]	LDmode	0: disabled, 1:enabled
[in]	hybridmode	0: disabled, 1:enabled
[out]	hFB	The FIRs as Filterbank coefficients; FLAT: N_bands x nCH x N_dirs

Definition at line 592 of file afSTFTlib.c.

◆ afSTFT_forward()

void afSTFT_forward	(	void *const	hSTFT,
		float **	dataTD,
		int	framesize,
		float_complex ***	dataFD )

Performs forward afSTFT transform.

Parameters

[in]	hSTFT	afSTFT handle
[in]	dataTD	Time-domain input; nCHin x framesize
[in]	framesize	Frame size of time-domain data
[out]	dataFD	Frequency-domain output; AFSTFT_FDDATA_FORMAT

Definition at line 229 of file afSTFTlib.c.

◆ afSTFT_forward_flat()

void afSTFT_forward_flat	(	void *const	hSTFT,
		float *	dataTD,
		int	framesize,
		float_complex *	dataFD )

Performs forward afSTFT transform (flattened arrays)

Parameters

[in]	hSTFT	afSTFT handle
[in]	dataTD	Time-domain input; FLAT: nCHin x framesize
[in]	framesize	Frame size of time-domain data
[out]	dataFD	Frequency-domain output; FLAT: AFSTFT_FDDATA_FORMAT

Definition at line 310 of file afSTFTlib.c.

◆ afSTFT_forward_knownDimensions()

void afSTFT_forward_knownDimensions	(	void *const	hSTFT,
		float **	dataTD,
		int	framesize,
		int	dataFD_nCH,
		int	dataFD_nHops,
		float_complex ***	dataFD )

Performs forward afSTFT transform (dataFD dimensions are known)

Note: If the dimensions of dataFD are known, then this function will use the same dataFD format as used by afSTFT_forward(), but with the speed of afSTFT_forward_flat()

Parameters

[in]	hSTFT	afSTFT handle
[in]	dataTD	Time-domain input; nCHin x framesize
[in]	framesize	Frame size of time-domain data
[in]	dataFD_nCH	Number of channels dataFD is allocated (the max)
[in]	dataFD_nHops	Number of timeslots dataFD is allocated (the max)
[out]	dataFD	Frequency-domain output; AFSTFT_FDDATA_FORMAT

Definition at line 267 of file afSTFTlib.c.

◆ afSTFT_getCentreFreqs()

void afSTFT_getCentreFreqs	(	void *const	hSTFT,
		float	fs,
		int	nBands,
		float *	freqVector )

Returns current frequency vector.

Definition at line 545 of file afSTFTlib.c.

◆ afSTFT_getNBands()

int afSTFT_getNBands ( void *const hSTFT )

Returns number of frequency bands.

Definition at line 527 of file afSTFTlib.c.

◆ afSTFT_getProcDelay()

int afSTFT_getProcDelay ( void *const hSTFT )

Returns current processing delay, in samples.

Note

The afSTFT filterbank delay is broken down into the following: analysis delay: 5*hopsize

hybrid-filtering delay: 3*hopsize (or 0, if it is disabled)
synthesis delay 4*hopsize

If the low-delay mode is enabled, it is instead: analysis delay: 2*hopsize

hybrid-filtering delay: 3*hopsize (or 0, if it is disabled)
synthesis delay 2*hopsize

Definition at line 536 of file afSTFTlib.c.

Variable Documentation

◆ __afSTFT_protoFilter1024

const float __afSTFT_protoFilter1024[10240]

extern

Prototype filter used by afSTFTlib.

Definition at line 28 of file afSTFT_protoFilter.h.

◆ __afSTFT_protoFilter1024LD

const float __afSTFT_protoFilter1024LD[10240]

extern

Prototype filter used by afSTFTlib (low-delay mode)

Definition at line 1494 of file afSTFT_protoFilter.h.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ AFSTFT_USE_SAF_UTILITIES

Enumeration Type Documentation

◆ AFSTFT_FDDATA_FORMAT

Function Documentation

◆ afSTFT_backward()

◆ afSTFT_backward_flat()

◆ afSTFT_backward_knownDimensions()

◆ afSTFT_channelChange()

◆ afSTFT_clearBuffers()

◆ afSTFT_create()

◆ afSTFT_destroy()

◆ afSTFT_FIRtoFilterbankCoeffs()

◆ afSTFT_forward()

◆ afSTFT_forward_flat()

◆ afSTFT_forward_knownDimensions()

◆ afSTFT_getCentreFreqs()

◆ afSTFT_getNBands()

◆ afSTFT_getProcDelay()

Variable Documentation

◆ __afSTFT_protoFilter1024

◆ __afSTFT_protoFilter1024LD