Functions
A function is a named piece of script that you write once and use many times. A fade that works for deck A can work for any deck if the deck becomes a parameter. A calculation used in three places can have a name.
ORIX Script has two kinds of function, and the difference is important:
| Kind | Header | May do | Used as |
|---|---|---|---|
| Procedure | fn name(…) { … } |
Everything an automation does: set controls, call actions, wait, ramp | A statement: name(…) |
| Value function | fn name(…) -> type { … } |
Only compute | An expression: let x = name(…) |
Functions are declared at the top level of the file, outside any automation, in any order.
Procedures
fn fadeOut(d: deck, length: duration) {
over length { d.volume -> -60dB }
d.pause()
d.volume = 0dB
}
automation "Fade Out A" quantize bar {
fadeOut(deck.A, 4 bars)
}- Every parameter has a name and a type:
d: deck,length: duration. - Inside the function, a parameter of type
deckis used exactly likedeck.A:d.volume,d.play(),d.fx.echo.enable(). - The call must give one argument per parameter, of the right type.
A procedure runs in the caller's time
Calling a procedure is like pasting its body at the place of the call. Its waits and ramps move the caller's cursor: the statement after the call runs when the procedure has finished.
fn dip(d: deck) {
over 2 beats { d.volume -> -12dB }
over 2 beats { d.volume -> 0dB }
}
automation "Two Dips" quantize bar {
dip(deck.A) // takes one bar
wait 1 bar
dip(deck.A) // starts two bars in
}To run a procedure without waiting for it, call it from an at block. The block has its own cursor, so the main sequence carries on.
fn fade(d: deck, level: gain, length: duration) {
over length { d.volume -> level }
}
automation "Crossing Fades" quantize bar {
deck.B.volume = -60dB
deck.B.sync(true)
deck.B.play()
at bar 1 { fade(deck.A, -60dB, 8 bars) } // both start now and run together
at bar 1 { fade(deck.B, 0dB, 4 bars) }
wait 8 bars
deck.A.pause()
deck.A.volume = 0dB
}Leaving early
return without a value leaves the procedure.
fn startIfReady(d: deck) {
if not d.loaded {
print("nothing loaded")
return
}
d.play()
}
automation "Start C" {
startIfReady(deck.C)
}stop inside a procedure stops the whole automation, not just the procedure.
What a procedure cannot contain
onhandlers: they belong in an automation (E-EVENT).- A procedure cannot be called inside an
overblock (E-OVER).
at bar N inside a function counts from the start of the automation, not from the call; the compiler reminds you with the warning W-AT. Inside a function, prefer wait to position yourself.
Value functions
A function with -> type computes a value and gives it back with return.
fn barsToBeats(count: number) -> number {
return count * 4
}
fn quieter(level: gain, steps: number) -> gain {
return max(level - 3dB * steps, -60dB)
}
automation "Compute" {
let total = barsToBeats(8)
deck.A.volume = quieter(0dB, 2) // -6 dB
print(total)
wait 1 bar
deck.A.volume = 0dB
}A value function is pure: its result depends only on its arguments. It may declare variables, use if and loops, and call builtins and other value functions. It may not:
- wait, ramp or schedule (
wait,over,at,every,on); - set a control or call an action;
- read a live value such as
deck.A.bpm: pass it as an argument instead; - call
print,random()or a procedure, or usestop.
Each of these is the error E-PURE.
fn halfTempo() -> number {
return deck.A.bpm / 2
}
automation "X" {
print(halfTempo())
}A function that returns a value cannot read live values such as 'deck.A.bpm'; pass them as arguments. [E-PURE](For this script the compiler also reports E-RETURN on the function, because the rejected return statement no longer counts as one. Fixing the first problem removes both messages.)
The corrected version reads the tempo in the automation and passes it in:
fn half(x: number) -> number {
return x / 2
}
automation "Half Tempo" {
print(half(deck.A.bpm))
}Every path must return
The compiler checks that a value function returns a value whatever happens. The last statement must be a return, or an if/else whose two branches both end with one.
fn pick(x: number) -> number {
if x > 1 {
return x
}
}
automation "X" {
print(pick(2))
}Function 'pick' must return a number on every path. [E-RETURN]fn pick(x: number) -> number {
if x > 1 {
return x
}
return 1
}
automation "Pick" {
print(pick(2), pick(0))
}The returned value must have the declared type.
Parameters and arguments
- Parameter types:
number,duration,gain,frequency,bool,string,deck, or an array type such as[gain]. - Arguments are checked strictly. The "plain number as a linear fader level" convenience applies only when assigning to a gain control, not to function arguments: pass
-6dB, not0.5, to againparameter. - A parameter cannot have the name of a reserved word (
E-SYNTAX): writed: deck, notdeck: deck. - Parameters cannot be assigned inside the function. Copy one into a
varif you need to change it. - A function has its own variables. It cannot see the variables of the automation that calls it; it can see the file's top-level constants.
let floorLevel = -60dB
fn playPattern(d: deck, levels: [gain], stepLength: duration) {
for level in levels {
d.volume = max(level, floorLevel)
wait stepLength
}
d.volume = 0dB
}
automation "Pattern" quantize bar {
playPattern(deck.A, [0dB, -60dB, -6dB, -60dB], 1/2beat)
}Wrong number or type of arguments:
fn fadeOut(d: deck, length: duration) {
over length { d.volume -> -60dB }
}
automation "X" {
fadeOut(deck.A)
}'fadeOut' takes 2 arguments, not 1. [E-ARGS]No recursion
A function cannot call itself, directly or through other functions (E-RECURSION). This is one of the rules that guarantee an automation always ends. Use a loop instead.
fn countdown(n: number) -> number {
if n <= 0 { return 0 }
return countdown(n - 1)
}
automation "X" {
print(countdown(3))
}Function 'countdown' calls itself, directly or through other functions. Recursion is not allowed: automations must be bounded. [E-RECURSION]Calls can be nested at most 16 deep.
Names
A function cannot have the name of another function, of a builtin (min, max, clamp, abs, round, floor, ceil, lerp, random, len, db, hz, beats, bars, seconds, toBeats, toSeconds, toNumber, print) or of a reserved word (E-REDECLARED).
Calling a value function, or a builtin other than print, as a statement throws its result away; the compiler warns with W-UNUSED.
A small library
Functions make a file of transitions readable. This one defines three building blocks and two automations that combine them.
let silent = -60dB
fn bringIn(d: deck, length: duration) {
d.sync(true)
d.volume = silent
d.eq.low = -26dB
d.play()
over length { d.volume -> 0dB }
}
fn swapBass(from: deck, to: deck) {
from.eq.low = -26dB
to.eq.low = 0dB
}
fn takeOut(d: deck, length: duration) {
over length { d.volume -> silent }
d.pause()
d.eq.low = 0dB
d.volume = 0dB
}
automation "A to B" quantize bar {
bringIn(deck.B, 4 bars)
swapBass(deck.A, deck.B)
takeOut(deck.A, 4 bars)
}
automation "A to C quick" quantize bar {
bringIn(deck.C, 1 bar)
swapBass(deck.A, deck.C)
takeOut(deck.A, 1 bar)
}When the length of a procedure depends on an argument, as here, the total length of the automation is not known before it runs. That only affects what the scheduler display can show.