diff --git a/fluidsynth/doc/FluidSynth-LADSPA.pdf b/fluidsynth/doc/FluidSynth-LADSPA.pdf new file mode 100644 index 00000000..432f3d67 Binary files /dev/null and b/fluidsynth/doc/FluidSynth-LADSPA.pdf differ diff --git a/fluidsynth/doc/midi_time.txt b/fluidsynth/doc/midi_time.txt new file mode 100644 index 00000000..dbc5f162 --- /dev/null +++ b/fluidsynth/doc/midi_time.txt @@ -0,0 +1,48 @@ + + +I use this document as a memo to understand timing in MIDI files. [PH] + +- MIDI Quarter Note: There is the MIDI quarter note. For those of you + who are interested in the music notation of a MIDI file, beware, a + MIDI quarter note in NOT necessarily equal to a notated quarter + note. + +- MIDI Clock: There are *24* MIDI clocks in a MIDI quarter note (this + is forced upon you) + +- MIDI Tempo: There are miditempo x 24th of a micro-second in a MIDI + clock. The value of miditempo is given by the SetTempo meta-event. + +- Division: A MIDI quarter note is split into N divisions. The value + of divisions can be found in the midifile header (MThd chunk). + +- Delta-time: The time between one event and the next is called + delta-time. The MIDI event delta-times are specified in divisions. + + +* How long is a MIDI Clock? + + midi-clock = miditempo * 1e-6 / 24 sec + +* How long is a MIDI Quarter Note? + + quarter-note = 24 midi-clocks + = 24 * miditempo * 1e-6 / 24 sec + = miditempo * 1e-6 sec + +* How long is a Division (a "tick" or "delta-time")? + + 1 delta-time = 1 tick = quarter-note / divisions + = miditempo / divisions / 1e6 sec + = miditempo / divisions / 1000 msec + + +To handle music notation, two more concepts are introduced: + +- There are *Nm* MIDI clocks in a metronome ticks +- There are *N32* notated 32nd notes in a MIDI quarter note + +Nm and N32 can be found in the TimeSignature meta event + + + diff --git a/fluidsynth/doc/xtrafluid.txt b/fluidsynth/doc/xtrafluid.txt new file mode 100644 index 00000000..4fb8f23f --- /dev/null +++ b/fluidsynth/doc/xtrafluid.txt @@ -0,0 +1,907 @@ +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). + +------------------------------- +------------------------------- +-------------------------------