SPB Git

Repository Public

migration.md 5.4 KB

# 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:

orixdj-error
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:

text
'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):

orixdj
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:

orixdj-error
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:

text
'turn' is not declared. Declare it first: let turn = …  (or 'var' if it changes). [E-UNDECLARED]

Two more benefits follow from the same rule:

  • let documents and enforces that a value is fixed. Assigning to it is the error E-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:

  1. Find its first assignment.
  2. Put let in front of it if the name is never assigned again, var if it is.
  3. 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
orixdj
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.

The sketch ended its transition like this:

orixdj
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:

orixdj
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.

Files main
Menu

Theme