fluidsynth/doc/xtrafluid.txt

Xtra iiwu
Version 2.7
October 2002


--- Introduction
The iiwu Xtra integrates the iiwusynth synthesizer into Director.

The iiwusynth software synthesizer has been designed by Peter Hanappe,
and is available under the LGPL licence.  It emulates in software the
SoundFont 2.01 Specifications (http://www.soundfont.com) designed by
Creative Labs (SoundBlaster maker).  It is basically a small, fast and
robust wavetable synthesizer, with a MIDI-like interface and
integrated sequencer.  For more information on the iiwu synthesizer :
http://www.iiwu.org/iiwusynth

The iiwu Xtra has been developped as part of the "infiniteCD Author"
project managed by Antoine Schmitt and Hyptique, with support from the
PRIAM funds from the French government.

For more information on the infiniteCD Author project :
http://www.infiniteCD.org/
http://www.hyptique.com/
http://www.gratin.org/as/


--- Licencing

The Version 2.7 of the iiwu Xtra is beta. Do not distribute without
permission.  Eventually, the Xtra will be part of the iiwu project,
and thus will conform to the LGPL licence.


--- Release notes
Version 2.0.1 : first beta version - October 2002
Version 2.0.1 : first beta version - October 2002
Version 2.5 : second beta - November 2002
Version 2.6 : third beta - November 2002
Version 2.7 : fourth beta - November 2002


--- Technical Requirements
OS:
- Macintosh >= MacOS8.6.1 < MacOSX
- Windows >= 95
Director 8.5.1
Sound Card


--- Installation
Drop the folder "iiwuXtraFolder" into the Xtras folder of Director.


-----------------
--- Documentation
-----------------

- Calls

All function calls are done using lingo's call syntax:

object.func(args...)
or
func(object, args...)

Where object is the instance of the Xtra created with the 'new'
method.  All functions return either a value, which can be 0 (zero),
meaning that the function executed without errors, either a negative
number, meaning that an error occurred. If an error occured, the
function 'getError' returns a human-readable string describing the
error.

- Instances

Many instances of the Xtra may coexist at the same time.
Instances are created with the 'new' function, and deleted by assigning
the lingo variable to VOID, as usual for Xtra instances.

- SoundFont file, stack, presets

A SoundFont bank is typically stored in a file, called a SoundFont
file, of extension .sf2. In the following documentation, we will refer
to the SoundFont file or SoundFont bank by the term
'SoundFont'. Please note that the term 'bank' will always refer to a
MIDI bank, not a SoundFont bank.

A SoundFont has a name and contains 'presets'. A preset represents a
way to play a sound, as a combination of sample data and parameters on
how to play it. The preset is the fundamental sound object of the
SoundFont format.

A preset has a name, and is defined uniquely by a MIDI bank number and
a preset number in the bank. The MIDI bank number ranges from 0 to
16383 and the preset number from 0 to 127. Thus a SoundFont file may
contain up to 128x16384=2097152 presets.

SoundFont files may be loaded in the synthesizer, using the
'loadSoundFont' function, thus making its presets available for
playing. A SoundFont may be unloaded using the 'unloadSoundFont'
function.

If more than one SoundFont file is loaded, the SoundFonts are stacked
in the synthesizer : when a preset is requested by the 'programChange'
function, it is looked up in all succcessive SoundFonts, from first to
last, until the preset with the right preset number and bank number is
found. The SoundFont stack may be examined but not changed : the
SoundFonts are stacked in inverse loading order: the last loaded
SoundFont is the first searched.

A special SoundFont is maintained by the synthesizer, corresponding to
user-defined presets, built from user-provided samples. These presets
are defined using the 'loadSample' and 'loadSoundMember'
functions. This user SoundFont is inserted in the SoundFont stack at
the first call of one of these functions. All subsequent calls to one
of these functions will insert the created preset in the same user
SoundFont.

- Channels

According to the MIDI format and protocol, the synthesizer has a fixed
number of channels. This is the maximum number of presets that may be
playing at the same time. At all times, one given channel plays at
most one preset (but can play many notes from this preset). A preset
is associated to a channel using the 'programChange' function. The
number of channels of the synthesizer is defined at init time using
the 'new' function. A given preset may be associated to many
channels.


-----------------
-- Initialization
-----------------

new(Xtra"iiwusynth")
new(Xtra"iiwusynth", plist initParams)
-----------------

ex : iiwuObj = new(Xtra "iiwusynth", [#channels: 32])

Creates a new instance of the iiwu Xtra.
The optional initParams argument is a propert-list
of key-value paris defining initialization parameters.

Only one key is currently defined: 

- #channels : int > 0 : the number of channels allocated by the
synthesizer. If omitted, the default number of channels is set to 64.
Version 2.0.1 : This is not implemented yet : the number of channels is always 64.

To destroy the synthesizer, simply set its variable to VOID.

Returns an error code (unable to create, hardware error, bad arguments).


getChannelsCount(object me)
-----------------

ex : nbchan = getChannelsCount(iiwuObj)

Returns the number of channels of the synthesizer. By default, there are 64 channels.

Returns an error code (no synth).


getMasterGain(object me)
-----------------

ex : gain = getMasterGain(iiwuObj)

Returns the master gain of the synthesizer. By default the gain is 1.0 (full volume).
The gain is between 0.0 and 2.0.
Returns an error code (no synth).


setMasterGain(object me, float gain)
-----------------

ex : setMasterGain(iiwuObj, 0.5)

Sets the master gain of the synthesizer. By default the gain is 1.0.
The gain should between 0.0 and 2.0. 
Gains superior to 1.0 (full volume, no attenuation) should be handled
carefully, as distortion may happen.
Returns an error code (no synth).


-----------------
-- Reverb/Chorus
-----------------

setReverb(object me)
setReverb(object me, int onOrOff)
-----------------

ex : setReverb(iiwuObj)
ex : setReverb(iiwuObj, FALSE)

Sets the reverb module of the synthesizer on or off.

Returns an error code (no synth, bad arguments).


getReverb(object me)
-----------------

ex : revOn = getReverb(iiwuObj)

Return 1 of the reverb module is on (default), 0 if it is off.

Returns an error code (no synth, bad arguments).


setReverbProp(object me, symbol prop, float value)
-----------------

ex : setReverbProp(iiwuObj, #roomsize, 0.9)
ex : setReverbProp(iiwuObj, #level, 0.2)

Sets the value of a property of the reverb module.
Accepted properties are:
- #level : the level of the reverb (0.0 = no reverb, 1.0 = full reverb).
- #roomsize : the size of the room. 0.0 means a very small room, 1.0 means outerspace.
- #width : the spatial width of the reverb. 0.0 means a very narrow reverb, 1.0 a wide one.
- #damping : how much power is lost at each reverberation. 1.0 : mostly lost, 0.0 : full reverberation.

All values are between 0.0 and 1.0.

Returns an error code (no synth, bad arguments).


getReverbProp(object me, symbol prop)
-----------------

ex : roomsiz = getReverbProp(iiwuObj, #roomsize)
ex : damping = getReverbProp(iiwuObj, #damping)

Returns the float value of the given property of the reverb module. Accepted properties are listed above.
Returns an error code (no synth, bad arguments).


setChorus(object me)
setChorus(object me, int onOrOff)
-----------------

ex : setChorus(iiwuObj)
ex : setChorus(iiwuObj, FALSE)

Sets the chorus module of the synthesizer on or off.

Returns an error code (no synth, bad arguments).


getChorus(object me)
-----------------

ex : chorusOn = getChorus(iiwuObj)

Return 1 of the chorus module is on (default), 0 if it is off.

Returns an error code (no synth, bad arguments).


setChorusProp(object me, symbol prop, float value)
-----------------

ex : setChorusProp(iiwuObj, #number, 3)
ex : setChorusProp(iiwuObj, #level, 0.2)

Sets the value of a property of the chorus module.
Accepted properties are:
- #level : the level of the chorus. Min is 0.0, maximum accepted is 10.0.
- #number : the number of secondary voices. Maximum is 99.
- #modulation : the amplitude of the frequency modulation, in Hz. Min is 0.29, max is 5.0.
- #delay : the maximum delay between secondary voices, in ms. Min is 0, maximum is 100.0.

Returns an error code (no synth, bad arguments).


getChorusProp(object me, symbol prop)
-----------------

ex : number = getChorusProp(iiwuObj, #number)
ex : modulation = getChorusProp(iiwuObj, #modulation)

Returns the float value of the given property of the chorus module. Accepted properties are listed above.
Returns an error code (no synth, bad arguments).

-----------------
-- Sound Data
-----------------

loadSoundFont(object me, string filePath)
-----------------

ex : soundFontID = loadSoundFont(iiwuObj, the moviePath & "MySoundFonts.sf2")

Loads a SoundFonts file in the synthesizer and places it at the top of
the SoundFont stack : it will be the first searched when looking for a
preset.

The path is absolute, and should be expressed with the local file
system conventions.

The loaded soundFont will be of type #file.

Returns an ID, an interger uniquely idenfiying the SoundFont in the stack, or an error
code (no synth, no file, bad file format, not enough
memory).


createSoundFont(object me)
createSoundFont(object me, string name)
-----------------

ex : soundFontID = createSoundFont(iiwuObj)
ex : soundFontID = createSoundFont(iiwuObj, "mysoundfont in memory")

Creates an empty SoundFont in memory (type #ram) and places it at the top of
the SoundFont stack : it will be the first searched when looking for a
preset.

The returned soundFontID can be used in the #soundFont property of the loadSampleFile or
loadSampleMember functions.

The created soundFont can be removed from memory, using the unloadSoundFont function.

The 'name' argument is optional and defaults to EMPTY (the empty string).

Returns an ID, an interger uniquely idenfiying the SoundFont in the stack, or an error
code (no synth, no file, bad file format, not enough
memory).


unloadSoundFont(object me)
unloadSoundFont(object me, int soundFontID)
-----------------

ex : unloadSoundFont(iiwuObj, 1)
ex : unloadSoundFont(iiwuObj)

Unloads the SoundFont of the given ID of the SoundFont stack.
The soundFontID argument is optional, and defaults to the first searched
SoundFont (the last loaded).

All types of soundFonts can be unloaded from memory.

Returns an error code (no synth, bad ID).


reloadSoundFont(object me)
reloadSoundFont(object me, int soundFontID)
-----------------

ex : reloadSoundFont(iiwuObj, 1)
ex : reloadSoundFont(iiwuObj)

Version 2.0.1 : Not Yet Implemented.

Reloads the SoundFont of the given ID of the SoundFont stack.
The soundFontID argument is optional, and defaults to the first searched
SoundFont (the last loaded).
This is useful when a soundFont is known to have changed outside
the synthesizer.
Only SoundFonts of type #file can be reloaded.

Returns an error code (no synth, bad ID).


getSoundFontsStack(object me)
-----------------

ex : aList = getSoundFontsStack(iiwuObj)

Returns a lingo list containing all the IDs of the SoundFonts in the stack, sorted from first searched to last searched (last loded to first loaded).
May return an error code (no synth).


getSoundFontInfo(object me)
getSoundFontInfo(object me, int soundFontID)
-----------------

ex : nam = getSoundFontInfo(iiwuObj)

Returns information about the SoundFont of the given soundFontID of the SoundFont stack.
The soundFontID argument is optional, and defaults to the first searched
SoundFont (the last loaded).

The information is returned in the form of a lingo property-list,
containing key-value pairs describing the SoundFont: its name, and
info about its presets (name, preset number and bank number):

[
    #name:"SoundFontName",
   	#type:#file or #ram,
    #presets:
    [
        [#name:"preset1Name", #bank:preset1bankNb, #number:preset1Number],
        [#name:"preset2Name", #bank:preset2bankNb, #number:preset2Number],
        ...
    ]
]
(More information may be added in future versions of the Xtra)

Can return an error code (no synth, bad soundFontID).


loadSampleFile(object me, string filePath, plist presetInfo)
loadSampleFile(object me, string filePath, int number)
-----------------

Version 2.0.1 : Not Yet Implemented.

ex : loadSampleFile(iiwuObj, the moviePath&"MidPiano.aiff",
[#name:"piano", #bank:0, #number:1, #rootKey:60, #keyrange:[50, 70]])

ex : loadSampleFile(iiwuObj, the moviePath&"Piano.aiff", [#number:2])
ex : loadSampleFile(iiwuObj, the moviePath&"Piano.aiff", 2)

Loads a sample file from filePath and creates a preset from it. This
is a simple way of creating a preset from a specific sample.

The 'filePath' is absolute, and should be expressed with the local
file system conventions. Accepted sample formats are : wav, and aiff.

The preset is added to a ram (memory) SoundFont (type #ram).
This SoundFont is either specified using the #soundFont property (see below),
either the highest soundfont in the stack is used if it is a ram soundfont,
either it is created on the fly in memory, in which case it is placed at the top
of the SoundFont stack of the synthesizer.

The preset is created according to the 'presetInfo'
lingo property-list. This plist is a combination of key-value pairs
describing the preset. The following keys are taken into account:

- #number : integer, mandatory. Between 0 and 127 : the preset number in the bank
  If this preset number (and bank if set) was already in use, the sample is added
  to the already preset samples of this preset. This is a handy way to define
  a keyRange for a preset.

- #bank : integer, optional (default = 0). Between 0 and 16383: the number
  of the MIDI bank that will be assigned to the preset.

- #soundFont : integer, optional. Specifies the soundFontID of the SoundFont
   in which the preset will be created. If specified, it should be a
   soundFont of type #ram. If not specified, the first soundfont on the stack
   will be used if it is of type #ram. If not, a new SoundFont 
   is created on the fly. 

- #name : string : the name of the preset - optional

- #rootKey : int between 0 and 127 : the key at which the sample will
   be played 'as is' - optional : if omitted, 60 (middle-C) is used.

- #keyRangeStart : integer, optional (default = 0).
   Defines the first of two keys between which the sample should be
   played (the comparison is inclusive).
   If a noteon asks for a key outside this range, the sample is not
   played. If omitted, the whole range [0, 127] is used.

- #keyRangeEnd : integer, optional (default = 127). See keyRangeStart.

- #loop : boolean, optional. Specifies that the sample should be played
as a loop. Default is FALSE.

- #attack : float, optional (default = 0.0). Duration, in milliseconds of
the attack phase of the sound, i.e. the time for the sample to reach peak volume
after a noteon is issued.

- #decay : float, optional (default = 0.0). Duration, in milliseconds of
the decay phase of the sound, i.e. the time for the sample to reach sustain volume
after the attack.

- #sustainlevel : float, optional (default = 0.0). Level, in dB relative to the
peak level, of the sustain level. A sustainlevel of 0 means the same level than
the peak level. A sustainlevel of 10 mean peak-10dB, which is very low.
A sustainlevel of 100dB conventionnaly means full attenuation.

- #release : float, optional (default = 0.0). Duration, in milliseconds of
the release phase of the sound, i.e. the time for the sample to reach silence
after a noteoff.

Note that in one preset, two different samples may be used for two
different key ranges.

example :

loadSampleFile(iiwuObj, the moviePath&"PianoLo.aiff", [#name:"piano",
#bank:0, #number:1, #rootKey:30, #keyrange:[0, 60]])

loadSampleFile(iiwuObj, the moviePath&"PianoHi.aiff", [#name:"piano",
#bank:0, #number:1, #rootKey:90, #keyrange:[61, 127]])

This example defines two samples for two ranges of the same preset.

A preset may not be unloaded ; only the whole user SoundFont may be
unloaded from the SoundFont stack, using the 'unloadSoundFont'
function.

Returns the soundFontID of the SoundFont to which the sample has been added,
or an error code (no synth, no file, bad file format, not enough
memory, bad bank number, bad preset number, bad key).


loadSampleMember(object me, obj member, plist presetInfo)
-----------------
ex : loadSampleMember(iiwuObj, member(3), [#name:"piano", #bank:0, #number:1])

Version 2.0.1 : Not Yet Implemented.

Loads a sample from the given Director sound cast member and creates a
preset from it.

The preset is created according to the 'presetInfo' lingo
property-list. (see above for details on the presetInfo format).

Returns the soundFontID of the SoundFont to which the sample has been added,
or an error code (no synth, no member, bad member format, not enough memory,
bad bank number, bad preset number, bad key, not a user soundFont).



-----------------
-- Event sequencer
-----------------

Introduction
-----------------

- Sequencer

The API functions for playing music is derived from the MIDI
protocol. This protocol defines the use of a number of presets for
every synthesizer object. Application communicate with a preset in a
synthesizer over a channel. The communication is event based (MIDI
events). The API of the music functions (discussed below) can be
thought of as sending an event over a channel to a preset. 

The music API functions includes the optional use of a sequencer. A
sequencer is an object that assures the delivery of an event at a
future time. To use the sequencer object, the events have to specify a
time property. Two property key values can be used:

- #date: specifies the time on an absolute time axis (the creation
   time of the synthesizer is used as time zero),

- #delay: specifies the time relative to the sequencer's current time.

The time is measured in 'ticks'. A 'tick' is an arbitrary unit that
can be set by the application. See the sequencer API below.

- Event destinations

The API includes the use of several synthesizer objects. The property
key '#dest' indicates the destination of the event. The destination
value is the name of the synthesizer object. If no destination is
specified, the event will be sent to the first known destination which
is the default synthesizer.

- Event sources

Events can also specify an event source. This is useful when the
sender of an event wants to cancel some time the event later. To use
this feature, the event simply contains the key '#source' with a string
as value.

- Callbacks

Lingo objects can ask the sequencer to schedule a callback function at
a precise time. The callback is the name of a Lingo handler. The movie
will have to call the poll function of the xtra regularly to receive
the callbacks.


- Sequencer API

The following functions address the sequencer directly.

setTimeUnit(object me, float ticksPerSecond)
-----------------
ex. setTimeUnit(iiwuObj, 10.0) -- 1 tick equals 100 millisecond

Sets the tick unit of the sequencer.
ticksPerSecond is a float > 0.

Returns a error indication (bad initialization).


getTimeUnit(object me)
-----------------
ex. getTimeUnit(iiwuObj)

Returns the tick unit of the sequencer or an error indication (bad
initialization).
By default, the tick value is 1000.0 (1 tick = 1 millisecond).


getTime(object me)
-----------------
ex. getTime(iiwuObj)

Returns the time in tick from the start of the synthesizer, in tick units
of the sequencer or an error indication (bad initialization).


getDestinations(object me)
-----------------
ex. getDestinations(iiwuObj)

Returns a list with all the names of possible event destinations.


removeEvents(object me, plist filter)
-----------------
ex. removeEvents(iiwuObj, [#dest: "iiwusynth", #source: "DrumMachine"])
ex. removeEvents(iiwuObj, [#source: "DrumMachine", #type: #note])

Removes events that are queued for sending in the sequencer. The
function takes property list as argument. The property list defines
the events that should be filtered. Currently, any of the three
following keys can be used:

- #source: remove the events for the specified source (if not specified,
removes all source)
- #dest: remove the events sent by the specified destination (if not
specified, removes all destination)
- #type: remove the events according to this event type (if not
specified, removes all events)

Possible event types are:

- #note
- #noteon
- #noteoff
- #allsoundsoff
- #allnotesoff
- #programchange
- #controlchange: includes all controlChange events (pitchbend, modulation,
  sustain, pan, volume, reverbsend, chorussend)
- #pitchbend
- #modulation
- #sustain
- #pan
- #volume
- #reverbsend
- #chorussend
- #callback

Returns an error code (no sequencer, invalid argument).



scheduleCallback(object me, plist callbackInfo)
-----------------
ex. scheduleCallback(iiwuObj, [#delay: 1200, #handler:"updateDrumMachine", #args: [1,2,3]])
ex. scheduleCallback(iiwuObj, [#delay: 1200, #source:"drumMachine", #handler:"updateDrumMachine"])

Schedules a callback event. When the event is reached, the lingo handler defined in
the 'callbackInfo' propertylist is called back. Note that the callback happens during
idle time.

The 'callbackInfo' propertylist has the following possible properties:

- #handler, string, mandatory. It is the lingo handler that will be called.
- #args, a lingo list, optional. This list contains the arguments of the handler.
The scheduleCallback function retains a pointer to this list but does not copy it,
according to the lingo tradition. The lingo eventually executed is equivalent
to "handler(args[1], args[2], ...)". If the first argument is a child object,
the corresponding handler will be called on that object.
- #delay/#date : integer, optional. Specifies the time of the callback. Defaults to #delay:0
- #source : optional. Specifies the source. Useful for removing callbacks.
- #dest : optional. Specifies the destination.

To remove a scheduled callback, use removeEvents:
ex : removeEvents(iiwuObj, [#source: "drumMachine", #type: #callback])
ex : removeEvents(iiwuObj, [#type: #callback])

Returns an error code (no sequencer, invalid argument).





-----------------
-- Playing music
-----------------

Most event functions accept an optional property list that describes
the sequencing of the event. This is indicated by the 'seq' argument
in the functions below. The following properties are recognized:

- #date: the absolute time of the event
- #delay: the time of the event relative to current time
- #source: the event source
- #dest: the event destination

#date and #delay should not be specified together.


programChange(object me, int channel, plist presetInfo, plist seq)
programChange(object me, int channel, int presetNumber, plist seq)
-----------------

ex : programChange(iiwuObj, 1, [#bank:1, #number:3])
ex : programChange(iiwuObj, 1, 3)

Assigns the given preset of the SoundFont stack to the given channel
of the synthethizer.

The preset may be defined using a property-list defining its MIDI bank
number and its preset number, using specific keys:

- #bank : int between 0 and 16383: the number of the MIDI bank of the
   preset - optional : if #bank is not present, 0 is the default.

- #number : int between 0 and 127 : the preset number in the bank -
  mandatory.

The preset may also be defined by a unique int, wich is treated as
the preset number, assuming that the MIDI bank is 0 (zero).

In all cases, the preset is looked up in the SoundFont stack, starting
from the first SoundFont up the stack, until a corresponding preset is
found. The found preset is assigned to the channel.  The maximum
number of channels are defined using the 'new' method.

If a preset was previoulsy assigned to that channel, it is forgotten,
but all noteon finish normally.

Returns an error code (no synth, no SoundFonts, bad
channel, bad preset definition).


getProgram(object me, int channel)
-----------------

ex : getProgram(iiwuObj, 0)

Returns information about the preset assigned to the channel.  The
information is of the form : [#name:"presetName", #bank:presetBankNb,
#number:presetNumber] The maximum number of channels are defined using
the 'new' method.

May return an error code (no synth, no preset
assigned, bad channel number)


note(object me, int channel, int key, float vel, int dur, plist seq)
-----------------

ex : note(iiwuObj, 1, 38, 1.0, 1000) 

Plays a note, using the specified 'channel' and 'key', with the
specified velocity (strength). The duration 'dur' of the note is
specified in ticks.

0.0 <= vel <= 1.0 (automatically limited if smaller or greater)
0 <= key <= 127

The maximum number of channels are defined using the 'new' method.

Returns an error code (no synth, no SoundFonts, bad
channel, no preset assigned, bad key, bad vel).


noteon(object me, int channel, int key, float vel, plist seq)
-----------------

ex : noteon(iiwuObj, 1, 38, 1.0)

Starts a note, using the specified 'channel' and 'key', with the
specified velocity (strength).

0.0 <= vel <= 1.0 (automatically limited if smaller or greater)
0 <= key <= 127

The maximum number of channels are defined using the 'new' method.

Returns an error code (no synth, no SoundFonts, bad
channel, no preset assigned, bad key, bad vel).


noteoff(object me, int channel, int key, plist seq)
-----------------
ex : noteoff(iiwuObj, 1)

Stops all playing notes on the given 'channel' and the given 'key'.

The maximum number of channels are defined using the 'new' method.

Returns an error code (no synth, no SoundFonts, bad
channel, no preset assigned).


controlChange(object me, int channel, plist controlParams, plist seq)
-----------------
ex:
controlChange(obj, 1, [#pitchbend: 1.0, #sustain:1])
controlChange(obj, 1, [#pan: -0.2, #sustain:1, #volume:0.5, #reverbsend:1.0]) 

This function allow to change some control parameters of the given
channel. The effect is immediate and allows for continuous
modification of a sound.

The 'controlParams' is a lingo property-list of key-value pairs, with
the key describing the control parameter to affect, and the value
specifying the amount of the change. For some keys, the value is not
taken into account. The list of currently implemented keys is the
following :

- #pitchbend: float between -1.0 an 1.0: sets the pitchbend level
  0.0 means no pitchbend.
  The pitchrange may be configured in the preset (for
  loaded SoundFonts), but the default range corresponds to 4 steps
  (one step = one semi-tone), so a value of -1.0 means two steps down,
  and a value of 1.0 means two steps up.

- #pan: float between -1.0 an 1.0: sets the pan level.
   -1.0 is all sound on left channel, 1.0 is all sound on right channel
   0.0 is sound in center.

- #volume: float between 0.0 an 1.0: sets the volume level.
   0.0 is silence, 1.0 is full volume.

- #reverbsend: float between 0.0 an 1.0. Sets the volume of the auxiliary
   output send to the reverb module. 0.0 is no signal, 1.0 is full
   volume.

- #chorussend: float between 0.0 an 1.0. Sets the volume of the auxiliary
   output send to the chorus module. 0.0 is no signal, 1.0 is full
   volume.

- #sustain: int = 0 or 1: sets or removes the sustain from the
   channel.

- #modulation: float between 0.0 an 1.0. Amplitude modulation.
   Vibrato.

Returns an error code (no synth, no SoundFonts, bad
channel, no preset assigned, unknown controlKey, bad controlValue).


getControl(object me, int channel, symbol ctrl)
-----------------
ex. getControl(iiwuObj, 1, #volume)

Returns the value of a controller.


getControls(object me, int channel)
-----------------
ex. getControls(iiwuObj, 1)

Returns a property list with the values of all controllers in the
form: [#pan: 0.4, #sustain:1, #volume:0.8, #reverbsend:1.0, ...]


allsoundsoff(object me, int channel, plist seq)
-----------------

Instantly stops all sound on the channel. The optional argument is
the sequencer information. Returns an error code (no sequencer).


allnotesoff(object me, int channel, plist seq)
-----------------

Sends a noteoff to all currently playing notes on the channel.  The
optional argument is the sequencer information. Returns an error code
(no sequencer).



---------------------------
-- Debug and maintenance
---------------------------

debug(object me, string logFile)
-----------------

ex : debug(iiwuObj, the moviePath&"logfile")

Sets the debug mode of the Xtra.
If a logFile is provided, debug is set.
If VOID is provided, debug is turned off.
If debug is on, a log of all actions and errors is written in the logFile.

Returns an error code (cannot open/create log file).


getError(object me)
-----------------
ex : lastError = getError(iiwuObj)

returns a human readable string describing the last error that occured
in the Xtra.


getCPUUsage(object me)
-----------------
ex : aPercent = getCPUusage(iiwuObj)

returns a float representing the estimation of the percentage of CPU
used by the synthesizer, or an error code (no synth).

-------------------------------
-------------------------------
-------------------------------