Migration Guides
A migration guide explains how to adapt scripts written for one version of the language to the next. ORIX Script 1.0 is the first version, so there is no earlier version to migrate from, and no script needs to be converted. This chapter exists so that future guides have a place, and to document the one difference between the released language and its original design sketch.
From the design sketch to 1.0: variables must be declared
The difference
The first sketch of the language, written before the compiler existed, showed a variable being created by a plain assignment:
automation "Eight Bar Transition" {
tempo = master.bpm
over 8 bars {
deck.A.volume -> -60dB
deck.B.volume -> 0dB
}
}In ORIX Script 1.0 this is an error:
'tempo' is not declared. Declare it first: let tempo = … (or 'var' if it changes). [E-UNDECLARED]A variable must be introduced with let (a value that never changes) or var (a value that can be assigned again):
automation "Eight Bar Transition" {
let tempo = master.bpm
over 8 bars {
deck.A.volume -> -60dB
deck.B.volume -> 0dB
}
print("started at", tempo, "BPM")
}Why
A script is meant to run in front of an audience, unattended. If an assignment could create a variable, a typing mistake in a name would never be reported: the script would quietly create a second variable and carry on with the wrong value.
Consider a counter that decides when to stop:
var turns = 0
repeat 8 {
turn = turns + 1 // typo: 'turn' instead of 'turns'
wait 1 beat
}With implicit variables this would run without complaint, turns would stay at 0 for ever, and whatever depended on it would misbehave on stage. With explicit declarations the compiler refuses the script before it runs and says exactly what is wrong:
'turn' is not declared. Declare it first: let turn = … (or 'var' if it changes). [E-UNDECLARED]Two more benefits follow from the same rule:
letdocuments and enforces that a value is fixed. Assigning to it is the errorE-CONST.- The type of a variable is fixed at its declaration, so later assignments can be checked (
E-TYPE).
How to adapt a script
For each name that is assigned without having been declared:
- Find its first assignment.
- Put
letin front of it if the name is never assigned again,varif it is. - If the first assignment is inside a block (
if, a loop) but the name is used outside, move the declaration before the block with an initial value.
| Sketch | ORIX Script 1.0 |
|---|---|
tempo = master.bpm |
let tempo = master.bpm |
count = 0 … count = count + 1 |
var count = 0 … count = count + 1 |
level = deck.A.volume (read once, used later) |
let level = deck.A.volume |
automation "Adapted" {
var count = 0
let level = deck.A.volume
repeat 4 {
count = count + 1
wait 1 beat
}
print(count, level)
}The compiler lists every undeclared name with its line, so the adaptation is mechanical: fix the reported lines until the script compiles.
A related point in the same sketch: at bar 8 after over 8 bars
The sketch ended its transition like this:
automation "Sketch Ending" {
over 8 bars {
deck.A.volume -> -60dB
}
at bar 8 {
deck.A.pause()
}
deck.A.volume = 0dB
}This compiles in 1.0, and it is worth understanding what it does. Bar 8 begins 28 beats in; when the cursor reaches the at statement, after the 32 beats of the ramp, that position is already 4 beats in the past. The block therefore runs immediately, with a warning in the log. The result is what the author wanted, by accident. The clear way to write it is to put the statements after the ramp:
automation "Clear Ending" {
over 8 bars {
deck.A.volume -> -60dB
}
deck.A.pause()
deck.A.volume = 0dB
}This is not a change of the language, only a reminder that at positions count from the start of the automation and from 1. See Beats and Bars.
Scripts from other applications
ORIX Script is not compatible with the scripting or mapping formats of other DJ software, and there is no importer for them. A routine from elsewhere has to be rewritten. The concepts usually map directly: a control change becomes path = value, a timed move becomes over, a quantized action becomes wait nextBar followed by the action. Claude Studio can help with the rewrite; its output is compiled and simulated like any other script.
Future versions
When a new version of the language is released, this chapter will gain one section per version, each with:
- the list of changes that affect existing scripts;
- for each change, a before and after example and the diagnostic that the new compiler reports for the old form;
- what happens to scripts stored in projects saved with the previous version.
Until then, the state of things is simple: every script that compiles with your copy of ORIX DJ is a 1.0 script. See Version Compatibility for what is recorded in projects and exported files.