Resolution
SequenceXtra has an internal resolution of 480 pulses per quarter note (ppq). In this manual we will refer to these pulses as ticks. Ticks are used throughout to describe time positions as well as note lengths. A quarter note is 480 ticks long, an eight note 240, a whole note 1920 etc. Thus, the first beat in bar 5 (assuming 4/4), is positioned at tick 9600. In Appendix 1 You will find a table that shows various note values as well as positions described as ticks.

 

Syntax
SequenceXtra handles a large number of MIDI-messages. Many of these messages are composed of a number of elements. sequenceXtra uses Lingo lists to handle MIDI-messages that consists of several elements. Lists is one of Lingos data types, and there are two types of Lists in Lingo: linear lists and property lists. SequenceXtra uses both types for different purposes.

Sourceforce has put together a set of behaviors for sequenceXtra. These are freely downloadable from our web site; www.sourceforce.nu.

Most of the commands and functions in sequenceXtra is related to a sequenceXtra song. These commands always use the song variable as argument to the command or function

sxPlay(mySong)

Time positions and lengths
SequenceXtra can use two ways to describe time positions and lengths.

- As an integer
- As a linear list with three or four elements

If You use an integer sequenceXtra will normally interpret this as a bar number, or a number of bars (some functions uses or returns a tick, this is described thruout the manual).

If You use a list sequenceXtra will interpret it like this:

Time position: [2,3,3,65]
bar 2, quarter note 3, sixteenth note 2, tick 65
(the tick element can be left out)

Length: [2,3,3,65] -
2 bars + 3 quarter notes + 3 sixteenth notes + 65 ticks
(i e almost three bars long)

Normally You can use which ever method You like. SequenceXtra will recognize what You do and interpret correctly.

Events, Parts, Tracks and Songs
A sequenceXtra Song is built by Tracks. A Track is built by Parts. And the Parts contains the MIDI events.

Events
The MIDI specification dictates the decimal codes for every possible MIDI event. SequenceXtra describes events as a list of decimal integers. The second value in a MIDI event description in sequenceXtra consists of a combination of event type and MIDI channel. In Appendix 2 of this manual You will find a listing of event types and their decimal numeric codes

For instance, a Note-event in sequenceXtra consists of five elements:

position, eventType+MIDI channel, note number, velocity and length.

An eight note of the note C on MIDI channel 1 played on the first beat of bar 1 is built like this:

1920, 144, 60, 100, 240

• 1920 means 1920 ticks from the starting position (see Appendix 1)
• 144 is a noteOn event on MIDI channel 1 (see Appendix 2)
• 60 is middle C
• 100 is the velocity
• 240 is the length of an eight note.

The time position is always relative to the part that contains the event. If the Part is located in bar 6 in 4/4, the event in the example above would be on the first beat of bar 7 (since 0 is the first time position in a Part). The fourth and fifth values, (100 ,240) in the example above is only needed if the MIDI-message requires it.

Event list
When You build a list of events (an Event list), You must find a way to separate the events from each other. To do this sequenceXtra expects every event to be a linear Lingo list. An event list is therefore a list of lists:

Example:
[ [144, 63, 100, 240], [3840, 144, 66, 85, 240], [5760, 144, 54, 23, 240] ]

Note the double brackets in the beginning and the end of this list. The first and last bracket encloses the event list, while every event also is a list of its own.

Parts
A part consists of a time position followed by one Event list. The time position shows where the part begins. Each Part is identified with a unique ID number, which is used to reference the part.

Example:
[1,1,1,1],[[1920,144,63,100,240],[3840,144,66,85,240],[5760,144,54,23,240]]

Tracks
A Track consists of a number of Parts. On the Track You must be able to separate the parts from each other and therefore sequenceXtra need to have every Part as a linear list, just like the Eventlists. The first element in the part is the time position and the second element is that Parts Event list.

Example:
eventList1 = [[0,192,60], [480,144,62,80,400], [960,144,47,80,240]]
eventList2 = [[0,144,60,100,200], [240,144,62,70,200], [480,144,64,80,200]]

Track1= [[[1,1,1,1],eventList1], [[16,1,1,1],eventList2]]

Songs
A song consists of Tracks. You can create a song from a linear list of tracks.

Example:
mySong= [Track1, Track2, Track3...]

As You can see its all built on Lingo lists. Almost every aspect of sequenceXtra can be described as a Lingo list. When You send commands to sequenceXtra that returns information, this information is almost always presented to You in the form of a Lingo list. So.. if You haven't dug into the world of lists in Lingo, now is the time...

Result codes
Every time You issue a command to sequenceXtra, the Xtra returns a result code. This code is stored in a system variable: the result. After issuing a command You can examine the result and act upon that. We recommend "defensive programming" where You evaluate the result code after every command sent to sequenceXtra to reduce program errors for the end user. Typically sequenceXtra returns 0 to report OK. Certain commands and functions however, are designed to return some sort of value. These commands use the expected result to report OK back to Lingo.

Below is a list of result codes that every sequenceXtra command and function returns.

0 or the expected result: OK
-1: sequenceXtra not initialized - use sxOpenSequencer()
-2: Song does not exist - use new() to create a song
-3: Track does not exist- use sxCreateTrack() to create a Track
-4: Part does not exist - use sxCreatePart() to create a Part
-10: Wrong argument type
-11: Argument out of allowed range
-12: Director out of memory
-15: Function not allowed in plug in mode.

Almost every command and funcion can be used during playback!