Class: FrequencyDomain

Overview

Transforms between time-domain and frequency-domain audio, including buffering, windowing (HanningZ) and window overlap handling (default: 4:1). One instance allocates around 131 kb memory.

Steps to use:

Audio input using addInput().
Call timeDomainToFrequencyDomain(), if it returns false go back to 1.
The output of timeDomainToFrequencyDomain is frequency domain data you can work with.
Call advance() (if required).
Call frequencyDomainToTimeDomain() to create time domain audio from frequency domain data.

Pseudo-example

// Constructor.
let fd = new Superpowered.FrequencyDomain(
    11, // FFT log size, between 8 and 13 (FFT 256 - 8192). The default value (11) provides a good compromise in precision (~22 Hz per bin), CPU load and time-domain event sensitivity.
    4   // [Maximum overlap]:1 (default: 4:1).
);

// Add some audio input. Has no return value.
fd.addInput(
    input, // Pointer to floating point numbers. 32-bit interleaved stereo input.
    512    // The number of input frames.
);

// In the frequency domain we are working with 1024 magnitudes and phases for every channel (left, right), if the fft size is 2048.
// Put this into an iteration, because it may have more frames available than a single loop. Or none!
while (
    // Converts the audio input (added by addInput()) to the frequency domain.
    // Each frequency bin is (samplerate / [FFT SIZE] / 2) wide.
    // Returns true, if a conversion was possible (enough frames were available).
    fd.timeDomainToFrequencyDomain(
    magnitudeL, // Pointer to floating point numbers. Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
    magnitudeR, // Pointer to floating point numbers. Magnitudes for each frequency bin, right side.  Must be at least [FFT SIZE] big.
    phaseL,     // Pointer to floating point numbers. Phases for each frequency bin, left side.  Must be at least [FFT SIZE] big.
    phaseR,     // Pointer to floating point numbers. Phases for each frequency bin, right side.  Must be at least [FFT SIZE] big.
    0,          // Value of Pi. Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
    false,      // If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).
    0           // The index of the stereo pair to process.
    )
) {
    // You can work with frequency domain data inside there, available in magnitudeL, magnitudeR, phaseL and phaseR.

    // After the frequency domain data is modified, maybe you want to go back to the time domain.
    // The method below converts frequency domain data to audio output. Has no return value.
    fd.frequencyDomainToTimeDomain(
        magnitudeL, // Pointer to floating point numbers. Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
        magnitudeR, // Pointer to floating point numbers. Magnitudes for each frequency bin, right side. Must be at least [FFT SIZE] big.
        phaseL,     // Pointer to floating point numbers. Phases for each frequency bin, left side. Must be at least [FFT SIZE] big.
        phaseR,     // Pointer to floating point numbers. Phases for each frequency bin, right side. Must be at least [FFT SIZE] big.
        output,     // Pointer to floating point numbers. 32-bit interleaved stereo output.
        0,          // Value of Pi. Pi can be translated to any value (Google: the tau manifesto). Leave it at 0 for M_PI.
        0,          // For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
        false,      // If true, then the magnitude and phase inputs represent complex numbers (magnitude: real, phase: imag).
        0           // The index of the stereo pair to process.
    );

    // Advances the input buffer (removes the earliest frames). Has no return value.
    fd.advance(
        0 // Number of frames. For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
    );
} // end while

// Returns with how many frames of input should be provided to produce some output.
let frames = fd.getNumberOfInputFramesNeeded();

// Destructor (to free up memory).
fd.destruct();

#include "SuperpoweredFrequencyDomain.h"

// Constructor.
frequencyDomain = new Superpowered::FrequencyDomain(
    11, // FFT log size, between 8 and 13 (FFT 256 - 8192). The default value (11) provides a good compromise in precision (~22 Hz per bin), CPU load and time-domain event sensitivity.
    4   // [Maximum overlap]:1 (default: 4:1).
);

// Add some audio input. Has no return value.
frequencyDomain->addInput(
    input, // Pointer to floating point numbers. 32-bit interleaved stereo input.
    512    // The number of input frames.
);

// In the frequency domain we are working with 1024 magnitudes and phases for every channel (left, right), if the fft size is 2048.
// Put this into an iteration, because it may have more frames available than a single loop. Or none!
while (
    // Converts the audio input (added by addInput()) to the frequency domain.
    // Each frequency bin is (samplerate / [FFT SIZE] / 2) wide.
    // Returns true, if a conversion was possible (enough frames were available).
    frequencyDomain->timeDomainToFrequencyDomain(
        magnitudeL, // Pointer to floating point numbers. Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
        magnitudeR, // Pointer to floating point numbers. Magnitudes for each frequency bin, right side.  Must be at least [FFT SIZE] big.
        phaseL,     // Pointer to floating point numbers. Phases for each frequency bin, left side.  Must be at least [FFT SIZE] big.
        phaseR,     // Pointer to floating point numbers. Phases for each frequency bin, right side.  Must be at least [FFT SIZE] big.
        0,          // Value of Pi. Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
        false,      // If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).
        0           // The index of the stereo pair to process.
    )
) {
    // You can work with frequency domain data inside there, available in magnitudeL, magnitudeR, phaseL and phaseR.

    // After the frequency domain data is modified, maybe you want to go back to the time domain.
    // The method below converts frequency domain data to audio output. Has no return value.
    frequencyDomain->frequencyDomainToTimeDomain(
        magnitudeL, // Pointer to floating point numbers. Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
        magnitudeR, // Pointer to floating point numbers. Magnitudes for each frequency bin, right side. Must be at least [FFT SIZE] big.
        phaseL,     // Pointer to floating point numbers. Phases for each frequency bin, left side. Must be at least [FFT SIZE] big.
        phaseR,     // Pointer to floating point numbers. Phases for each frequency bin, right side. Must be at least [FFT SIZE] big.
        output,     // Pointer to floating point numbers. 32-bit interleaved stereo output.
        0,          // Value of Pi. Pi can be translated to any value (Google: the tau manifesto). Leave it at 0 for M_PI.
        0,          // For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
        false,      // If true, then the magnitude and phase inputs represent complex numbers (magnitude: real, phase: imag).
        0           // The index of the stereo pair to process.
    );

    // Advances the input buffer (removes the earliest frames). Has no return value.
    frequencyDomain->advance(
        0 // Number of frames. For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
    );
} // end while

// Returns with how many frames of input should be provided to produce some output.
unsigned int frames = frequencyDomain->getNumberOfInputFramesNeeded();

Read-only properties

inputList

PROPERTY

For advanced uses: access to the internal audio input pointer list.

Type	Min	Max	Default
Superpowered::AudiopointerList

Methods

constructor

METHOD

Creates an instance of FrequencyDomain class.

Parameters

Name	Type	Description
fftLogSize	`Number`	FFT log size, between 8 and 13 (FFT 256 - 8192). The default value (11) provides a good compromise in precision (~22 Hz per bin), CPU load and time-domain event sensitivity.
maxOverlap	`Number`	[Maximum overlap]:1.

Returns

Type	Description
`Superpowered.FrequencyDomain`	The constructed instance.

constructor

METHOD

Creates an instance of FrequencyDomain class.

Parameters

Name	Type	Default	Description
fftLogSize	`unsigned int`	11	FFT log size, between 8 and 13 (FFT 256 - 8192). The default value (11) provides a good compromise in precision (~22 Hz per bin), CPU load and time-domain event sensitivity.
maxOverlap	`unsigned int`	4	[Maximum overlap]:1.

Returns

Type	Description
`Superpowered::FrequencyDomain`	The constructed instance.

addAudiopointerlistElement
METHOD
Add some audio input (advanced use).
Parameters
Name Type Default Description
input AudiopointerlistElement * The input buffer.
Returns
None
addInput
METHOD
Add some audio input.
Parameters
Name Type Description
input Number (pointer in Linear Memory) 32-bit interleaved stereo input.
numberOfFrames Number The number of input frames.
Returns
None
addInput
METHOD
Add some audio input.
Parameters
Name Type Default Description
input float * 32-bit interleaved stereo input.
numberOfFrames int The number of input frames.
Returns
None
advance
METHOD
Advances the input buffer (removes the earliest frames).
Parameters
Name Type Description
numberOfFrames Number For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
Returns
None
advance
METHOD
Advances the input buffer (removes the earliest frames).
Parameters
Name Type Default Description
numberOfFrames int 0 For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
Returns
None
destruct
METHOD
Destructor to free Linear Memory.
Parameters
None
Returns
None

Name	Type	Default	Description
input	`AudiopointerlistElement *`		The input buffer.

Name	Type	Description
input	`Number (pointer in Linear Memory)`	32-bit interleaved stereo input.
numberOfFrames	`Number`	The number of input frames.

Name	Type	Default	Description
input	`float *`		32-bit interleaved stereo input.
numberOfFrames	`int`		The number of input frames.

Name	Type	Description
numberOfFrames	`Number`	For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).

Name	Type	Default	Description
numberOfFrames	`int`	0	For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).

frequencyDomainToTimeDomain

METHOD

Converts frequency domain data to audio output.

Parameters

Name	Type	Description
magnitudeL	`Number (pointer in Linear Memory)`	Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
magnitudeR	`Number (pointer in Linear Memory)`	Magnitudes for each frequency bin, right side. Must be at least [FFT SIZE] big.
phaseL	`Number (pointer in Linear Memory)`	Phases for each frequency bin, left side. Must be at least [FFT SIZE] big.
phaseR	`Number (pointer in Linear Memory)`	Phases for each frequency bin, right side. Must be at least [FFT SIZE] big.
output	`Number (pointer in Linear Memory)`	32-bit interleaved stereo output.
valueOfPi	`Number`	Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
incrementFrames	`Number`	For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
complexMode	`Boolean`	If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).
stereoPairIndex	`Number`	The index of the stereo pair to process.

Returns

None

frequencyDomainToTimeDomain

METHOD

Converts frequency domain data to audio output.

Parameters

Name	Type	Default	Description
magnitudeL	`float *`		Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
magnitudeR	`float *`		Magnitudes for each frequency bin, right side. Must be at least [FFT SIZE] big.
phaseL	`float *`		Phases for each frequency bin, left side. Must be at least [FFT SIZE] big.
phaseR	`float *`		Phases for each frequency bin, right side. Must be at least [FFT SIZE] big.
output	`float *`		32-bit interleaved stereo output.
valueOfPi	`float`	0	Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
incrementFrames	`int`		For advanced use, if you know how window overlapping works. Use 0 (the default value) otherwise for a 4:1 overlap (good compromise in audio quality).
complexMode	`bool`	false	If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).
stereoPairIndex	`int`	0	The index of the stereo pair to process.

Returns

None

getNumberOfInputFramesNeeded
METHOD
Returns with how many frames of input should be provided to produce some output.
Parameters
None
Returns
Type Description
Number Number of frames.
getNumberOfInputFramesNeeded
METHOD
Returns with how many frames of input should be provided to produce some output.
Parameters
None
Returns
Type Description
unsigned int Number of frames.
reset
METHOD
Reset all internals, sets the instance as good as new.
Parameters
None
Returns
None
reset
METHOD
Reset all internals, sets the instance as good as new.
Parameters
None
Returns
None

Type	Description
`Number`	Number of frames.

Type	Description
`unsigned int`	Number of frames.

setStereoPairs

METHOD

This class can handle one stereo audio channel pair by default (left + right). You can extend it to handle more.

Parameters

Name	Type	Description
numStereoPairs	`Number`	The number of stereo audio channel pairs. Valid values: one (stereo) to four (8 channels).
dontFree	`Boolean`	If true, this function will not free up any memory if numStereoPairs is less than before, so no reallocation happens if numStereoPairs needs to be increased later.

Returns

None

setStereoPairs

METHOD

This class can handle one stereo audio channel pair by default (left + right). You can extend it to handle more.

Parameters

Name	Type	Default	Description
numStereoPairs	`unsigned int`		The number of stereo audio channel pairs. Valid values: one (stereo) to four (8 channels).
dontFree	`bool`	false	If true, this function will not free up any memory if numStereoPairs is less than before, so no reallocation happens if numStereoPairs needs to be increased later.

Returns

None

timeDomainToFrequencyDomain

METHOD

Converts the audio input (added by addInput()) to the frequency domain. Each frequency bin is (samplerate / [FFT SIZE] / 2) wide.

Parameters

Name	Type	Description
magnitudeL	`Number (pointer in Linear Memory)`	Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
magnitudeR	`Number (pointer in Linear Memory)`	Magnitudes for each frequency bin, right side. Must be at least [FFT SIZE] big.
phaseL	`Number (pointer in Linear Memory)`	Phases for each frequency bin, left side. Must be at least [FFT SIZE] big.
phaseR	`Number (pointer in Linear Memory)`	Phases for each frequency bin, right side. Must be at least [FFT SIZE] big.
valueOfPi	`Number`	Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
complexMode	`Boolean`	If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).
stereoPairIndex	`Number`	The index of the stereo pair to process.

Returns

Type	Description
`Boolean`	True, if a conversion was possible (enough frames were available).

timeDomainToFrequencyDomain

METHOD

Converts the audio input (added by addInput()) to the frequency domain. Each frequency bin is (samplerate / [FFT SIZE] / 2) wide.

Parameters

Name	Type	Default	Description
magnitudeL	`float *`		Magnitudes for each frequency bin, left side. Must be at least [FFT SIZE] big.
magnitudeR	`float *`		Magnitudes for each frequency bin, right side. Must be at least [FFT SIZE] big.
phaseL	`float *`		Phases for each frequency bin, left side. Must be at least [FFT SIZE] big.
phaseR	`float *`		Phases for each frequency bin, right side. Must be at least [FFT SIZE] big.
valueOfPi	`float`	0	Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
complexMode	`bool`	false	If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).
stereoPairIndex	`int`	0	The index of the stereo pair to process.

Returns

Type	Description
`bool`	True, if a conversion was possible (enough frames were available).

timeDomainToFrequencyDomainMono

METHOD

Converts mono audio input (added by addInput()) to the frequency domain. Each frequency bin is (samplerate / [FFT SIZE] / 2) wide.

Parameters

Name	Type	Description
magnitude	`Number (pointer in Linear Memory)`	Magnitudes for each frequency bin. Must be at least [FFT SIZE] big.
phase	`Number (pointer in Linear Memory)`	Phases for each frequency bin. Must be at least [FFT SIZE] big.
valueOfPi	`Number`	Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
complexMode	`Boolean`	If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).

Returns

Type	Description
`Boolean`	True, if a conversion was possible (enough frames were available).

timeDomainToFrequencyDomainMono

METHOD

Converts mono audio input (added by addInput()) to the frequency domain. Each frequency bin is (samplerate / [FFT SIZE] / 2) wide.

Parameters

Name	Type	Default	Description
magnitude	`float *`		Magnitudes for each frequency bin. Must be at least [FFT SIZE] big.
phase	`float *`		Phases for each frequency bin. Must be at least [FFT SIZE] big.
valueOfPi	`float`	0	Pi can be translated to any value (Google: the tau manifesto). Keep it at 0 for M_PI.
complexMode	`bool`	false	If true, then it returns with complex numbers (magnitude: real, phase: imag). Performs polar transform otherwise (the output is magnitudes and phases).

Returns

Type	Description
`bool`	True, if a conversion was possible (enough frames were available).

Class: FrequencyDomain

Overview

Pseudo-example

Read-only properties

inputList

Methods

constructor

constructor

addAudiopointerlistElement

addInput

addInput

advance

advance

destruct

frequencyDomainToTimeDomain

frequencyDomainToTimeDomain

getNumberOfInputFramesNeeded

getNumberOfInputFramesNeeded

reset

reset

setStereoPairs

setStereoPairs

timeDomainToFrequencyDomain

timeDomainToFrequencyDomain

timeDomainToFrequencyDomainMono

timeDomainToFrequencyDomainMono