Mobius Scripting

Normally scripts are loaded once when Mobius is first started and remain in memory for as long as Mobius runs. If you make changes to the script file they will not be used by Mobius until you shut it down and restart it.

The !autoload declation will cause the script file to be reloaded from the file system every time the script is called. This is very useful when writing new scripts, it allows you to keep Mobius running while you make changes the script.

After the script is working properly you should remove this declaration. Realoading the script takes time. If you are trying to call the script at precice locations in the loop, the reload will delay the running of the script slightly.

This option identifies the script as a controller script. When the script is triggered by a MIDI continuous controller, the script is called whenever the value of the controller changes.

Normally, when a script is bound to a MIDI continuous controller, it is assumed that the controller events are being sent by a momentary switch rather than an expression pedal. Momentary switches typically send a non-zero controller value when the switch is pressed and a zero value when the switch is released. Mobius will only call the script when it receives a non-zero value which means the switch has been pressed. It will not call the script when it receives a zero value after the switch is released, unless you also use the !sustain declaration.

This behavior is usually not desired when the continuous controller values are being generated by an expression pedal. With an expression pedal, you want the script called whenever the position of the pedal changes, even when it goes to zero.

Controller scripts are most often used to change the track controls:

• Input Level
• Output Level
• Feedback
• Secondary Feedback
• Pan

They may also be used to change rate and pitch shift for each track, and change preset paramters such as 8ths Per Cycle.

Including the !controller declaration in a script will disable the following directives if they also appear in the script.

• !quantize
• !switchQuantize
• !sustain
• !multiclick
• !spread

Here is an example script that implements a basic volume control. The behavior of this scipt is exactly the same as binding a controller to the Output Level control.

  !name Output Level
  !controller
  set outut midiValue

The !controller declaration tells Mobius that this script should be called every time the value of the trigger changes. The word midiValue is a reference to a system variable that will contain the value of the continuous controller that triggered this script. The value will be from 0 to 127.

Here is a more interesting example that sets the output level to the inverse of the controller value. When the controller value is zero (toe up) the output level will be 127, when the controller value is 127 (toe down) the output level will be zero.

  !name Backwards Output Level
  !controller
  set output 127 - midiValue

If you are familar with the EDP, controller scripts give you the ability to implement "flip mode" as well as many other combinations of Mobius controls that change in response to a single expression pedal.

Normally scripts do not obey focus lock or track groups. When a script is run it will only run in the selected track.

The !focuslock declaration makes the script sensitive to track focus lock and track groups. The script will be run simultaneously in all focused locked tracks, and all tracks in the same track group as the selected track.

This option is useful for simple scripts that only operate on one track. It makes the script behave more like the built-in Mobius functions. If however the script uses the for statement to operate on several tracks, you normally never use the !focuslock option.

This option allows the script to change behavior if you trigger it more than once within a short time. Some people think of this as "double clicking". A script that uses this option is called a multi-click script.

To create a multi-click script, add this declaration:

  !multiclick 2000

The numeric argument is the trigger expiration period expressed as a number of milliseconds. The default expiration period is 1000 (1 second) so you only need to include this argument if you want a value other than 1000. In this example the expiration period will be two seconds.

Next add Label statements to the script with these names:

• click - run whenever the script is triggered again before the expiration period
• endClick - run when the trigger expiration period is reached

As always this is best described with an example:

  !name Multiclick Test

  # the default value is 1000 milliseconds, override to 2 seconds
  !multiclick 2000

  Message Starting Click Test
  end

  Label click
  Message Click $clickCount
  end

  Label endClick
  Message Ending Click Test
  end

When you trigger the script for the first time, the message "Starting Click Test" is displayed. If you trigger the script again within 2 seconds, a message is displayed showing the number of triggers that have been received from the system variable clickCount. If you wait 2 seconds without triggering the script again, the "Ending Click Test" message is displayed and the script is finished.

Each time the script is triggered, the expiration period starts over at 2 seconds.

GEEK Note: As with sustain scripts, the click and endClick labels are called in different threads so the script may be active in more than one thread. Variables can be used for communication between threads.

This declaration is used to specify the name to be displayed for this script in the binding windows. If no name is specified, the file name is displayed. It is very common to use a !name declaration since the script file name is not always meaningful to the user.

The name consists of all characters after the space after the !name declaration up to the end of the line. In the following example, the name displayed for the script would be "Auto Record 4".

  !name Auto Record 4

Like all declarations, !name may appear anywhere in the file but it is usually the first line to make it easier to see.

Normally scripts will not obey the quantize parameter in the preset. When a script is triggered it will be run immeidately.

The !quantize option makes the script sensitive to the quantize parameter, it will be run at the next quantization point. This makes scripts behave more like built-in functions.

This option is most often used when the script does not begin with a Wait statement.

This option will allow the script to be triggered by a range of MIDI note, controller, or program events. The script is bound once to the center of the range, but will then be triggered by events on either side of the center.

This option is usually used when binding to MIDI note events. If the script is bound to middle C, then notes on either side of middle C will automatically be bound to the script. This is similar to the way the Pitch Shift and Rate Shift functions behave. The note you select in the Binding window is the center note, pressing notes below the center lowers the pitch/rate, pressing notes above the center raises the pitch/rate.

For spread scripts, the script will be run when any note in the range is pressed. The script can then reference internal variables to determine which note within the range was pressed.

While it will be most common to bind spread scripts to MIDI notes so that you can "play" the script chromatically, you can also bind the script to a range of program changes or continuous controller values.

To define a spread script, include this declaration at the top:

  !spread

The default range of the spread is 48 values on either side of the center, which for notes means 4 octaves up and 4 octaves down. You can reduce this range by adding an argument to the !spread declaration:

  !spread 4

In the previous example, the 4 argument means that the spread will be 4 notes on either side of the center.

If there is a conflict between a spread script binding and another function that is bound to a specific note, the other function will have priority. For example, if a spread script with a range of 12 is bound to note 64, the script will be called whenever notes 52 to 76 are received. If you also have the Record function bound to note 59, that note will call the Record function, but all the notes around it will still call the script. You can think of this like "holes being punched" into the spread range. You usually do not want to have a spread range conflict with another function binding so it is best to move the center notes so they do not overlap. If you want to have a large spread range, you will need to use different MIDI channels for the center notes.

When a spread script is called, the following system variables may be referenced to adjust the behavior of the script:

• triggerOffset - A positive or negative integer representing the relative position of the trigger from the center of the range.

For example, if you bind the script to note 64 and you press note 63, the value of triggerOffset will be -1. If you press note 64 triggerOffset will be 0, and if you press note 65 triggerOffset will be 1.

The built-in Rate Shift function could be implemented with this script:

  !name Script Rate Shift
  !spread 12
  RateShift triggerOffset

Spread scripts are probably most useful with the RateShift, PitchShift, LoopTrigger, and TrackSelect functions. But you could also use them to set the ouput level or 8thsPerCycle parameter.

As a more interesting example, if you always want to rate shift in octave intervals, you could use this script and you would only need to reserve 9 notes:

  !name Rate Shift Octaves
  !spread 4
  RateShift triggerOffset * 12

This option will cause the script to be run on both the down and up transitions of the trigger. A down transition happens when you press a switch, an up transition happens when you release a switch. A script that uses this option is called a sustain script. Sustain scripts are effective only if you are using a momentary trigger such as a MIDI note, MIDI continuous controller, or computer keyboard key.

To use MIDI notes, the trigger device must send a Note On event when a switch is pressed and a Note Off event when the switch is released. To use MIDI continuous controllers, the switch must send a CC value greater than zero when the switch is pressed and zero when the switch is released. Note that you can not use MIDI program changes for sustain scripts since the program change is only sent when the switch is pressed.

Sustain scripts are also run repeatedly while the switch is held down, this allows it to change behavior depending on how long the switch is held. This allows scripts to have long press behavior like other built-in functions.

To be notified when the trigger goes up, you simply add this label to the script:

  Label endSustain

The statements following this label will be run when the function trigger goes up.

To be notified while the trigger is held, add this label to the script:

  Label sustain

The statements following this label will be run every 250 milliseconds (1/4 second) while the trigger is held. You can determine how long the trigger has been held by testing the sustainCount variable. This will have a number starting at 1 and incrementing by 1 every time the sustain script is called.

You can specify the duration of the sustain notifications by adding a number after the !sustain keyword. This number is the number of milliseconds between notifications. For example, this declaration will cause the sustain label to called every second rather than every 1/4 second.

  !sustain 1000

Here is a more complex example that demonstrates all of the features of sustain scripts.

  !name Sustain Test

  # default is 250 msec, raise it to 1 sec
  !sustain 1000

  # the Message statement can be used to display brief messages
  Message Starting sustain test
  end

  Label sustain
  Message Sustained $sustainCount
  end

  Label endSustain
  Message Ending sustain test
  end

You can think of this as 3 scripts in one. From the top to the first end are the statements that are run when the switch is pressed.

The statements from Label sustain to the next end are called as the switch is held.

The statements from Label endSustain to the next end are called when the function trigger goes up.

You do not need to declare both labels, but you do need to remember to put an end before each of the sustain lables.

GEEK Note: Scripts are similar to a re-entrant function in a multi-threaded programming language. Each of the calls for the down transition, up transition, and sustain notifications are done in an environment similar to a thread. If you use Wait statements, it is possible for the script to be active in more than one thread. By using variables, the threads can communicate with each other.

Here is a more realistic example. A long-press of the Record function will normally perform a Reset. This script does something similar but with the Mute function.

  !name Mute/Reset

  Mute
  end

  Label sustain
  if sustainCount = 1
  Reset
  endif

Under the sustain label, you can test the sustainCount variable to make the script change behavior the longer the trigger is held. Some examples of this might be:

• change rate or pitch shift the longer the trigger is held
• bounce between half speed and normal speed every second as long as the trigger is held
• slip forward one subcycle every 1/2 second

Here is another example of simle sustain sccript that raises the rate a fifth while held and drops it back when released.

  !name SUSRateUp5

  RateUp 7
  end

  Label endSustain
  RateDown 7
  end

When you change loops with the switchQantize parameter set something other than off, Mobius will enter a special Switch mode while it waits for the next switch quantization point. During this mode, many functions that you trigger are queued and performed after the loop switch.

By default scripts do not wait until after the loop switch, they are run immediately. The !switchQuanitze option will delay the execution of the script until after the loop switch. This makes scripts behave more like built-in functions.

Note however that the functions performed by the script are not treated like alternate endings to the switch function. For example, if you do an Overdub during the switch quantization and the next loop is empty, the current loop is copied into the next loop. But if you run a script whos first function is Overdub, this will not cause the loop to be copied.