Variables
A variable is a name for a value: a fade length, a level to come back to, a counter. Naming a value lets you write it once and use it in several places, and lets a script remember something for later.
Declaring: let and var
Every variable must be declared before it is used.
letdeclares a name whose value never changes.vardeclares a name whose value can be changed later.
let fade = 8 bars // fixed
var hits = 0 // will change
hits = hits + 1
over fade { deck.A.volume -> -60dB }
deck.A.volume = 0dBA declaration always has an initial value. The value decides the type of the variable; it keeps that type for its whole life.
Use let unless you really need to change the value. The compiler then protects you from changing it by mistake.
Remembering a setting
The most common use of a variable in a DJ script is to remember where a control was, so that you can put it back.
let before = deck.A.volume // read the fader now
over 2 bars { deck.A.volume -> -20dB }
wait 2 bars
over 1 bar { deck.A.volume -> before }let before = deck.A.volume reads the fader once, at that moment. If the fader moves later, before does not change. To get the current value again, read the path again.
Why declarations are required
Writing tempo = master.bpm without let or var is an error:
tempo = master.bpm'tempo' is not declared. Declare it first: let tempo = … (or 'var' if it changes). [E-UNDECLARED]This is deliberate. If an assignment could create a variable silently, a typing mistake would go unnoticed: you would mean to change hits, type hist, and the script would run with a new, useless variable instead of telling you. With explicit declarations, every misspelt name is caught before the script runs. See Migration Guides.
Changing a let is an error
let level = -6dB
level = -12dB'level' was declared with 'let' and cannot change. Declare it with 'var'. [E-CONST]The type cannot change
var level = -6dB
level = 0.5Cannot assign number to 'level' of type gain. [E-TYPE]Optional type annotation
You may state the type after the name. The compiler checks that the value has that type. It is never required, but it documents the intention.
let cutoff: frequency = 800Hz
var open: bool = false
let pattern: [number] = [1, 0, 1, 1]
let target: deck = deck.B
print(cutoff, open, pattern, target)The type names are number, duration, gain, frequency, bool, string, deck, and [type] for an array.
Scope: where a name is visible
A variable is visible from its declaration to the end of the block (the pair of braces) in which it is declared, including the blocks nested inside.
let outer = 1
if deck.A.playing {
let inner = 2
print(outer + inner) // both visible here
}
print(outer) // 'inner' no longer exists hereRules:
- Two variables in the same block cannot have the same name (
E-REDECLARED). - A nested block may declare a name that already exists outside; inside that block the new variable hides the outer one.
- The variable of a
forloop exists only inside the loop and cannot be assigned. - Function parameters behave like
let: they cannot be assigned. - One automation or function can declare at most 512 variables.
Top-level constants
A let written outside any automation is a constant shared by every automation and function of the file.
let blend = 8 bars
let quiet = -18dB
automation "In" quantize bar {
deck.B.volume = quiet
deck.B.play()
over blend { deck.B.volume -> 0dB }
}
automation "Out" quantize bar {
over blend { deck.A.volume -> quiet }
}A top-level constant must be a constant expression: literals, arithmetic on them, and builtins such as bars(8). It cannot read a live value, because no automation is running when the file is loaded.
let tempo = master.bpm
automation "X" {
print(tempo)
}A top-level 'let' must be a constant expression; read live values inside an automation. [E-CONST]Only let is allowed at the top level; var is not. If a variable inside an automation has the same name as a top-level constant, the compiler warns (W-SHADOW) because the constant is hidden there.
Variables and scheduled blocks
Two statements run their block later: at and on. They treat variables differently, and the difference matters.
at takes a snapshot. A block scheduled with at sees the variables as they were at the moment the at statement ran. Later changes are not seen by the block, and changes made inside the block are not seen outside.
var level = -6dB
at bar 2 { deck.A.volume = level } // will use -6 dB
level = -12dB // does not affect the scheduled block
wait 2 bars
deck.A.volume = 0dBThis is what makes scheduling inside a loop work: each scheduled block keeps the value the loop variable had when it was scheduled.
for step in 1...4 {
at beat step * 4 { print("scheduled as number", step) }
}on shares the variables. An event handler works with the automation's own variables: it sees their current values and its changes are visible everywhere.
var barCount = 0
on bar {
barCount = barCount + 1
}
wait 8 bars
print("bars counted:", barCount)
stopArrays
An array is an ordered list of values of the same type. Elements are numbered from 0.
let cuts = [-3dB, -6dB, -12dB, -26dB]
deck.A.eq.high = cuts[0]
print(len(cuts)) // 4
for cut in cuts {
deck.A.eq.low = cut
wait 1 beat
}
deck.A.eq.low = 0dB
deck.A.eq.high = 0dBAn array has at least one element and at most 256. Arrays cannot contain arrays. An index outside the array is an error (E-RANGE), found by the compiler when the index is a constant and at run time otherwise. There is no statement to change one element; build a new array instead.
Naming advice
- Reserved words cannot be used for variables,
forloop variables or function parameters:bar,beat,deck,limit,curve,once… The full list is in Language Syntax. UsebarCount,maxTurns,shape. - Names are case-sensitive.
- Say what the value is for:
fadeLength,quietLevel,returnCutoffare easier to read on stage thanxandt2.