#include <VibrosonicsAPI.h>

Public Member Functions
void	init ()

void	processAudioInput (float *output)
	Perform fast fourier transform on the AudioLab input buffer.

void	computeHammingWindow ()
	Pre compute hamming windows for FFT operations.

void	dcRemoval ()
	Perform DC Removal to reduce noise in vReal.

void	fftWindowing ()
	Applies windowing function to vReal data.

void	complexToMagnitude ()
	Computes frequency magnitudes in vReal data.

float	getMean (float *data, int dataLength)
	Returns the mean of some float data.

float	getMean (complex *data, int dataLength)
	Retruns the mean of some complex data.

void	noiseFloor (float *data, float threshold)
	Floors data that is below a certain threshold.

void	noiseFloorCFAR (float *data, int numRefs, int numGuards, float bias)
	Floors data using the CFAR algorithm.

void	assignWave (float freq, float amp, int channel)
	Add a wave to a channel with specified frequency and amplitude.

void	assignWaves (float freqs, float amps, int dataLength, int channel)
	Add waves to a channel from the values in the frequency and amplitude arrays.

void	mapAmplitudes (float *ampData, int dataLength, float minAmpSum=10000, float smoothFactor=0.05)
	Maps amplitudes in some data to between 0.0-1.0 range.

float	mapFrequencyByOctaves (float inFreq, float maxFreq)
	Maps a frequency to the haptic range (0-230Hz) by transposing it down by octaves.

float	mapFrequencyMIDI (float inFreq, float minFreq, float maxFreq)
	Maps a frequency to the haptic range by quantizing it using MIDI values.

void	updateGrains ()
	Updates all grains in the globalGrainList.

Grain *	createGrainArray (int numGrains, uint8_t channel, WaveType waveType)
	Creates and returns a static array of grains on desired chanel with specified wave type.

Grain *	createDynamicGrain (uint8_t channel, WaveType waveType, FreqEnv freqEnv, AmpEnv ampEnv, DurEnv durEnv)
	Creates and returns a single dynamic grain with the specified channel and wave type. Also takes frequency and amplitude envelopes for immediate triggering.

void	triggerGrains (Grain *grains, int numGrains, FreqEnv freqEnv, AmpEnv ampEnv, DurEnv durEnv)
	Updates an array of numPeaks grains sustain and release windows.

FreqEnv	createFreqEnv (float attackFreq, float decayFreq, float sustainFreq, float releaseFreq)
	Creates a frequency envelope for a grain.

AmpEnv	createAmpEnv (float attackAmp, float decayAmp, float sustainAmp, float releaseAmp)
	Creates an amplitude envelope for a grain.

DurEnv	createDurEnv (int attackDuration, int decayDuration, int sustainDuration, int releaseDuration, float curve)
	Creates a duration envelope for a grain.

void	setGrainFreqEnv (Grain *grains, int numGrains, FreqEnv freqEnv)
	Sets the frequency envelope parameters for an array of grains.

void	setGrainAmpEnv (Grain *grains, int numGrains, AmpEnv ampEnv)
	Sets the amplitude envelope parameters for an array of grains.

void	setGrainDurEnv (Grain *grains, int numGrains, DurEnv durEnv)
	Sets the duration envelope paramaters for an array of grains.

Member Function Documentation

◆ assignWave()

void VibrosonicsAPI::assignWave	(	float	freq,
		float	amp,
		int	channel )

Add a wave to a channel with specified frequency and amplitude.

Creates and adds a wave to a channel for output. The wave is synthesized from the provided frequency and amplitude.

Parameters

freq	Frequency of the synthesized wave.
amp	Amplitude of the synthesized wave.
channel	The output channel to add the wave to.

◆ assignWaves()

void VibrosonicsAPI::assignWaves	(	float *	freqData,
		float *	ampData,
		int	dataLength,
		int	channel )

Add waves to a channel from the values in the frequency and amplitude arrays.

Creates and adds multiple waves to a channel for output. The waves are synthesized from the frequencies and amplitudes provided as arguments. Both frequency and amplitude arrays must be equal lengthed, and their length must be passed as dataLength.

Parameters

freqs	Frequencies of the synthesized waves.
amps	Amplitudes of the synthesized waves.
dataLength	The length of the frequency and amplitude arrays.
channel	The output channel to add the waves to.

◆ complexToMagnitude()

void VibrosonicsAPI::complexToMagnitude ( )

Computes frequency magnitudes in vReal data.

Converts raw FFT output to a readable frequency spectrogram.

◆ computeHammingWindow()

void VibrosonicsAPI::computeHammingWindow ( )

Pre compute hamming windows for FFT operations.

◆ createAmpEnv()

AmpEnv VibrosonicsAPI::createAmpEnv	(	float	attackAmp,
		float	decayAmp,
		float	sustainAmp,
		float	releaseAmp )

Creates an amplitude envelope for a grain.

Creates a amplitude envelope struct to shape the grain's amplitude parameters with Also sets state durations and curve shape.

Parameters

attackAmp	The amplitude the grain will target in its attack state
decayAmp	The amplitude the grain will target in its decay state
sustainAmp	The amplitude the grain will target in its sustain state
releaseAmp	The amplitude the grain will target in its release state

◆ createDurEnv()

DurEnv VibrosonicsAPI::createDurEnv	(	int	attackDuration,
		int	decayDuration,
		int	sustainDuration,
		int	releaseDuration,
		float	curve )

Creates a duration envelope for a grain.

Creates a duration envelope struct to shape the grain's amplitude parameters with Also sets state durations and curve shape.

Parameters

attackDuration	The number of windows the attack phase will last for
decayDuration	The number of windows the decay phase will last for
sustainDuration	The number of windows the sustain phase will last for
releaseDuration	The number of windows the release phase will last for
curve	The shape of the grain's progression through targeted amplitudes and frequencies

◆ createDynamicGrain()

Grain * VibrosonicsAPI::createDynamicGrain	(	uint8_t	channel,
		WaveType	waveType,
		FreqEnv	freqEnv,
		AmpEnv	ampEnv,
		DurEnv	durEnv )

Creates and returns a single dynamic grain with the specified channel and wave type. Also takes frequency and amplitude envelopes for immediate triggering.

Creates a grain that runs once and is then deleted.

Parameters

channel	The physical speaker channel, on current hardware valid inputs are 0-2
waveType	The type of wave Audiolab will generate utilizing the grains.
FreqEnv	The frequency data used to shape the grain.
AmpEnv	The amplitude data used to shape the grain.
durEnv	The duration lengths and curve to shape the grain.

◆ createFreqEnv()

FreqEnv VibrosonicsAPI::createFreqEnv	(	float	attackFreq,
		float	decayFreq,
		float	sustainFreq,
		float	releaseFreq )

Creates a frequency envelope for a grain.

Creates a frequency envelope struct to shape the grain's frequency parameters with

Parameters

attackFreq	The frequency the grain will target in its attack state
decayFreq	The frequency the grain will target in its decay state
sustainFreq	The frequency the grain will target in its sustain state
releaseFreq	The frequency the grain will target in its release state

◆ createGrainArray()

Grain * VibrosonicsAPI::createGrainArray	(	int	numGrains,
		uint8_t	channel,
		WaveType	waveType )

Creates and returns a static array of grains on desired chanel with specified wave type.

Creates an array of grains with specified length, channel, and wave type and then pushes the newly created grain array to the global grain list.

Parameters

numGrains	The size of the output Grains array
channel	The physical speaker channel, on current hardware valid inputs are 0-2
waveType	The type of wave Audiolab will generate utilizing the grains.

◆ dcRemoval()

void VibrosonicsAPI::dcRemoval ( )

Perform DC Removal to reduce noise in vReal.

Removes the mean of the data from each bin to reduce noise.

◆ fftWindowing()

void VibrosonicsAPI::fftWindowing ( )

Applies windowing function to vReal data.

Applies a precomputed hamming windowing factor to the data. This is done to reduce spectral leakage between bins.

◆ getMean() [1/2]

float VibrosonicsAPI::getMean	(	complex *	data,
		int	dataLength )

Retruns the mean of some complex data.

Finds and returns the mean value of complex data.

Parameters

data	Array of amplitudes.
dataLength	Length of amplitude array.

◆ getMean() [2/2]

float VibrosonicsAPI::getMean	(	float *	data,
		int	dataLength )

Returns the mean of some float data.

Finds and returns the mean value of float data.

Parameters

data	Array of amplitudes.
dataLength	Length of amplitude array.

◆ init()

void VibrosonicsAPI::init ( )

Initializes all necessary api variables and dependencies.

◆ mapAmplitudes()

void VibrosonicsAPI::mapAmplitudes	(	float *	ampData,
		int	dataLength,
		float	minAmpSum = 10000,
		float	smoothFactor = 0.05 )

Maps amplitudes in some data to between 0.0-1.0 range.

Maps amplitudes to the range [0, 1] by normalizing them by the sum of the amplitudes. This sum is smoothed by the previous data to ensure a consistent amplitude output and contrast.

Parameters

ampData	The amplitude array to map.
dataLength	The length of the amplitude array.
minAmpSum	The minimum value to normalize the amplitudes by (if their sum is not greater than it).
smoothFactor	The factor to smooth the amplitudes by.

◆ mapFrequencyByOctaves()

float VibrosonicsAPI::mapFrequencyByOctaves	(	float	inFreq,
		float	maxFreq )

Maps a frequency to the haptic range (0-230Hz) by transposing it down by octaves.

◆ mapFrequencyMIDI()

float VibrosonicsAPI::mapFrequencyMIDI	(	float	inFreq,
		float	minFreq,
		float	maxFreq )

Maps a frequency to the haptic range by quantizing it using MIDI values.

◆ noiseFloor()

void VibrosonicsAPI::noiseFloor	(	float *	ampData,
		float	threshold )

Floors data that is below a certain threshold.

Sets the amplitude of a bin to 0 if it is less than threshold.

Parameters

windowData	The frequency domain data to filter.
threshold	The threshold value to floor the data at.

◆ noiseFloorCFAR()

void VibrosonicsAPI::noiseFloorCFAR	(	float *	windowData,
		int	numRefs,
		int	numGuards,
		float	bias )

Floors data using the CFAR algorithm.

Uses a sliding window to compute the average value of a number of reference cells for each cell under test (CUT). If the CUT's value is less than the average * a bias, then the cell is floored.

Read more on the CFAR here: https://en.wikipedia.org/wiki/Constant_false_alarm_rate.

Parameters

windowData	The frequency domain data to filter.
numRefs	The number of reference cells for CFAR.
numGuards	The number of guard cells for CFAR.
bias	The bias factor to use for CFAR.

◆ processAudioInput()

void VibrosonicsAPI::processAudioInput ( float * output )

Perform fast fourier transform on the AudioLab input buffer.

Feeds its input array to the Fast4ier fourier transform engine and stores the results in private data members vData and vReal.

Parameters

output Array of signals to store result of FFT operations in.

◆ setGrainAmpEnv()

void VibrosonicsAPI::setGrainAmpEnv	(	Grain *	grains,
		int	numGrains,
		AmpEnv	ampEnv )

Sets the amplitude envelope parameters for an array of grains.

Sets the amplitude envelope for an array of grains

Parameters

grains	An array of grains to have their amplitude envelope set.
numGrains	The size of the Grain array.
ampEnv	The struct containing the new amplitude envelope data

◆ setGrainDurEnv()

void VibrosonicsAPI::setGrainDurEnv	(	Grain *	grains,
		int	numGrains,
		DurEnv	durEnv )

Sets the duration envelope paramaters for an array of grains.

Sets the amplitude envelope for an array of grains

Parameters

grains	An array of grains to have their amplitude envelope set.
numGrains	The size of the Grain array.
durEnv	The struct containing the new duration envelope data

◆ setGrainFreqEnv()

void VibrosonicsAPI::setGrainFreqEnv	(	Grain *	grains,
		int	numGrains,
		FreqEnv	freqEnv )

Sets the frequency envelope parameters for an array of grains.

Sets the frequency envelope for an array of grains

Parameters

grains	An array of grains to have their frequency envelope set.
numGrains	The size of the Grain array.
freqEnv	The struct containing the new frequency envelope data

◆ triggerGrains()

void VibrosonicsAPI::triggerGrains	(	Grain *	grains,
		int	numGrains,
		FreqEnv	freqEnv,
		AmpEnv	ampEnv,
		DurEnv	durEnv )

Updates an array of numPeaks grains sustain and release windows.

Updates an array of grains attack, sustain, and release windows if the data's amplitude is greater than the amplitude stored in the grain.

Parameters

grains	An array of grains to be triggered.
numGrains	The size of the Grain array.
freqEnv	The struct containing the frequency envelope data
ampEnv	The struct containing the amplitude envelope data
durEnv	The duration lengths and curve to shape the grain.

◆ updateGrains()

void VibrosonicsAPI::updateGrains ( )

Updates all grains in the globalGrainList.

Calls update for every grain in the grain list Deletes dynamic grains as needed.

The documentation for this class was generated from the following files:

src/VibrosonicsAPI.h
src/VibrosonicsAPI.cpp

Public Member Functions

Member Function Documentation

◆ assignWave()

◆ assignWaves()

◆ complexToMagnitude()

◆ computeHammingWindow()

◆ createAmpEnv()

◆ createDurEnv()

◆ createDynamicGrain()

◆ createFreqEnv()

◆ createGrainArray()

◆ dcRemoval()

◆ fftWindowing()

◆ getMean() [1/2]

◆ getMean() [2/2]

◆ init()

◆ mapAmplitudes()

◆ mapFrequencyByOctaves()

◆ mapFrequencyMIDI()

◆ noiseFloor()

◆ noiseFloorCFAR()

◆ processAudioInput()

◆ setGrainAmpEnv()

◆ setGrainDurEnv()

◆ setGrainFreqEnv()

◆ triggerGrains()

◆ updateGrains()