SPB Git

Repository Public

types.md 8.6 KB

# Types

Every value in ORIX Script has a type, and the type says what kind of quantity it is: a level, a frequency, a length of time, a plain number. The compiler uses types to stop the classic mistakes before the script runs: sending hertz to a fader, adding beats to decibels, waiting "4" without saying four of what.

# The types

Type What it is Written as Used for
number A plain number 4, 0.35, 50%, 128bpm Knob positions (0…1), counts, tempo, semitones
gain A level in decibels -12dB, 0dB Faders, EQ bands, trim, thresholds
frequency A frequency in hertz 80Hz, 12kHz Filter corners, LFO speeds
duration A length of time 4 beats, 1/2beat, 2 bars, 250ms, 2s Waits, ramps, positions, delay times, loop lengths
bool Yes or no true, false Switches, conditions
string Text "smooth" Crossfader curve, track titles, messages
deck One of the four decks deck.A … deck.D Passing a deck to a function, choosing a deck
[type] An array [1, 2, 3], [-6dB, -12dB] Patterns, lists of steps

Each parameter in the reference chapters has one of these types. deck.A.volume is a gain; deck.A.filter.highpass is a frequency; fx.delay.time is a duration; mixer.crossfader is a number.

# Two kinds of duration

A duration is either musical or absolute, and it remembers which.

  • Musical: beats and bars. 4 beats is always four beats, whatever the tempo.
  • Absolute: milliseconds, seconds and minutes. 2s is two seconds; how many beats that is depends on the tempo at the moment it is used.

Both can be used wherever a duration is expected. See Timing for how seconds are converted.

# No silent conversion

A value of one type is never turned into another type behind your back.

orixdj-error
deck.A.filter.highpass = 500
text
'deck.A.filter.highpass' expects frequency, not number. Write a frequency such as 800Hz or 12kHz. [E-TYPE]
orixdj-error
deck.A.volume = 20Hz
text
'deck.A.volume' expects gain, not frequency. Write a gain such as -6dB. [E-TYPE]

There is exactly one exception, made for faders.

# The fader exception: a number given to a gain parameter

When a plain number or a percentage is assigned (or ramped) to a parameter of type gain, it is taken as a linear level, the way a fader position is often described: 1 or 100% is 0 dB, 0.5 or 50% is about -6 dB, 0 is silence.

orixdj
deck.A.volume = 50%        // about -6 dB
deck.B.volume = 0          // silence (-60 dB)
wait 1 bar
deck.A.volume = 100%       // 0 dB
Linear Decibels
0 (up to 0.001) -60 dB (silence)
0.25 about -12 dB
0.5 about -6 dB
1 0 dB
2 about +6 dB

The linear value must be between 0 and 4, and the resulting level must still be within the range of the parameter. This conversion applies only when writing to a gain parameter; a variable declared with a number stays a number.

# Operators and types

# Arithmetic

Expression Result Example
number + number, number - number number 3 + 4
gain + gain, gain - gain gain -6dB - 3dB is -9 dB
frequency + frequency, frequency - frequency frequency 200Hz + 50Hz
duration + duration, duration - duration duration 4 bars + 2 beats is 18 beats
string + string string "deck " + "A"
number * number number
duration * number, number * duration duration 2 * 4 beats
gain * number, frequency * number (either order) gain, frequency 200Hz * 2
number / number number
duration / number, gain / number, frequency / number same as the left side 8 bars / 2 is 16 beats
duration / duration number 8 bars / 1 bar is 8
frequency / frequency number 400Hz / 200Hz is 2
number % number number remainder: 7 % 4 is 3
-x same as x number, gain, frequency or duration

Anything else is a type error. The message tells you which unit is missing.

orixdj-error
let louder = deck.A.volume + 3
text
Operator '+' cannot combine gain and number. Add the unit: 3dB. [E-TYPE]

Adding a musical and an absolute duration is allowed; the result is in beats, computed with the tempo at the moment the expression is evaluated.

orixdj
let lead = 1 bar + 500ms
print(lead)

Dividing by zero, or any arithmetic whose result is not a finite number, is the error E-MATH.

# Comparison

<, <=, >, >= compare two values of the same type among number, gain, frequency and duration. == and != compare two values of the same type, including bool, string and deck, but not arrays.

orixdj
if deck.A.remaining < 30s { print("deck A is ending") }
if deck.B.bpm > deck.A.bpm { print("deck B is faster") }
if master.deck == "A" { print("deck A drives the clock") }
if deck.A.level > -3dB { print("deck A is hot") }

Durations of different kinds are compared after conversion to beats with the current tempo.

# Logic

and, or, not (also written &&, ||, !) work on bool values only. See Conditions.

# Builtin functions

Function Result What it does
min(a, b), max(a, b) type of a Smaller, larger of two values of the same numeric type
clamp(x, low, high) type of x x limited to low…high
abs(x), round(x), floor(x), ceil(x) number On numbers
lerp(a, b, t) type of a The point a fraction t of the way from a to b
random() number A number from 0 to 1; the same sequence on every run of an automation
len(a) number Number of elements of an array, or of characters of a string
db(x) gain A gain of x decibels
hz(x) frequency A frequency of x hertz
beats(x), bars(x) duration A musical duration
seconds(x) duration An absolute duration
toBeats(d), toSeconds(d) number Length of a duration at the current tempo
toNumber(x) number The decibels of a gain or the hertz of a frequency, as a plain number
print(values…) – Writes the values to the automation log

"Numeric type" means number, gain, frequency or duration.

# Making a typed value from a computed number

Use the constructor functions when the number is calculated rather than written.

orixdj
for step in 1...4 {
    deck.A.eq.high = db(-3 * step)        // -3, -6, -9, -12 dB
    deck.A.filter.highpass = hz(100 * step)
    wait beats(step / 2)
}
deck.A.eq.high = 0dB
deck.A.filter.highpass = 20Hz

# Getting a number out of a typed value

orixdj
let level = toNumber(deck.A.volume)      // decibels as a number
let beatsLeft = toBeats(deck.A.remaining)
let barsLeft = floor(beatsLeft / 4)
print(level, barsLeft)

# Blending two values

orixdj
let dark = 400Hz
let bright = 8kHz
deck.A.filter.lowpass = lerp(dark, bright, 0.5)
wait 1 bar
deck.A.filter.lowpass = 20kHz

lerp is linear: halfway between 400 Hz and 8 kHz is 4.2 kHz. (Ramps written with -> treat frequencies differently; see Timing.)

# Arrays

All the elements of an array have the same type, which gives the array its type: [1, 2] is a [number], [1/4beat, 1/8beat] is a [duration].

orixdj-error
let mixed = [1, 2dB]
text
All elements of an array must have the same type (number and gain found). [E-TYPE]

An empty array [] is not allowed because its element type would be unknown.

# The deck type

deck.A on its own is a value of type deck. Stored in a variable or passed to a function, it can be used wherever deck.X can.

orixdj
let incoming = deck.B
incoming.volume = -12dB
incoming.play()
over 2 bars { incoming.volume -> 0dB }
print(incoming == deck.B)        // true

# Values that are clamped at run time

When the compiler can see the value (a literal or a constant expression), a value outside the range of a parameter is an error (E-RANGE). When the value is only known while the script runs, it is limited to the range of the parameter instead, and the run statistics count it as a clamped value.

orixdj
let wild = deck.A.bpm / 100      // 1.28 at 128 BPM
mixer.crossfader = wild          // set to 1, the top of the range
wait 1 beat
mixer.crossfader = 0.5

The simulator and the debugger report the number of clamped values; a script that clamps is usually computing something wrong.

Files main
Menu

Theme