asFFTfile Xtra Documentation

asFFTfile Xtra
v 1.2january 2005
© Antoine Schmitt 2005

———————————————————
———————Description———————
———————————————————

The asFFTfile Xtra computes a power spectrum using a FFT (Fast Fourier Transform) on a QuickTime sound file.

Only Quicktime sound files are supported at this time.

You can select the number of bins (frequency bands) and the timesmooth of the computation.
You can also access the sound samples directly.
You can retrieve the raw frequencies or have them grouped in an equalizer mode.
You can have the values proportional to the volume (normalized).
Designed to be used with Director.

———————————————————
————Technical Requirements————
———————————————————

- Macintosh MacOSX
- Windows >= XP
- Director /MX

———————————————————
——————Installation————————
———————————————————

Drop the asFFT into the Xtras folder of Director.
The Xtra can also be in the Xtra folder besides your projector. Check Director's documentation about Xtras.
On Windows, use asFFTfile.x32 file.
On Macintosh, use the asFFTfile file.

———————————————————
——————Version History——————
———————————————————

January 2005: v1.0
January 2005: v1.1 - Windows version
January 2005: v1.2 - added getAmplitude function

———————————————
———————API———————
———————————————

General info

The Xtra is instantiated with the call:

object = new(Xtra "asFFT")

All later calls can be in the form:
func(object, args...)
or the new form
object.func(args...)

The Xtra is released at the end by setting it to VOID:
object = VOID

All functions return 0 (zero) if an error occurred.
If an error occured, the function 'getError' returns a human-readable string describing the error.

Argument types:
int = integer (ex: 16)
str = string (ex: "abcde")
float = float (ex: 1.2)
list = lingo list (ex: ["ab", "cd"])

———————————————
—————Functions——————
———————————————

new(Xtra "asFFTfile")
—————————
ex: obj = new(Xtra "asFFT")

Creates the Xtra instance and returns it. The Xtra should be released at the end by setting the variable to VOID.

int openQuicktimeFile(object me, string absoluteFilePath)
—————————
ex: fileID = obj.openQuicktimeFile(the moviePath&"myQuickTimeMovie.mov")

Opens the given QuickTime file.
If the file contains multiple sound tracks, uses the first one.
If the sound track is stereo, it is considered as mono for the getFFT and getSamples functions.

Returns fileID, an integer that represents the open file. This fileID is ised in the getFFT, getSamples, getSampleRate and closeFile functions. The fileID is an integer > 0.
Returns 0 if failed. Use getError to get a description of the error.

See also : closeFile, getFFT, getSamples, getSampleRate

int closeFile(object me, int fileID)
—————————
ex: obj.closeFile(fileID)

Closes the QuickTime file refered to by fileID (as returned by openQuicktimeFile).
Returns 0 if failed. Use getError to get a description of the error.

See also : getFFT, getSamples, getSampleRate, openQuicktimeFile

list getFFT(object me, integer fileID, int startSample)
list getFFT(object me, integer fileID, int startSample, int binCount)
list getFFT(object me, integer fileID, int startSample, int binCount, int timeSmooth)
list getFFT(object me, integer fileID, int startSample, int binCount, int timeSmooth, float amplMax)
list getFFT(object me, integer fileID, int startSample, int binCount, int timeSmooth, float amplMax, int normalized)
list getFFT(object me, integer fileID, int startSample, int binCount, int timeSmooth, float amplMax, int normalized, int equalized)
—————————
ex: fftValuesList = obj.getFFT(fileID, 5628)
ex: fftValuesList = obj.getFFT(fileID, 5628, 1024, 8, 480.0, TRUE, TRUE)

This is the main function of the asFFTfile Xtra. It returns a list of float values which are the spectrum values corresponding to the 4*timeSmooth*binCount sound samples starting at startSample. Considers the sound track as mono.

The number of returned values depends on whether equalization is requested or not:
if equalized is TRUE, the function returns 1 + log2(binCount) values, otherwise it returns binCount values (see below for details on equalization).
Use the getEqualizedFreqCount function to compute the equalized number of values.

Returns 0 if failed. Use getError to get a description of the error.

Arguments :

- fileID : int. Mandatory. The ID of the file on which to compute the FFT.

- startSample : int, min = 0, no max. Mandatory. The first sample that will be used for the computation. The FFT uses 4*timeSmooth*binCount samples starting at the position startSample in the file.

- binCount : int, min = 2, no max, default = 256. The number of bins requested.
The higher the number of bins, the slower the computation.
This number should be a power of 2. If it is not, it is automatically rounded to the next power of two.
The width of the bin in Hertz (the frequency range of a value) is computed with the equation: Df = 0.5*frameRate/(binCount + 1) Hz.
Example: with binCount = 256, and a sampleRate of 44100, Df = 85.8 Hz.

- timeSmooth : int, min = 1, no max, default = 1. The desired timesmooth.
The FFT is computed over 4*timesmooth*binCount sound samples, and the resulting FFT values are averaged.
The higher the timesmooth, the lower the variance of the results and the higher the accuracy of the computation, but the slower the computation.

- amplMax : float, default = 1.0 : the maximum amplitude of the returned values: all values will be between (roughly) 0.0 and amplMax.
This is useful to have the Xtra compute the multiplication on all values instead of doing it in lingo (slower).

- normalized : integer, 0 (FALSE) or 1 (TRUE), default = 0 : tells whether the values should be normalized to the current volume of the sound
When not normalized, the FFT values may show some power even though the sound volume is low (as FFT computation does not depend on volume).
Setting this value to TRUE ensures that when there is a low volume, the FFT values are also low. Less exact, but more intuitive.

- equalized : integer, 0 (FALSE) or 1 (TRUE), default = 0 : tells whether the function should return equalized values or not.
Equalized values are more intuitive when building an equalizer than raw values.
When asked to equalize the values, the asFFT groups frequencies in increasingly large groups.
The frequencies are grouped according to the following rule : freq0, freq1, freq2 to freq3, freq4 to freq7, freq8 to freq15, etc... So the higher the frequency, the larger the group.
In this mode, the getFFT function returns less values than binCount. It actually returns 1 + log2(binCount) values.
Use the getEqualizedFreqCount function to get the number of equalized values returned.

The way the asFFT Xtra works :
it continuously records incoming sound from the current sound input into two buffers of length 4*timesmooth*binCount.
At all times, one of the buffers is being used for recording, the other one (the previous one) is used for FFT computations.
When the application program requests the FFT values, the Xtra gets 4*timeSmooth*binCount sound samples starting at startSample, computes 'timesmooth' FFTs over these samples, applies a Bartlett Window to the FFT values, averages the 'timesmooth' values for each bin and computes the power of these values.
It then applies a log function and a multiplication factor to these values so that the values are in the range of maxAmpl.

See also : getSampleRate, getEqualizedFreqCount

list getSamples(object me, integer fileID, int startSample, int nbSamples)
list getSamples(object me, integer fileID, int startSample, int nbSamples, float amplMax)
—————————
ex: samplesList = obj.getSamples(3, 100, 1000)
ex: samplesList = obj.getSamples(3, 100, 1000, 100.)

Returns nbSamples sound sample values taken from the file corresponding to fileID, starting at sample startSample (>= 0). Sample values are float that range from -amplMax to amplMax. If startSample + nbSamples is larger than the total number of samples of the file, the additional samples returned will be 0.0 (zero).
Returns 0 if failed. Use getError to get a description of the error.