Global Functions

The functions on this page are called "Global funcitons". These functions do not relate to a specific song, and hence need no reference to one.

sxOpenSequencer({#noOMS})
sxOpenSequencer establishes a connection between the Xtra and QuickTime or OMS on the Mac and MME on Windows. sxOpenSequencer can be used to switch between between OMS and QuickTime on the Macintosh platform. Before this command is used, sequenceXtra has to be disconnected from the MIDI-system with the sxCloseSequencer() command (below)

MACINTOSH ONLY:
If the argument #noOMS (optional) is isssued sequenceXtra will connect to QuickTime even if OMS is present in the system. OMS is then ignored by sequenceXtra. The windows version of sequenceXtra will always ignore this parameter.

Result code: Standard error code

Example:
on mouseUp me
 sxCloseSequencer()
 sxOpenSequencer(#noOMS)
end mouseUp

sxCloseSequencer()
sxCloseSequencer will close sequenceXtra and release all memory used by it. The connection to QuickTime/OMS/MME is disabled. After this command sequenceXtra will not respond to any command sent to it.

Result code: Standard error code

Example:
on mouseUp me
  sxCloseSequencer()
end stopMovie

new(xtra "sequenceXtra", tracks)
new creates a new sequenceXtra song. The argument tracks must be an integer that represents the number of Tracks that shall be initially created in Your song.
The MIDI channel of each Track will be the same as the track number. If You create more than 16 tracks, the channel numbers start over from 1, beginning with Track 17. You can create and delete Tracks dynamically with the sxCreateTrack() and sxDeleteTrack() functions.

Result code: Standard error code

Example:
on startMovie
 global mySong
 mySong = new(xtra "sequenceXtra", 16)
end startMovie

This will create a new song, referenced by the variable mySong, and containing 16 Tracks.

sxGetOutputList()
sxGetOutputList returns a linear Lingo list of strings containing the MIDI devices installed on the current system. On the Macintosh, If OMS is not installed, this function will return an empty list, since QuickTime is the only available output device.

Result code: Standard error code

Example:
put sxGetOutputList()
--["Sound Canvas","MU80",QuickTimeMusic"]

sxSetOutput(outputNumber)
sxSetOutput connects sequenceXtra to the MIDI device indicated by outputNumber . OutputNumber is an integer that refers to the devices position in the list returned by the function sxGetOutputList(). The example will select "Sound Canvas" from the list above.

Result code: Standard error code

Example:
on mouseUp 
 sxSetOutput(1) 
end mouseUp

sxFlushMIDIIn()/sxFlushMIDIOut()
sxFlushMIDIIn/Out will delete all events from one of sequenceXtras two buffers. Use this function to "clean up" sequenceXtra from unwanted residual events before You issue sxGetMIDIIn() or sxGetMIDIOut() .

Resultcode: standard error code

Example:
on mouseUp
 sxFlushMIDIIn()
end mouseUp

sxSendMIDI(event)
sxSendMIDI will send one MIDI event directly to the current MIDI device. This funcion does not require a song reference and thus, no song needs to be created to use sxSendMIDI. You can also use this command to send System Exclusive messages.

Example:
on mouseDown
 sxSendMIDI([192,66]) --a program change nr 66 on MIDI channel 1
end mouseDown

sxGetMIDIIn() [used to be sxGetMIDI() - which is still supported]
sxGetMIDIIn will return the oldest event from the buffer for incoming MIDI events and subsequently delete the event from the buffer. Use this function to use incoming MIDI data in realtime. For example You could use sxGetMIDI to create real time graphic feedback on what the user plays on a MIDI keyboard.

Resultcodes:
0: No events in buffer
a list: the oldest event

Example:
on exitFrame
 theEvent = sxGetMIDIIn()
 if listP(theEvent) then myEvent = string(theEvent)
end exitFrame

sxGetMIDIout()
sxGetMIDIout will return the oldest event from the buffer for outgoing MIDI events and subsequently delete the event from the buffer. Use this function to use outgoing MIDI data in realtime. For example You could use sxGetMIDI to create real time graphic feedback on the music that´s playing from a MIDI-file.

Resultcodes:
0: No events in buffer
a list: the oldest event

Example:
on exitFrame
 theEvent = sxGetMIDIOut()
 if listP(theEvent) then myOutEvent = string(theEvent)
end exitFrame

sxSendInputWaiting(true|false) and sxSendOutputWaiting(true|false)
sxSendInputWaiting and sxSendOutputWaiting will activate or deactivate a function that reports to Director if there are events waiting in one of the MIDI buffers.
If this function is activated (true) sequenceXtra will call the handler sxMIDIInWaiting or sxMIDIOutWaiting in the movie script of the current Director Movie (you will have to create the handlers yourself). This can be used to retreive in- or outgoing MIDI data without constantly issuing the sxGetMIDIIn() or sxGetMIDIOut() command.

Result code:
Standard error code

Example:

-- This example will show the spriteChannel that corresponds to the incoming
-- note number if the velocity > 0 (i e when a note is triggered) and hide it when its velocity
-- is 0 (i e when the note is released)

on sxMIDIInWaiting()
 theEvent = sxGetMIDIIn()
 if (theEvent[2] >= 144) AND (theEvent[2] <= 159) 
   --is this a note event?? 
   sprite(theEvent[3]).visible = theEvent[4]
 end if
end sxMIDIInWaiting

sxSetPrgChase(state)
sxSetPrgChase will set the state of the chase of program change events when a sxPlay() command is issued. State must be 0 or 1. A value of 1 blocks the chase and a value of 0 will chase program change events. sequenceXtra defaults to 0, i e chase is ON.

Result codes: Standard error code