#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.

void	noiseFloor (float data[], int dataLength, float threshold)
	Floors data that is below a certain threshold.

void	noiseFloorCFAR (float data[], int dataLength, 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.

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	mapAmplitudes (float *ampData, int dataLength, float minAmpSum=10000, float smoothFactor=0.05)
	Maps amplitudes in some data to between 0.0-1.0 range.

void	mapFrequenciesLinear (float *freqData, int dataLength)
	linearly maps input frequencies from (0 - (1/2)*SAMPLE_RATE) Hz to (0 - 250) Hz, the haptic range.

void	mapFrequenciesExponential (float *freqData, int dataLength, float exp)
	Exponentially maps input frequencies from (0 - (1/2)*SAMPLE_RATE) Hz to (0 - 250) Hz, the haptic range.

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)
	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)
	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, int attackDuration, float decayAmp, int decayDuration, float sustainAmp, int sustainDuration, float releaseAmp, int releaseDuration, float curve)
	Creates an amplitude 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.

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,
		int	attackDuration,
		float	decayAmp,
		int	decayDuration,
		float	sustainAmp,
		int	sustainDuration,
		float	releaseAmp,
		int	releaseDuration,
		float	curve )

Creates an amplitude envelope for a grain.

Creates a frequency 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
attackDuration	The number of windows the attack phase will last for
decayAmp	The amplitude the grain will target in its decay state
decayDuration	The number of windows the decay phase will last for
sustainAmp	The amplitude the grain will target in its sustain state
sustainDuration	The number of windows the sustain phase will last for
releaseAmp	The amplitude the grain will target in its release state
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 )

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, duration lengths, and curve used 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.

◆ mapFrequenciesExponential()

void VibrosonicsAPI::mapFrequenciesExponential	(	float *	freqData,
		int	dataLength,
		float	exp )

Exponentially maps input frequencies from (0 - (1/2)*SAMPLE_RATE) Hz to (0 - 250) Hz, the haptic range.

mapFrequenciesLinear() and mapFrequenciesExponential() map their input frequencies to the haptic range (0-250Hz).

mapFrequencyExponential uses an exponent to apply a curve to the mapping that mapFrequenciesLinear does.

These functions help reduce 'R2-D2' noises caused by outputting high frequencies.

We've found that maintaining certain harmonic relationships between frequencies for output on a single driver can greatly improve tactile feel, so we recommend scaling down by octaves in these scenarios.

Parameters

freqData	The frequency array to map.
dataLength	The length of the frequency array.
exp	The exponential value to apply to the normalized frequencies.

◆ mapFrequenciesLinear()

void VibrosonicsAPI::mapFrequenciesLinear	(	float *	freqData,
		int	dataLength )

linearly maps input frequencies from (0 - (1/2)*SAMPLE_RATE) Hz to (0 - 250) Hz, the haptic range.

mapFrequenciesLinear() and mapFrequenciesExponential() map their input frequencies to the haptic range (0-250Hz).

mapFrequenciesLinear maps the frequencies to the lower range by normalizing them and then scaling by 250 Hz.

These functions help reduce 'R2-D2' noises caused by outputting high frequencies.

We've found that maintaining certain harmonic relationships between frequencies for output on a single driver can greatly improve tactile feel, so we recommend scaling down by octaves in these scenarios.

Parameters

freqData	The frequency array to map.
dataLength	The length of the frequency array.

◆ noiseFloor()

void VibrosonicsAPI::noiseFloor	(	float	data[],
		int	dataLength,
		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

data	The array of data to floor.
threshold	The threshold value to floor the data at.

◆ noiseFloorCFAR()

void VibrosonicsAPI::noiseFloorCFAR	(	float	data[],
		int	dataLength,
		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.

Parameters

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.
freqEnv	The struct containing the new amplitude 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 )

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

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

◆ createDynamicGrain()

◆ createFreqEnv()

◆ createGrainArray()

◆ dcRemoval()

◆ fftWindowing()

◆ getMean() [1/2]

◆ getMean() [2/2]

◆ init()

◆ mapAmplitudes()

◆ mapFrequenciesExponential()

◆ mapFrequenciesLinear()

◆ noiseFloor()

◆ noiseFloorCFAR()

◆ processAudioInput()

◆ setGrainAmpEnv()

◆ setGrainFreqEnv()

◆ triggerGrains()

◆ updateGrains()