SPB Git

Repository Public

functions.md 8.2 KB

# 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

orixdj
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 deck is used exactly like deck.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.

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

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

orixdj
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

  • on handlers: they belong in an automation (E-EVENT).
  • A procedure cannot be called inside an over block (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.

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

Each of these is the error E-PURE.

orixdj-error
fn halfTempo() -> number {
    return deck.A.bpm / 2
}

automation "X" {
    print(halfTempo())
}
text
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:

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

orixdj-error
fn pick(x: number) -> number {
    if x > 1 {
        return x
    }
}

automation "X" {
    print(pick(2))
}
text
Function 'pick' must return a number on every path. [E-RETURN]
orixdj
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, not 0.5, to a gain parameter.
  • A parameter cannot have the name of a reserved word (E-SYNTAX): write d: deck, not deck: deck.
  • Parameters cannot be assigned inside the function. Copy one into a var if 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.
orixdj
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:

orixdj-error
fn fadeOut(d: deck, length: duration) {
    over length { d.volume -> -60dB }
}

automation "X" {
    fadeOut(deck.A)
}
text
'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.

orixdj-error
fn countdown(n: number) -> number {
    if n <= 0 { return 0 }
    return countdown(n - 1)
}

automation "X" {
    print(countdown(3))
}
text
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.

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

Files main
Menu

Theme