RTMix
<< | table of contents
| >>
4. Scripting Language
RTMix's scripting language is its heart and soul. It is in the scriptfiles where all of the RTMix's power is contained. The scripting language contains a number of various events which can take similar (and often the same) parameters in order to describe their properties (such as timing). If you have ever been exposed to Paul Lansky's RT, then this scripting language will look very familiar. Yet, even if you had no prior exposure to scripts, it should be still a rather smooth experience. We will start with an overview of the language.
4.1 Overview
Scriptfiles contain series of commands that are compiled before starting the playback. The events are stored into a virtual cue and are retrieved as needed (usually either based on their timing or using a real-time trigger). Each of the commands are referred to as an EVENT, while each of the options associated with a particular event is referred to as PARAMETER. All events have their MANDATORY and OPTIONAL parameters. Optional parameters usually subtly alter the behavior of the event in question.
4.2 Syntax
The scriptfile can only have ONE EVENT PER LINE. Having more than one will result in compilation error. This is to ensure that the scriptfile is as legible as possible. The built-in editor has the word-wrap enabled by default, hence some of the more elaborate events might "spill" into the next line. The editor will treat all this as a SINGLE LINE (kind of like emacs, except that there will be no "backslash" at the end of the line signaling extension of the line). The line counter at the bottom of the "editor" tab reflects this as described.
The scriptfile compiler understands two types of information:
Comments are delineated by C-convention double-slash ("//") at the
beginning of the line. Everything following the double slash in a particular
line will be considered a comment. Multi-line comments need to have
double-slash at the beginning of every line belonging to that comment. A
typical example of a comment would be:
//This is a comment
Events which have the following
syntax:
<event-name> (
[>param_1]={"value_1"} [>param_2]={"value_2"} ...
[>param_n]={"value_n"} );;
NOTE:
Parameters do not have to be in any particular order.
Spacing is generally not crucial except in a few instances:
All parameter names need to be preceeded with square bracket + greater-than sign ([>) and must end with closing square bracket (]) and must not have any spaces in between (i.e. "[>do]" is ok, while "[> do ]" is not).
All parameter values need to be delineated by a curly bracket + quotation mark ({") and the opposite for closing brackets ("}). Spaces between those will result in an error.
Termination of an event-line must be done with a double semi-colon (;;). Again, spaces between the two semicolons will result in an error.
There are some additional event-specific exceptions which are listed below, but generally this is the main syntax for the script file.
Finally, the syntax is NOT case-sensitive. However if you do come across an inconsistency, please do let me know because it is most likely a bug.
4.3 Available Commands
Each command has an ID value associated to it. This is important since ID values, like many other numeric values can be altered at run-time (something that can be a lot of fun). Each command's ID is equal to the last digit of the sub-chapter number (i.e. event's sub-chapter number is 4.3.1, hence its ID = 1). Events with ID's equal to 0 (something that is achievable only through real-time alterations -- see 4.5.6) are simply ignored.
Available events can be grouped based on their scope and functionality:
CORE EVENTS: event (4.3.1), countdown (4.3.2), warning (4.3.8)
TRANSPORT CONTROLS: pause (4.3.5), stop (4.3.6), checkpoint (4.3.4), jump, (4.3.10), rew (4.3.14), ffw (4.3.15)
MODULAR VARIABLE MANIPULATION EVENTS: assign (4.3.17), seed (4.3.13), randomize (4.3.11), change (4.3.12)
NETWORK EVENTS: setnet (4.3.19), togglenet (4.3.20), and just about any other event with a [>net] flag
REAL-TIME EVENTS: togglert (4.3.18), togglemidi (4.3.21), and just about any other event with a rt[<num>] value substituted for its timing
VISUAL EVENTS: almost any event with the proper parameters (countdown and warning having them on by default)
Now, we'll look closer at each of these events and their syntax, parameters, as well as their behavior.
4.3.1 event
DESCRIPTION:
The event is the "backbone" of external event-invoking mechanism and possibly of the whole scriptfile. It is primarily used for external system calls that will trigger other applications and processes. However, it is also capable of sending an array of MIDI data via MIDI port, a single or an array of OSC events, as well as pose as an MIDI router for other applications requiring MIDI (for more info on MIDI and OSC events, see 4.5.2, 4.5.4, and 4.5.5).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>do] -- event to be triggered as it would be typed in the shell (i.e. "play my_soundfile.wav"). This parameter can also take value "none" in which case it will be disregarded. NOTE: syscall events DO NOT require ending "&" that would imply a background process, but if you feel compelled to add them, then the compiler adjusts accordingly. Event can also be MIDI or OSC-related (see 4.5.4 and 4.5.5).
[>kill] -- event or system-call-invoked process to be "killed" in the case of termination of playback (i.e. "play" or "pd"). This parameter can also take value "none" in which case it will be disregarded.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>net] -- value that determines whether the event will be sent via network, interpreted locally, or both (see4.5.1). The default value for event is "-2" (local), while valid range is "-2" to "255" ("-1" is for global including the client itself, and "0-255" for a specific networked client).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
event( [>at]={"0.5"} [>say]={"This
is an event"} [>do]={"play any_sound.wav"} [>kill]={"play"}
);;
event([>say]={"none"} [>at]={"rt[0]"} [>do]={"play
any_sound.wav"} [>kill]={"play"} [>light]={"1"} [>lightlength]={"5"}
[>accel]={"d"});;
4.3.2 countdown
DESCRIPTION:
Countdown event is very similar to the event, except that it also employs a countdown mechanism. At the end of the countdown, it executes the given event, specified with the [>do] parameter. Countdown and Warning events are the only ones allowed to utilize the Main widget's countdown counter. For more info on light events and countdown counters see 4.5.3).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>do] -- event to be triggered as it would be typed in the shell (i.e. "play my_soundfile.wav"). This parameter can also take value "none" in which case it will be disregarded. NOTE: syscall events DO NOT require ending "&" that would imply a background process, but if you feel compelled to add them, then the compiler adjusts accordingly. Event can also be MIDI or OSC-related (see 4.5.4 and 4.5.5).
[>kill] -- event or system-call-invoked process to be "killed" in the case of termination of playback (i.e. "play" or "pd"). This parameter can also take value "none" in which case it will be disregarded.
[>dur] -- duration of the countdown expressed in seconds (i.e. "9.23" or "144"). The maximum countdown is equal to the counter's capability (main countdown timer is capable up to 59mins 59.99secs, while external Warning windows are capable of only up to 59.99secs).
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). Default values are light=3, lightlength=2secs, preplength=5secs, and blinkspeed=1sec.
[>net] -- value that determines whether the event will be sent via network, interpreted locally, or both (see4.5.1). The default value for event is "-2" (local), while valid range is "-2" to "255" ("-1" is for global including the client itself, and "0-255" for a specific networked client).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
countdown( [>at]={"11.23"}
[>say]={"This is a countdown"} [>do]={"none"} [>kill]={"none"}
[>dur]={"5.77"} );;
countdown( [>say]={"none"} [>at]={"111.1"}
[>do]={"CMIX < scorefile.sco"} [>kill]={"play"} [>light]={"4"}
[>lightlength]={"5"} [>preplength]={"5"} [>blinkspeed]={"0.5"}
[>dur]={"30"} );;
4.3.3 text
DESCRIPTION:
Text event is a simple event that outputs text onto the notification interface.
IMPORTANT: any event invoking the [>say] parameter can have v[<num>] variables included, which will be then verbosely displayed on screen with the stored values at the time of execution. For instance, if the first stored variable is equal to 5, then having
[>say]={"Show me the var 0 value: v[0]"}
would result in an output
"Show me the var 0 value: 5"
NOTE: MIDI values cannot be displayed as a part of the text due to fact that they can be already easily logged in the Console window using the "MIDI logging" button (see 3.4.3) and due to their limited scope of behavior cannot serve an important role in the notification interface.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>say] -- string (i.e. "This is an example") that will be posted in the Notification Interface (see 3.4.1). It can be explicitly set to "none" which will disregard it (although that defeats the whole purpose of this event).
OPTIONAL PARAMETERS:
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>net] -- value that determines whether the event will be sent via network, interpreted locally, or both (see4.5.1). The default value for event is "-2" (local), while valid range is "-2" to "255" ("-1" is for global including the client itself, and "0-255" for a specific networked client).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
text( [>at]={"0"} [>say]={"So it
begins..."});;
text([>say]={"Keyboard key 'd' has been released"}
[>at]={"rt[0]"} [>light]={"4"} [>lightlength]={"5"}
[>accel]={"^d"});;
4.3.4 checkpoint
DESCRIPTION:
Checkpoint event is a marker in the timeline that user can quickly fast-forward or rewind to. One can think of checkpoints as being "rehearsal marks" in a score. The beginning of the piece is considered the initial, 0th checkpoint.
IMPORTANT: while this event may have an 'absat' value set, it will never be reachable by any of the "jumping" events, such as "jump" (see 4.3.10), "rew" (see4.3.14), and "ffw" (see 4.3.15), even the transport controls "rew" and "ffw" (see 3.2) due to fact that those events strictly are bound to the non-absat checkpoints. You may still choose to use this one in combination with the "absat" flag as a some kind of a marker (although you could do probably the same thing with a "text" event).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>say] -- string (i.e. "This is an example") that will be posted in the Notification Interface (see 3.4.1). It can be explicitly set to "none" which will disregard it (although that defeats the whole purpose of this event).
OPTIONAL PARAMETERS:
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
checkpoint( [>at]={"1"}
[>say]={"This is checkpoint no#1"} );;
checkpoint( [>at]={"15"}
[>light]={"4"} [>lightlength]={"5"} [>blinkspeed]={"0.2"}
[>say]={"none"} );;
4.3.5 pause
DESCRIPTION:
Pause event is equivalent to the "pause" transport control. It can be either bound to a particular time, or a real-time trigger.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs. NOTE: pause does invoke a default blinking behavior of the playback LED on the main widget (see 3.2).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
pause( [>at]={"0.5"}
[>say]={"Pausing..."});;
pause([>at]={"rt[0]"} [>accel]={"A"}
[>say]={"Here comes pause"});;
4.3.6 stop
DESCRIPTION:
Stop event is equivalent to the "stop" button in the transport controls (see 3.2). It can be either bound to a particular time, or a real-time trigger.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
stop( [>at]={"0.5"}
[>say]={"Stopping..."});;
stop([>at]={"rt[0]"} [>accel]={"A"}
[>say]={"The performance just came to a screeching halt..."});;
4.3.7 clear
DESCRIPTION:
Clear event clears the contents on the Notification widget. It can be either bound to a particular time, or a real-time trigger.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
OPTIONAL PARAMETERS:
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
clear( [>at]={"2"}
);;
clear([>at]={"rt[0]"} [>accel]={"Ctrl+K"});;
4.3.8 warning
DESCRIPTION:
Warning event is very similar to the countdown (see 4.3.2), except that it executes the command at the beginning of the countdown, rather than upon reaching the end. Countdown and Warning events are the only ones allowed to utilize the Main widget's countdown counter. For more info on light events and countdown counters see 4.5.3).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>do] -- event to be triggered as it would be typed in the shell (i.e. "play my_soundfile.wav"). This parameter can also take value "none" in which case it will be disregarded. NOTE: syscall events DO NOT require ending "&" that would imply a background process, but if you feel compelled to add them, then the compiler adjusts accordingly. Event can also be MIDI or OSC-related (see 4.5.4 and 4.5.5).
[>kill] -- event or system-call-invoked process to be "killed" in the case of termination of playback (i.e. "play" or "pd"). This parameter can also take value "none" in which case it will be disregarded.
[>dur] -- duration of the countdown expressed in seconds (i.e. "9.23" or "144"). The maximum countdown is equal to the counter's capability (main countdown timer is capable up to 59mins 59.99secs, while external Warning windows are capable of only up to 59.99secs).
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). Default values are light=3, lightlength=2secs, preplength=5secs, and blinkspeed=1sec.
[>net] -- value that determines whether the event will be sent via network, interpreted locally, or both (see4.5.1). The default value for event is "-2" (local), while valid range is "-2" to "255" ("-1" is for global including the client itself, and "0-255" for a specific networked client).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
warning( [>at]={"11.23"}
[>say]={"This is a warning"} [>do]={"none"} [>kill]={"none"}
[>dur]={"5.77"} );;
warning( [>say]={"none"} [>at]={"111.1"}
[>do]={"sox foo.snd"} [>kill]={"play"} [>light]={"4"}
[>lightlength]={"5"} [>preplength]={"5"} [>blinkspeed]={"0.5"}
[>dur]={"30"} );;
4.3.9 metronome
DESCRIPTION:
Metronome is a specific event tied to the Metronome window (see 3.6.4). It utilizes a couple of event-specific parameters and can be triggered both as a timed event or in real-time.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>num] -- refers to one of the four external Metro windows. Valid values are 1,2,3, or 4.
[>bpm] -- denotes "beats-per-minute" tempo to be set by the Metro window in question (0-999). Float values are rounded to the nearest integer.
[>meter] -- the most powerful parameter where user can specify a meter (i.e. "4" for four beats), or a compound meter (i.e. "3+4+2+1") which will create a number of rows, each populated with the appropriate number of LED's. Each row is separated by the "+" sign. Zero creates an empty row (i.e. "3+0+1").
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>net] -- value that determines whether the event will be sent via network, interpreted locally, or both (see4.5.1). The default value for event is "-2" (local), while valid range is "-2" to "255" ("-1" is for global including the client itself, and "0-255" for a specific networked client).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
metronome( [>at]={"1"}
[>say]={"none"} [>num]={"1"} [>bpm]={"93"} [>meter]={"2+3+2+1+0+5"}
);;
metronome( [>say]={"Boo!"} [>light]={"4"} [>at]={"4"}
[>num]={"1"} [>bpm]={"144"} [>meter]={"11"}[>lightlength]={"5"}
[>preplength]={"5"} [>blinkspeed]={"0.5"} );;
4.3.10 jump
DESCRIPTION:
Jump event is used to jump between the established checkpoints (see 4.3.4). Jump can be either forwards or backwards, as well as either absolute or relative. See below for more info.
IMPORTANT: It is quite possible that the awkward placement of "jump" (see 4.3.10), "rew" (see 4.3.14), and "ffw" (see 4.3.15) events can cause an infinite recursion. RTMix is by default able to handle single-level recursions by simply stopping the playback and notifying the user of a recursion. See tutorials for an example.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>to] -- denotes a number of checkpoints to skip. It can be both positive or negative. If the number implies jumping back beyond the beginning, it will result in a jump to beginning. By the same token if the jump forwards is larger than the number of checkpoints, then the resulting jump will be to the last available checkpoint. If the jump is absolute (see next parameter), then the number is always interpreted as a positive value.
[>abs] -- determines whether the jump is relative ("0") or absolute ("1"). Relative jumps count from the current position in the work, while the absolute ones count from the beginning of the piece. If absolute jump is out of bounds, it is ignored.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.IMPORTANT: while events "rew", "ffw", and "jump" do allow setting of this parameter, they still observe jumps only to relative events.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
jump( [>at]={"100"}
[>say]={"Whee!!!"} [>to]={"-2"} [>abs]={"0"} );;
jump(
[>at]={"232.22"} [>to]={"12"} [>abs]={"1"} [>light]={"13"}
[>lightlength]={"1"} [>blinkspeed]={"0.1"} );;
4.3.11 randomize
DESCRIPTION:
Randomize event is usually used in combination with the "change" event (see 4.3.12), "seed" event (see 4.3.13), and "assign" event (see 4.3.17). All these events are used for manipulation of simple float or integer variables. Up to 256 of the manipulated values can be stored for later retrieval and/or further manipulation. The purpose of such variable manipulation is to provide user with a modular functions that can be used for a variety of purposes:
One could for instance have a modular system call that invokes similarly named soundfiles, such as "sound1.wav" and "sound2.wav", where modular substitution of a manipulated variable could enable the event to execute either soundfile, therefore resulting in a modular system call syntax (in this case "play sound<variable>.wav").
Manipulating probabilities of particular events (see 4.5.9).
Alter events' parameters and/or behavior (see 4.5.3).
Other.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>type] -- determines whether the generated value is stored as an float ("0") or a scaled integer number ("1-65536"). The range of the generated float-point random values is always between 0 and 1 (i.e. 0.45261), while integer values are scaled according to their type (multiplied by the type value). For instance type 300 could generate any number between 0 and 300.
[>method] -- describes the method of generating the random numbers. There are seven methods: rrand, brrand, gaussian, cauchy, linlo, linhi, and triangle (numbered 0-6). They mostly differ in the way the random values are weighed (i.e. linlo tends to give lower numbers, while linhi higher). The range of the generated values depends on the "type" parameter and the variable type (integer or float-point).
[>store] -- (0-255) determines into which variable the resulting value will be stored. Later it will be possible to retrieve the variable's value by using "v[<number_0-255>]" syntax in designated parameters (for more info see 4.5.6).
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
randomize( [>at]={"2"}
[>type]={"0"} [>method]={"0"} [>store]={"0"} );;
randomize(
[>at]={"1234"} [>say]={"Let's make some random numbers..."}
[>type]={"65536"} [>method]={"4"} [>store]={"255"} [>absat]={"1"}
);;
4.3.12 change
DESCRIPTION:
Change event is usually used in combination with the "randomize" event (see 4.3.11), "seed" event (see 4.3.13), and "assign" event (see 4.3.17). All these events are used for manipulation of simple float or integer variables. Up to 256 of the manipulated values can be stored for later retrieval and/or further manipulation. The purpose of such variable manipulation is to provide user with a modular functions that can be used for a variety of purposes:
One could for instance have a modular system call that invokes similarly named soundfiles, such as "sound1.wav" and "sound2.wav", where modular substitution of a manipulated variable could enable the event to execute either soundfile, therefore resulting in a modular system call syntax (in this case "play sound<variable>.wav").
Manipulating probabilities of particular events (see 4.5.9).
Alter events' parameters and/or behavior (see 4.5.3).
Other.
Change event has a specific function to alter event values that are result of a MIDI input (only real-time events utilizing MIDI triggers), by retrieving one of the stored variables. or both (see 4.5.6). The resulting value can then be applied to various parameters of the event that follows the "change" event (or a specific event type that might not immediately follow the "change" event in which case RTMix searches for the next event of that type in the cue, ignoring "jumps" and other timeline-altering events) or stored back for later retrieval.
Despite great flexibility, change event is most commonly used to alter probabilities of the oncoming events (see 4.5.9).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>func] -- contains the mathematical formula which will be utilized to produce a final result. Both incoming MIDI events and stored variables can be included in the formula (see 4.5.6). Almost all calculator-based operations are allowed (i.e. "(5*2 + 2^2 - abs(-2))+ v[0]" would be an example of a valid entry).
[>var] -- determines either into which variable the resulting value will be stored (0-255) (later it will be possible to retrieve the variable's value by using "v[<number_0-255>]" syntax in designated parameters -- for more info see 4.5.6) or to specify which of the parameters of the event FOLLOWING this one will be affected by the final result (for more info see 4.5.6, as well as tutorials involving this event). Parameters that can be affected vary (i.e. [>say] parameter obviously cannot be affected since the output of this event is a numeric value), but generally just about any numeric parameter can be affected by this event. A typical example would be [>var]={"light"} in which case the light visuals for the following event would be appropriately modified. Other example would be altering timing of a particular event with [>var]={"at"}, in which case the time alteration is relative and may not exceed boundaries of the neighboring events. This value can also be referring to a specific real-time event by being equal to [>var]={"rt[<number_of_real-time_event>]"}.
OPTIONAL PARAMETERS:
[>id] -- this optional and event-specific parameter can be used when the event that needs to be affected is not the next in line, in which case the parser will search forward until it finds an event with the matching ID, and then appropriately alter its behavior as specified with the [>var] value.
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
change( [>at]={"4"} [>func]={"v[0]
- 0.7"} [>var]={"happen"} );;
change( [>at]={"4"} [>func]={"v[0]
- 0.7"} [>var]={"happen"} [>say]={"With that kind of alteration, the
chances for the next (abs!) event to occur are getting slimmer..."}
[>absat]={"1"} );;
4.3.13 seed
DESCRIPTION:
Seed event is usually used in combination with the "randomize" event (see 4.3.11), "change" event (see 4.3.12), and "assign" event (see4.3.17). All these events are used for manipulation of simple float or integer variables. Up to 256 of the manipulated values can be stored for later retrieval and/or further manipulation. The purpose of such variable manipulation is to provide user with a modular functions that can be used for a variety of purposes:
One could for instance have a modular system call that invokes similarly named soundfiles, such as "sound1.wav" and "sound2.wav", where modular substitution of a manipulated variable could enable the event to execute either soundfile, therefore resulting in a modular system call syntax (in this case "play sound<variable>.wav").
Manipulating probabilities of particular events (see 4.5.9).
Alter events' parameters and/or behavior (see 4.5.3).
Other.
Seed is directly related to the "randomize" event. It is used to "stimulate" computer to churn out random numbers, something that computer is incapable of doing themselves. Each seed value will give the same resulting number when a "randomize" call is executed. Therefore, the possible array from which one can pick a seed is rather large in order to minimize recurrence of random numbers.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>value] -- simply assigns a long integer value of the seed to the parser. If this number is equal to 0 then the seed is determined based on the Unix clock.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
seed( [>at]={"55.14"}
[>value]={"0"} [>say]={"This one will be based on the unix clock..."
);;
seed( [>at]={"0"} [>value]={"13243421"} );;
4.3.14 rew
DESCRIPTION:
Rew event (a.k.a. rewind) is equivalent to the "rew" button in the transport controls (see3.2). It can be either bound to a particular time, or a real-time trigger.
IMPORTANT: It is quite possible that the awkward placement of "jump" (see 4.3.10), "rew" (see 4.3.14), and "ffw" (see 4.3.15) events can cause an infinite recursion. RTMix is by default able to handle single-level recursions by simply stopping the playback and notifying the user of a recursion. See tutorials for an example.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>to] -- simply describes number of checkpoints to move back to. If the number exceeds the number of available checkpoints, the timer returns to the beginning. It accepts positive integer values.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.IMPORTANT: while events "rew", "ffw", and "jump" do allow setting of this parameter, they still observe jumps only to relative events.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
rew( [>at]={"0"} [>to]={"1"}
[>say]={"This one will cause an infinite recursion, but RTMix should be able
to handle it..." );;
rew( [>at]={"521.44"} [>to]={"5"} );;
4.3.15 ffw
DESCRIPTION:
Ffw event (a.k.a. fast-forward) is equivalent to the "rew" button in the transport controls (see3.2). It can be either bound to a particular time, or a real-time trigger.
IMPORTANT: It is quite possible that the awkward placement of "jump" (see 4.3.10), "rew" (see 4.3.14), and "ffw" (see 4.3.15) events can cause an infinite recursion. RTMix is by default able to handle single-level recursions by simply stopping the playback and notifying the user of a recursion. See tutorials for an example.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>to] -- simply describes number of checkpoints to move forward to. If the number exceeds the number of available checkpoints, the timer returns to the beginning. It accepts positive integer values.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.IMPORTANT: while events "rew", "ffw", and "jump" do allow setting of this parameter, they still observe jumps only to relative events.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
ffw( [>at]={"0"} [>to]={"1"}
[>say]={"Let's skip ahead" );;
ffw( [>at]={"521.44"} [>to]={"5"}
[>light]={"12"} [>lightlength]={"4"} );;
4.3.16 togglemetro
DESCRIPTION:
Togglemetro event is a specific event tied to the Metronome window (see 3.6.4). It utilizes a couple of event-specific parameters and can be triggered both as a timed event or in real-time. It is also similar in syntax to other toggle events "togglert" (4.3.18), "togglenet" (4.3.20), and "togglemidi" (4.3.21).
This event simply toggles a particular metronome (1-4) on or off. There are 4 types of switches (explained below).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>num] -- refers to one of the four external Metro windows. Valid values are 1,2,3, or 4.
[>status] -- defines the type of toggle to take place: 0 for stop & reset, 1 for stop, 2 for reset & start, and 3 for start.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>net] -- value that determines whether the event will be sent via network, interpreted locally, or both (see4.5.1). The default value for event is "-2" (local), while valid range is "-2" to "255" ("-1" is for global including the client itself, and "0-255" for a specific networked client).
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
togglemetro( [>at]={"1"}
[>num]={"1"} [>status]={"0"} [>say]={"Stop & Reset"}
);;
togglemetro( [>say]={"Boo!"} [>light]={"4"} [>at]={"32"}
[>num]={"4"} [>status]={"3"} );;
4.3.17 assign
Assign event is usually used in combination with the "randomize" event (see 4.3.11), "change" event (see 4.3.12), and "seed" event (see4.3.13). All these events are used for manipulation of simple float or integer variables. Up to 256 of the manipulated values can be stored for later retrieval and/or further manipulation. The purpose of such variable manipulation is to provide user with a modular functions that can be used for a variety of purposes:
One could for instance have a modular system call that invokes similarly named soundfiles, such as "sound1.wav" and "sound2.wav", where modular substitution of a manipulated variable could enable the event to execute either soundfile, therefore resulting in a modular system call syntax (in this case "play sound<variable>.wav").
Manipulating probabilities of particular events (see 4.5.9).
Alter events' parameters and/or behavior (see 4.5.3).
Other.
Assign is the most rudimentary of this group of events. It simply assigns a particular value to be stored into a particular variable. The value can be either float or integer.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>amt] -- a float or integer value to be stored.
[>store] -- designates to which of the storage variables the value is to be stored into (0-255), syntax being "v[<number>]".
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
assign( [>at]={"1.14"}
[>amt]={"0.564"} [>store]={"v[133]"} [>say]={"Text is always being
posted the first, hence the following value will not reflect the newly assigned
amount: v[133]" );;
assign( [>at]={"rt[0]"} [>accel]={"^t"}
[>amt]={"13243421"} [>store]={"v[3]"} );;
4.3.18 togglert
DESCRIPTION:
Togglert event is a specific event tied to the monitoring of the real-time events. Its behavior corresponds to the "toggle real-time events" button on the real-time tab (see3.4.3). It also resembles other "toggle" events in its syntax and properties.
Upon enabling the real-time monitoring all inbound real-time events will be interpreted. Furthermore, all resizable windows will cease to be resizable in order to minimize cpu utilization by RTMix's GUI. When the real-time event monitoring is enabled, the MIDI Monitoring button will become available (otherwise it is disabled).
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings. NOTE: in this case binding this event to a real-time accelerator does seem a bit redundant since it is a catch-22 situation: in order to enable the real-time events monitoring you need to press a real-time trigger which ironically won't register since real-time events monitoring is not toggled on :-).
[>status] -- defines the type of toggle to take place: 0 for "off", and 1 for "on".
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
togglert( [>at]={"1"} [>num]={"1"}
[>status]={"1"} [>say]={"Now you can use the real-time triggers! Yay!"}
);;
togglert( [>at]={"32"} [>status]={"0"} );;
4.3.19 setnet
DESCRIPTION:
Setnet event is a specific event tied to customizing networking settings. Its behavior corresponds to the various networking buttons found on the "network" tab (see 3.4.4). This event is peculiar because it is the only event that is timeless (does not have [>at] parameter) and is executed at compile-time.
Setnet can either set the localhost's socket to which other clients are going to be able to connect (default 9900), or configure one of the external clients, in which case it supplies client's hostname, port, and the id number to be associated with that connection (0-255 corresponding to the Network table).
PARAMETERS:
[>host] -- designates the name of the host. It can be either the hostname or the IP address.
[>socket] -- defines the socket number to which your client will be attempting to make a connection to (when requested to do so).
[>store] -- determines ID number which will be associated with this particular connection (also the column number in the "networking" table which it will populate). IMPORTANT: If this value is absent and the [>host] value is equal either to "localhost" or "127.0.0.1", the then the event is interpreted as a localhost's socket number change.
OPTIONAL PARAMETERS:
None.
EXAMPLES:
setnet( [>host]={"localhost"}
[>socket]={"9898"} );;
setnet( [>host]={"somewhere.out.there"}
[>socket]={"2121"} [>store]={"0"} );;
4.3.20 togglenet
DESCRIPTION:
Togglenet event is a specific event tied to enabling/disabling of the networking features. Its behavior corresponds to the various networking buttons found on the "network" tab (see3.4.4). It also resembles other "toggle" events in its syntax and properties.
Togglenet can either enable/disable localhost connectivity, or initiate connection to a remote client listed on the top of the networking tab (numbered 0-255). Such client needs to be initiated first by using the "setnet" event which is timeless and is always interpreted at compile-time (see 4.3.19).
IMPORTANT: while it is possible to create a localhost connection to the same client, this is not advisable, since it may cause an infinite recursion. RTMix has a network recursion filter that should be capable of disconnecting the host as soon as such recursion is found without hindering the continuation of the performance. Such recursions are logged in the console window.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings. NOTE: in this case binding this event to a real-time accelerator does seem a bit redundant since it is a catch-22 situation: in order to enable the real-time events monitoring you need to press a real-time trigger which ironically won't register since real-time events monitoring is not toggled on :-).
[>status] -- defines the type of toggle to take place: 0 for "off", and 1 for "on".
[>id] -- determines which connection needs to be toggled: -2 for the localhost, -1 for all external connections, and 0-255 for a specific external connection.
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
togglenet( [>at]={"5"}
[>status]={"1"} [>id]={"-2"} [>say]={"Starting localhost..."}
);;
togglenet( [>at]={"12"} [>status]={"0"} [>id]={"-1"}
);;
4.3.21 togglemidi
DESCRIPTION:
Togglemidi event is a specific event tied to the monitoring of the real-time MIDI events. Its behavior corresponds to the "Toggle MIDI Monitoring" button on the real-time tab (see 3.4.3). It also resembles other "toggle" events in its syntax and properties.
This option is only available if the real-time event monitoring is already on. If not, the event will be ignored.
PARAMETERS:
[>at] -- universal parameter that defines when the event will take place. It is specified as a float-point number in seconds (i.e. "93.5" = 1min 33.5secs). The timing resolution is up to the 1/100th of a second and its range is 0-359999.99secs. At can also have a real-time value, which means it is not timed at any specific point but rather triggered by an ACCELERATOR, in which case the syntax is "rt[0-255]" (0-255 being the real-time event binding). See 4.5.2 for more info on real-time bindings.
[>status] -- defines the type of toggle to take place: 0 for "off", and 1 for "on".
OPTIONAL PARAMETERS:
[>say] -- optional string (i.e. "This is an example") that will accompany event's execution by posting its text in the Notification Interface (see 3.4.1). By default it is equal to "none" which means that it will be disregarded.
[>accel] -- real-time accelerator to be used in combination with the real-time [>at] value (see 4.5.2). By default it is "none".
[>light], [>lightlength], [>dur], [>preplength], [>blinkspeed] -- visual effects associated with the event (see 4.5.3). The default behavior is that there are no visuals associated with this event, having values light=0, lightlength=0secs, preplength=0secs, and blinkspeed=0secs.
[>absat] -- value can be either "0" or "1" ("0" by default). "1" makes this event time itself against the ABSOLUTE TIMER, rather than the MAIN TIMER (see 3.6.2). For more info on absolute vs. relatively-timed events see 4.5.8.
[>happen] and [>chance] -- two values that determine the probability of this event's occurrence, both have a range of 0-1, both of their default values being 1 (or %100). For more info on probabilities, and their implementation see 4.5.9.
EXAMPLES:
togglemidi( [>at]={"1"}
[>num]={"1"} [>status]={"1"} [>say]={"Now you can use the real-time
MIDI triggers! Yay!"} );;
togglemidi( [>at]={"32"} [>status]={"0"}
);;
4.4 Debugging
RTMix has been designed to offer maximally verbose Console that can provide users with enough information to make bug-tracking easier. Coupled with the "goto error" button, as well as color-coded Console text, it should be more than adequate for most situations.
Console is the focal point when it comes to debugging the scripts. The kinds of errors you might encounter can be split-up into two groups: compile-time, and run-time errors. In addition to errors, Console also notifies user of non-critical "warnings" which affect a particular functionality, but do not hinder the overall performance.
4.4.1 Compile Errors
Compile-time errors check for the following errors:
Is the syntax sane?
Does the event in question have all of the required parameters?
Are individual parameters sane? (i.e. is this an integer?)
Are individual parameters within allowable range?
Are the optional parameter choices sane?
Is there anything to warn the user about in terms of inconsistencies or redundant entries?
Most, if not all error messages are structured to provide you with an exact line number, as well as the type of error and its possible resolution. Furthermore, if a particular value is outside allowable range, Console should suggest possible values and/or ranges.
Most of the compile-time errors should be easily resolved with some help from this manual and by observing the Console output.
4.4.2 Run-Time Errors
Run-time errors and warnings are a bit tougher to track down since they depend on the current state of the script, values stored within the parameters and the storable variable array, as well as real-time interactive events that can dramatically affect the flow of events. Run-time errors can include:
Manipulations of variables resulting in an invalid assignment
"Toggle" commands unable to perform their function
Infinite recursions resulting from a unforeseen loop in a scriptfile, or due to network loop
Inability to read from or write to one of the sockets and/or ports
Syntax issues with modular function calls (see 4.5.6)
Network connection statuses (invalid auth disconnections)
Other
Again, all of these try to be as verbose as possible. Very few run-time errors are show-stoppers (i.e. infinite recursions). Therefore it is always valuable to scroll back through your log to see what really happened. The status LED's at the bottom of the Console should be an additional helper where user can easily monitor event activity, as well as see whether the Console contains any warnings or errors since the last purge (see bottom-right 2 LED's on the Console window).
Beyond that, it is rather hard to give any specific advice. Like any other debugging session, it can be a rather tedious process. But, look at it from a brighter side, when you finally figure it out, you will feel a great sense of accomplishment :-).
4.5 Advanced
Topics included below are considered to be advanced primarily due to fact that covering their scope in enough detail would produce too much clutter in the event-listings, and perhaps in some cases are not something that everyone will want to use.
4.5.1 Networking
Apart from the straightforward events setnet (4.3.19) and togglenet (4.3.20), networking offers a great deal of flexibility when it comes to routing of the information.
Events that have the [>net] value set to -1 - 255 are sent over the network. "-1" value implies global event that is sent to every existing external connection as well as interpreted locally. All other values (0-255) refer to the specific networked connection.
What is important to understand is that every time transport control is pressed, this event is emanated globally (equiv. to the parameter value of "-1"). Other events, that have the ability to be networked have to be explicitly defined as such. All networked events with the value of "-2" will be interpreted strictly locally.
All events that are emanated globally are received by individual clients with the [>net] value altered to "-2" (even if their originating value was different, such as it is in this example, where original value was "-1"). This way the event will be only interpreted locally. This is to ensure avoidance of infinite recursions. Let's look at the following example in order to explain the issue of recursion:
Let's say we have 2 clients, A and B, which are inter-connected. A is the master of the B, while B is the master to the A. In order to recreate this situation, we can use two examples from the tutorials:
../network-examples/event-master.rmx
../network-examples/event-master-two-way-connection.rmx
We can spawn two instances of RTMix and compile one of the scripts in each instance. Upon compiling, we can connect the two clients by enabling connections on the network tab. By doing this, we have now crated a unique symbiotic relationship between the two instances of RTMix where both clients are both slaves and masters to each other. Needless to say this kind of an arrangement can offer a great setting for an improv session. On the other hand, if an event were to be allowed to propagate itself in such a setting, it would be easy for a global event to continuously jump back and forth between the two clients, thus creating an infinite spawn recursion. While there is a mechanism that filters such recursions in respect to the transport controls, events are simply impossible to track down due to their ability to be spawning at a great density. Furthermore, a recursive behavior of any kind of event is simply not desirable since it can be extremely hard to coordinate from the artistic standpoint.
It is also theoretically possible to connect the client to itself, although such an action yields no benefit over locally spawned events.
4.5.2 Accelerators and Custom Parameters
Accelerators are external real-time triggers of events that do not depend on a timeline, but are simply modular. There are two fundamental types of accelerators:
Keyboard keys (including complex combinations) -- this category can be further subdivided into key "presses" and key "releases"
MIDI events that can be limited in range and scope
Keyboard events require the following syntax:
Key presses use simple letters and/or signs from the keyboard i.e. "s" or "S". NOTE: Only single letters/keys are acceptable choices. No special keys or key-combinations can be used, other than using SHIFT+key in order to get capital letters and/or signs corresponding to SHIFT+number (i.e. "!" ).
Key releases are practically identical to the key presses, with one exception, and that is that they are preceded by the "^" sign, for instance "^s" or "^S".
MIDI accelerators are a bit more elaborate. They require 6 parameters. The syntax for the MIDI accelerator is as follows:
"midi: low_status (0-255, MIDI standard utilizes only 128-255), high_status (0-255, MIDI standard utilizes only 128-255), low_data1 (0-255, MIDI standard utilizes only 0-127), high_data1 (0-255, MIDI standard utilizes only 0-127), low_data2 (-1-255, MIDI standard utilizes only 0-127), high_data2 (-1-255, MIDI standard utilizes only 0-127)"
The reason for the the last data2 range allowing for -1 values is because some MIDI messages do not require the second data byte. This way you will ensure that messages that do not require the second data can still trigger the event.
An example of a MIDI accelerator would therefore look like this:
[>accel]={"midi: 128, 255, 0, 127, -1, 127"}
This kind of accelerator would be therefore susceptible to any kind of MIDI data received from the designated MIDI port. This is very useful for MIDI routing (see 4.5.5).
It is also possible to limit the range of acceptable values which can make this kind of accelerator more useful. For instance in order to limit accelerator only to note-on messages on the channel 1, one could say:
[>accel]={"midi: 144, 144, 0, 127, 0, 127"}
By now, it is obvious that RTMix utilizes MIDI on a rather low-level. Therefore one needs to be familiar with the MIDI protocol in order to be able to harness its power. One way to learn more about the MIDI protocol is to use RTMix's MIDI Logging capability (see 3.4.3), or by looking into some additional MIDI documentation (see 7.4).
IMPORTANT: RTMix's built-in protocol ignores any MIDI events that are hardware-specific (namely anything that utilizes status bytes of values greater than 0xEF, or in decimal terms greater than 239). Subsequently, such MIDI events cannot be routed either via OSC protocol (see 4.5.5).
IMPORTANT: both types of accelerators work no matter which of the RTMix's windows is focused. However, if none of the RTMix's widgets are focused, no keyboard events will be registered, while MIDI events will continue to be registered. This is simply due to fact that for any application under X-windows to receive keyboard events, it needs to be focused (i.e. currently selected and/or activated).
4.5.3 Custom Routing and Behavior of Visuals
Visuals play an important role in RTMix since they are the main means of conveying information to the performer while providing minimal amounts of distractions. While most events do not have any visual counterparts attached to them by default, almost all events can have custom visual behaviors assigned to them. This is done using optional visuals parameters [>light], [>lightlength], [>dur], [>preplength], and [>blinkspeed].
[>light] parameter specifies which LED, or group of LED's will be targeted, which will further dictate how the visuals will manifest themselves. The following are valid values:
0 -- all visuals are off.
1 -- use GREEN (a.k.a. "execute") LED on the Main window. [>lightlength] specifies in this case how long the light will be lit up before going back off. NOTE: if there is also [>blinkspeed] present than this will imply a blinking behavior, therefore making this parameter be interpreted as if it were [>light] = 2 (see below).
2 -- use YELLOW (a.k.a. "warning") LED on the Main window. [>lightlength] specifies the duration of the blinking, while the [>blinkspeed] specifies the speed of blinking (0.1secs - 10.00secs).
3 -- countdown event-like behavior where Main window's YELLOW (a.k.a. "warning") LED is lit up for the duration of the [>dur] variable, begins blinking when it reaches last [>preplength] amount of seconds before the end of countdown, at which point it begins blinking at the [>blinkspeed] rate, and at the end of the countdown turns off the YELLOW LED and lights-up the GREEN (a.k.a. "execute") LED for the duration of the [>lightlength]. NOTE: if the [>blinkspeed] or [>preplength] are absent, then there is no blinking preceding the end of countdown.
4-7 -- refer to the 4 Warning windows' LED visuals (see 3.6.3). These visuals, just like the LED window visuals are three-level visuals, meaning that they support three different states: OFF, WARN, and ON. Their behavior is based on the amount of information provided. For instance: having [>lightlength] only will make them behave like value "1", [>lightlength] in combination with [>blinkspeed] like "2", and with the addition of [>dur] as "3" (with or without blinking depending on [>preplength]).
8-13 -- refer to the 6 LED visuals found on the LED window (see 3.6.5). Their behavior is identical to the Warning windows visuals.
4.5.4 MIDI Utilization
MIDI as a real-time trigger has already been covered in the subchapter 4.5.2, so here we'll focus on MIDI utilization as an event. MIDI can be also posted as an parameter in the event call. It can be included in two forms:
MIDI values at the time of triggering
can be included into the event by substituting the variables with their
respective values (NOTE: you must have a MIDI accelerator associated with this
particular event). For instance an event's [>do]
parameter:
cmixplay
my_soundmidi[0].wav
invoked by the
MIDI note-on event with values 144, 56, 30 (status byte describing note-on on
the 1st channel, 56 standing for pitch, and 30 being its velocity) would
result in a following sys-call:
cmixplay my_sound144.wav
Any of the three values can be included by simply
specifying the correct parameter and they can be included as many times as
desired. The three values can be accessed by specifying:
midi[0] (144),
midi[1] (56), or midi[3] (30)
Therefore a event:
cmixplay midi[0]midi[1]midi[2].wav
would result in a system call:
cmixplay 1445630.wav
MIDI can be also used for output to
other MIDI devices. In this case, MIDI accelerator can, but does not have to
be the trigger (as a matter of fact, the event does not even have to be
real-time):
[>do]={"midisend: 144,
64, 76, 144, 61, 76, 144, 57, 76"}
This will produce a major triad on a synthesizer
connected to the RTMix. There are three note-on's (144) described here with
three different pitches (64, 61, and 57) and same velocities (76). Due to fact
that the MIDI protocol is linear, these values are fed to the raw-midi port
(selectable in the settings menu -- see 3.5.4) one
after the other. But this is done so quickly and efficiently that there is no
"broken chord" perceived.
MIDI events of this kind can be used in
combination with the first type (in which case they need to be
real-time):
[>do]={"midisend: 144,
midi[0], 76, 144... etc. ad infinitum"}
The number of the events is by no means limited,
and one could theoretically send a huge array of events. However, they would
be all timed synchronously.
4.5.5 OSC Utilization
OSC (Open Sound Control) protocol (see7.4) is utilized by RTMix in order to be able to communicate with the runaway processes spawned via sys-calls. Currently this protocol seems to be (in author's humble opinion) the most promising successor to the aging MIDI protocol. OSC in RTMix can be only utilized as a part of the [>do] parameter. There are three types of OSC events:
OSC router which must be associated
with a MIDI accelerator, routing incoming information via local (or remote)
socket to another application, hence enabling polling of the MIDI resources
between different applications. The only catch is that the receiving
application must support the OSC protocol (currently there is already 20+
applications supporting this protocol, and the number is steadily growing
see7.4 for
more info). MIDI events are sent in the standardized format:
MIDI EVENT | # PARAMS. | STATUS RANGE | OSC INTERPRETATION |
note-off | 3 | 0x80-0x8F | /midi/<channel-number>/noteoff <pitch> <velocity> |
note-on | 3 | 0x90-0x9F | /midi/<channel-number>/noteon <pitch>
<velocity> (NOTE: if velocity=0, then it is interpreted as a noteoff) |
poly aftertouch | 3 | 0xA0-0xAF | /midi/<channel-number>/polyaftertouch <data1> <data2> |
control | 3 | 0xB0-0xBF | /midi/<channel-number>/control <data1> <data2> |
program | 2 | 0xC0-0xCF | /midi/<channel-number>/program <data1> |
aftertouch | 2 | 0xD0-0xDF | /midi/<channel-number>/aftertouch <data1> |
pitchbend | 3 | 0xE0-0xEF | /midi/<channel-number>/pitchbend <data1> <data2> |
The syntax of an event looks as
follows:
[>do]={"oscroute: <host>,
<port>, <typetags>"}
This syntax needs to be associated
with the MIDI accelerator with a specific range. "Typetags" is a boolean
variable that determines whether the OSC packets will have typetags included
that describe the type of data being sent. For more info on typetags see7.4.
OSC event which is a single specified
instance of a MIDI message that can have up to 2 data members in addition to
the initial hierarchical description of the event (commonly referred to as
"address"). This is simply a singular trigger of some sorts. An example syntax
would be:
[>do]={"osc: <host>,
<port>, <typetags>, <address>, <data1>,
<data2>"}
For
instance:
[>do]={"osc: localhost,
9999, 1, /midi/foo/bar, 12423, -1"}
Notice that this introduces some more flexibility
than the previous model since now you can have more abstract adresses, and by
substituting MIDI data into the call (using midi[0]), you can still use it as
a MIDI router of a limited scope. Another flexibility is that now your values
(although still having to be numeric), can go beyond the 255 limit, but must
still adhere to the -1 rule.
OSC CUSTOM event where a series of OSC
events can be sent in a bundle and can have any kinds and numbers of
parameters:
[>do]={"osccustom:
<host>, <port>, <typetags>, <message1-with-parameters>
| <message2-with-parameters> | etc."}
For instance:
[>do]={"osccustom: localhost, 9999, 1, /foo/bar 22 a 3.3
| /midi/noteon/ch1 244 111 234 1 -232223.24"}
As you can see, the last instance is the least
limiting one. It provides for simlutaneous sending of various OSC data in a
single bundle that is received simultaneously. Furthermore, parameters can now
take on integers, float-point numbers, as well as "string"
values.
4.5.6 Variables, Functions, and Substitutions
Numeric variables in RTMix, both integers and float-point, can be stored and manipulated in order to modify sys-call events, as well as MIDI and OSC events or many other parameters of other events. For this purpose you can use events assign (4.3.17), seed (4.3.13), randomize (4.3.11), and change (4.3.12).
The easiest example of manipulating variables can be found in the explanations of the events listed above. Furthermore, let's observe several examples:
v[<num>] variables always refer to the stored float-point or integer values (0-255). These can be substituted in:
[>say] parameters in order to post them on the Notification interface.
[>do] parameters in order to alter behavior of sys-calls, MIDI, and OSC events.
[>func] parameters (change event-specific) where they can be used as a part of a normal mathematical function.
midi[<num>] (0-2) can be used in association with the real-time events utilizing MIDI accelerators (see4.5.2). They behave the same like the v[<num>] substitutions, but can be only used within:
[>do] parameters
[>func] parameters
Assign (4.3.17), randomize (4.3.11), and change (4.3.12) events can be used to manipulate stored values (all 256 are 0 by default). See these events' documentation for more info.
4.5.7 Color-coding the Text for the Notification Interface
Text destined for the Notification interface can be color-coded using HTML-compatible tags. All text posted on the Notification interface will fade into grey and eventually black as it is pushed away by the new incoming text. This is done in order to preserve legibility by having the new text always show up at the top of the Notification widget. However, the new text will retain its custom color until pushed away. An example of such color-coding would be:
[>say]={"<font color="#FF0000">This is red text...</font>"}
The color is done the same like in HTML where the six-digit number denotes hexadecimal values of the RGB (red, green, blue) elements in the color. Hence FF0000 would be red=255, green=0, blue=0, while 00FF00 would be green, etc.
4.5.8 Absolute vs. Relative Events
Absolute events (ones with the optional [>absat] parameter being equal to 1, if applicable) simply occur when the ABSOLUTE TIMER (see 3.6.2) reaches the desired timing specified by the [>at] value (NOTE: real-time values cannot have [>absat] value equal to 1, since they do not depend on either timer). This is because events like pause (4.3.5), stop (4.3.6), checkpoint (4.3.4), jump, (4.3.10), rew (4.3.14), and ffw (4.3.15) can affect the flow of the Main timer therefore hindering its ability to show absolute time since the beginning of the performance. This way, with the existence of the absolute-timed events, one can easily adjust the absolute ending of a particular improvised section (i.e. cadenza) or something similar.
The general notion is that the absolute events only talk nice to other absolute events (i.e. absolute "change" call will not affect the next event in the cue, but rather, next absolute event, if such an event exists, therefore potentially skipping over some other events). However, this is not valid for the following events:
"Jump", "ffw", and "rew" events with an enabled [>absat] parameter cannot jump to absolute checkpoints, but only to relative ones (even though the absolute checkpoints may exist). This is due to fact that the Main timer is unable to backtrack or fast-forward itself accurately, since its leaps and skips might be affected by a wide array of real-time and other non-real-time events. Hence, absolute versions of the aforementioned three events will occur according to the absolute timer, but will still only search for the non-real-time checkpoints.
4.5.9 Dealing With Event Probabilities
Event probabilities depend on the built-in, ever-present, yet optionally modifiable two parameters: [>happen] and [>chance]. Both parameters take in float-point values ranging between 0 and 1 (0 and 100% -- hence 0.50 would be 50%).
[>chance] parameter, by default 1 (or 100%) determines what is the chance of a particular event to occur. If at 100%, the only time it will not occur is if the [>happen] value is 0 (or 0%).
[>happen] parameter is the value the should be considered the one to be freely modified during performance, since it is compared every time to the [>chance] command, and if it is less than the 1-[>chance], then the event will not occur.
If the [>chance] parameter is 0 (0%), then no matter what is the [>happen] amount, the event will never happen. To make this a bit clearer, think of it this way:
If a chance of happening is 75% (0.75), then lets subtract this number from 1. We get 0.25. This means as long as the [>happen] value is >=0.25 (up to 1), which is the 75% of the range, the event will occur.
Obviously for such modular probabilities, one must use "change" event (see 4.3.12) in order to alter [>happen] (and/or [>chance]) parameter(s) at run-time. See "chance" tutorials for more info.
4.5.10 Issues with Audio Signal Polling
While RTMix solves many of the limitations imposed by using any single audio application, there are still a few issues that are beyond RTMix's control. One, perhaps the most important one for the Linux audio world is the lack of widespread audio-signal-polling (a.k.a. ability to have two applications both output audio together). The issue has become even more convoluted with the recent (and rather welcome) phasing out of the OSS framework and introduction of the ALSA kernel drivers. In the recent years this problem has been addressed in various ways (and with varying amounts of success), but the recent developments have provided the Linux audio community with a couple of promising solutions. They are listed in the order of their quality (in author's humble opinion):
JACK (http://jackit.sf.net/) audio super-lowlatency server that offers inter-app audio routing. It is the most promising project of this kind and is (again, in author's humble opinion) becoming the standard. How-to for this server can be found on its website.
ALSA (http://www.alsa-project.org/) project's dmix and snoop sound polling servers (dmix for output, and snoop for input). Sparse info on these servers can be found on the alsa-devel and alsa-user mailing lists (linked from their main site).
ARTSD (http://www.kde.org/) KDE's sound daemon.
Generally has not-so-good latency, but works rather well and is simple to
implement. As of right now, this one appears to be the easiest to utilize, at
least as far as the audio output is concerned. Artsd can be simply utilized in
the sys-calls by preceeding your event with the "artsdsp" command. Therefore a
sys-call:
cmixplay
my_sound.aiff
would
become:
artsdsp cmixplay
my_sound.aiff
This way multiple
playback streams become available, whose number is only limited by your cpu's
processing capability. This approach should work with both OSS and ALSA apps,
although due to various implementations of audio engines, your mileage may
vary.
Audio input polling on the other hand is still a bit flaky and I have not come across a full-proof way of polling audio input that will work consistently with older OSS-base applications and the new ALSA-based ones.
That being said, it seems that this problem will very soon become a non-issue since more and more applications are being ported to the JACK architecture, and once ALSA's dmix and snoop sound servers mature (my prognosis would be by the mid-to-late 2003), this chapter will lose its purpose :-).
<< | table of contents | >>