asFFT Documentation – schmittMachine

asFFT Xtra
v 2.0.8 september 2008
© Antoine Schmitt 1999-2008

———————————————————
——————Conditions of use—————
———————————————————

Shareware. Locked mode only works in Authoring.
asFFT is unlocked using a password.
See attached lixence.txt for details

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

The asFFT Xtra computes a power spectrum using a FFT (Fast Fourier Transform) on the live input sound samples.

You can select the input source from the standard system utilities, or from lingo.
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 access the instant sound volume.
You can retrieve the raw frequencies or have them grouped in an equalizer mode.
You can have the values proportional to the volume (normalized).
The sample rate is always 44100 Hz.
Shockwave-safe and autodownloadable.
Designed to be used with Director.

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

– Macintosh >= MacOS8.6.1 <= MacOSX
– Windows >= 95 (but no NT)
– Director 7.0 to 8.5.1/MX
– Sound Card (internal or external)

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

Drop the Xtra 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 asFFT.x32 file.
On Macintosh, use the asFFT file.

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

May 1999: v1.0
June 1999: v1.1
– Corrected crash bug if asFFTClose was called twice

June 2000: v1.2
– Mac and PC versions
– Shockwave Safe (thus Director 7 only)

July 2001: v1.3
– provided the packages built by Chuck Neal and mediamacros (www.mediamacros.com) (Many thanks to them!).
– added troubleshooting to the ReadMe files
– added packages documentation to the ReadMe files.
– no feature change nor bug fix

April 22 2003 : v2.0
– new API
– equalizer mode
– normalized mode
– instant volume
– source selection
– bug fixes: 16bit sound, micless Mac, firewire input, memory leak

April 26 2003 : v2.0.3
– Fixed bug about changing parameters on multidevice Windows platforms

May 6 2003 : v2.0.7
– Fixed bugs about device/source selection Windows platforms
– added autodownloadable packages (thanks to PegHole www.peghole.com)

June 5 2003 : v2.0.8
– Fixed bug about source selection on some Windows platforms
– Fixed a small memory leak
– added external versioning to the autodownloadable package for compatibility with previous versions.

September 2003 : same version
– ported to MacOSX

———————————————
———————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”])

Some old function names are also indicated. They still function, for backward compatibility, but please use the new function names.
Note that the word accuracy of the old API (asFFT 1.x), is now refered to as timesmooth, and nbBins is now called binCount.

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

new(Xtra “asFFT”)
new(Xtra “asFFT”, str username, str password)
—————————
ex: obj = new(Xtra “asFFT”, “myname”, “mypassword”)
ex: obj = new(Xtra “asFFT”)

Creates the Xtra instance and returns it. Only one instance of the Xtra may exist at any given time.
Creating multiple instances may result in various problems. The Xtra should be released at the end by setting the variable to VOID.

This is where your personal name and password should be entered in order to unlock the Xtra.

Important : always enter the name and password exactely as they where provided to you in the registration email.
Unmatched names and password do not work.

Important : dont circulate your personal name and password. Support independant software developers.
Especially, please dont circulate source code containing your personal name and password…

If the name and password are not provided or if they dont match or if they are “” (the empty string), the Xtra will run in Locked mode:
– it will display an alert when the ‘new’ function is called
– it works in Authoring (inside Director)
– it does not work in Projectors nor in Shockwave: all functions return meaningless values (but they still return gracefully).

asFFTClose(object me)
—————————
ex: asFFTClose(myAsFFTinstance)
Obsolete but kept for compatibility with previous versions (dont use from now on).
Closes the sound input, and frees up all memory used by the instance.
This is done automatically in version 2.0 when the Xtra instance is freed (the variable is set to VOID.)

list getDeviceList(object me)
—————————
ex: devList = obj.getDeviceList()

Returns the list of input sound devices (sound cards) of the computer. It is a list of strings, one per device.
You can use these strings as argument to the “device” argument of the setParams function.

Note : device names strongly depend on the machine’s configuration, esp. the default langage and sound card installed.
Don’t rely on a name to be present (ex : “CD”). Normally, the first device is the default device of the computer.

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

See also : setParams, getFFT

str getError(object me)
—————————
ex: errorString = obj.getError()
old function : asFFTGetError(object me)

Returns a string describing the last error that occured when calling functions of the asFFT Xtra.

list getFFT(object me)
list getFFT(object me, float amplMax,)
list getFFT(object me, float amplMax, int normalized)
list getFFT(object me, float amplMax, int normalized, int equalized)
—————————
ex: fftValuesList = obj.getFFT()
ex: fftValuesList = obj.getFFT(480.0, TRUE, TRUE)
old function: asFFTGetFFTValues(object me) which is equivalent to getFFT(800.0)

This is the main function of the asFFT Xtra. It returns a list of float values which are the spectrum values corresponding to the last 4*timesmooth*binCount sound samples.
The binCount and timesmooth values are set using the setParams method call and are 256 and 1 by default respectively.

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

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

Arguments :

– 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 computes ‘timesmooth’ FFTs over the previous buffer, 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 : setParams, getEqualizedFreqCount, getBinCount, getTimeSmooth

list getSamples(object me)
list getSamples(object me, int nbSamples)
list getSamples(object me, int nbSamples, float amplMax)
—————————
ex: samplesList = obj.getSamples()
ex: samplesList = obj.getSamples(10, 100.)
old function: asFFTGetSoundValues(object me, int nbValues), equivalent to getSamples(nbValues, 128.)

Returns nbSamples sound sample values taken from the previous sound input buffer. Sample values are float that range from -amplMax to amplMax.
Returns 0 if failed. Use getError to get a description of the error.

Arguments:

– nbSamples : int, min = 1, max = 4*timesmooth*binCount, default = timesmooth*binCount.
The number of values to return. It should be smaller than 4*timesmooth*binCount, if it is not, it is automatically truncated by the FFT Xtra.

– amplMax : float, min = 0.0, default = 1.0. The maximum amplitude of the sample values.
The returned values will be bewteen -amplMax and +amplMax included, with 0. meaning no sound

See also : setParams, getEqualizedFreqCount, getBinCount, getTimeSmooth

——————————————————————
————————— Examples ————————
——————————————————————

———————–
–Example 1
— Getting 100 FFTs
———————–
asFFTobj = new(Xtra “asFFT”, “myname, “mypassword”)
if not objectp(asFFTobj) then return

repeat with i = 1 to 100
values = asFFTobj.getFFT()
if values = 0 then
put “FFT error reading values:”&asFFTobj.getError()
else
put values
end if
end repeat

asFFTobj = VOID

———————–
— Example 2
— Getting 100 sound samples
———————–
asFFTobj = new(Xtra “asFFT”, “myname, “mypassword”)
if not objectp(asFFTobj) then return

repeat with i = 1 to 100
values = asFFTobj.getSamples(1)
if values = 0 then
put “FFT error reading values:”&asFFTobj.getError()
else
put values
end if
end repeat

asFFTobj = VOID

——————————————————————
—— Packages : Autodownloadable Version ——
——————————————————————

The asFFT Xtra is autodownloadable from the internet, so that it is usable inside a Shockwave movie available on a web site.
(Many thanks to PegHole for packaging the Xtra. Check their web site for more information: www.peghole.com.)

In order provide the asFFT Xtra for automatic download, follow these instructions:

– locate the packages in the delivery that you have received. There should be one package per platform (currently ppc, carbon and w32).

– put the packages in a single location on a server. eg:
http://www.myserver.com/packs/asFFT.ppc
http://www.myserver.com/packs/asFFT.carb
http://www.myserver.com/packs/asFFT.w32
(Do not put www.as-ci.net here, as the packages are *not* autodownloadable from the as-ci web site. Put them on your web site, alongside your Shockwave movie for example.)

– modify the xtrainfo.txt file in the Director folder to reference this location, eg:
; asFFT Xtra
[#namePPC:”asFFT”, #nameW32:”asFFT.X32″,#package:”http://www.myserver.com/packs/asFFT”]

– restart Director

– add a reference to the package in your movie:
Open a movie that uses asFFT Xtra. From the Modify\Movie\Xtras dialog in Director, select the asFFT Xtra in the list of xtras.
The “Download if needed” checkbox should now be enabled. (If it’s not enabled, make sure the filename in xtrainfo.txt matches the actual filename for the xtra.)
Click on the checkbox and director will load information from the package file for each platform and add it to the current movie.
– publish your shockwave movie, and install it on your server. Each user that plays your Shockwave will automatically dowload the asFFT Xtra from the http address you have specified.

For more information on the Packaging and Autodownload process, check Macromedia’s web site.

———————— Legal ————————
Director is a trademark of Adobe
Macintosh, Windows are trademarks of their respective owners.