Loops
A loop repeats a block. In a DJ script that usually means a rhythm: cut the fader on every eighth note, halve a loop every two beats, step a filter through a list of values. ORIX Script has five loop statements, and all of them are bounded: a loop always ends.
| Statement | Repeats | Typical use |
|---|---|---|
repeat N { … } |
N times | "Do this four times" |
for i in 1...8 { … } |
once per number of a range | Steps that depend on the step number |
for x in [a, b, c] { … } |
once per element of an array | A pattern of values |
every P for T { … } |
on a time grid, every P during T | Rhythmic effects |
while C limit N { … } |
while a condition is true, at most N times | Waiting for something |
repeat
repeat 4 {
deck.A.eq.high = -26dB
wait 1/2beat
deck.A.eq.high = 0dB
wait 1/2beat
}The body runs four times. Each turn takes one beat because of the two waits, so the loop takes one bar.
A loop does not take time by itself. A body without wait or over runs all its turns at the same instant.
The count may be computed. It must be a whole number, zero or more, and at most 10000.
let turns = floor(toBeats(deck.A.remaining) / 4) // whole bars left on deck A
print("bars left:", turns)
repeat min(turns, 2) {
wait 1 bar
} for over a range
a...b includes both ends; a..<b stops before b. The loop variable is a number, exists only inside the loop, and cannot be assigned.
for step in 1...4 {
deck.A.filter.highpass = hz(200 * step) // 200, 400, 600, 800 Hz
wait 1 beat
}
deck.A.filter.highpass = 20Hzfor index in 0..<4 {
print(index) // 0, 1, 2, 3
}The bounds are evaluated once, before the first turn. The variable goes up by 1 each turn; if the first bound is greater than the last, the body does not run. A range can cover at most 10000 values.
for over an array
let pattern = [0dB, -60dB, 0dB, 0dB, -60dB, 0dB, -60dB, -60dB]
for level in pattern {
deck.A.volume = level
wait 1/2beat
}
deck.A.volume = 0dBThe variable takes each element in turn and has the element's type. This is the simplest way to write a rhythmic pattern: the array is the pattern, the loop plays it.
every: a loop on a time grid
every P for T { … } runs its body at the cursor, then again P later, and so on, for a total length T. Then the cursor is T after where the loop started.
every 1 beat for 2 bars {
deck.A.eq.low = -26dB
wait 1/4beat
deck.A.eq.low = 0dB
}The body runs at beats 0, 1, 2, … 7 (eight times), and the statement after the loop runs at beat 8.
The difference with repeat: the grid of every does not depend on how long the body takes. The body above takes a quarter of a beat; the next turn still starts on the next beat. With repeat, you must make the waits of the body add up to the period yourself.
Rules:
- P and T are durations. P must be greater than zero and at least 1/64 beat.
- T divided by P can be at most 10000.
- A turn starts only if it begins before the end of T.
every 1 beat for 3.5 beatsruns at 0, 1, 2 and 3, and ends at 3.5. - If a turn is still running when the next one is due, the next one starts as soon as the body ends. The loop then finishes late: keep the body shorter than the period.
Both durations may be in seconds; they are converted with the tempo when the loop starts.
while: repeat as long as a condition holds
var level = 0dB
while level > -24dB limit 16 {
level = level - 3dB
deck.A.eq.mid = level
wait 1 beat
}
deck.A.eq.mid = 0dBThe condition is tested before each turn. limit is mandatory: it is the largest number of turns the loop is allowed to make, a constant whole number from 1 to 10000.
while deck.A.playing {
wait 1 beat
}A 'while' loop needs an iteration bound: while condition limit 64 { … }. [E-UNBOUNDED]Reaching the limit is an error, not a normal exit. If the body has run limit times and the condition is still true, the automation fails with E-UNBOUNDED:
var k = 0
while k >= 0 limit 50 {
k = k + 1
}The 'while' loop reached its limit without its condition becoming false. [E-UNBOUNDED]So the limit is a safety net, not a way to say "at most N times". When "give up after N turns" is an expected outcome, put the count in the condition and choose a limit that the condition makes unreachable:
var turns = 0
while not deck.B.playing and turns < 32 limit 32 {
wait 1 beat
turns = turns + 1
}Here the condition becomes false after 32 turns at the latest, so the limit is never exceeded.
break and continue
breakleaves the innermost loop at once.continueends the current turn and goes to the next one. In aneveryloop the next turn still starts on the grid.
for barNumber in [1, 2, 3, 4, 5, 6, 7, 8] {
if not deck.A.playing {
break // the deck was stopped: abandon the pattern
}
if barNumber % 2 == 1 {
wait 1 bar
continue // odd bars: nothing to do
}
deck.A.eq.high = -12dB
wait 1 bar
deck.A.eq.high = 0dB
}Both are errors outside a loop (E-LOOP). A block scheduled with at or an event handler written inside a loop is not "inside the loop" for this purpose: it runs later, on its own.
Loops and scheduling
A loop is a convenient way to schedule many blocks with at. Each block keeps the value the loop variable had when it was scheduled.
// kill the bass for the last beat of each of the next four bars
for barNumber in 1...4 {
at beat barNumber * 4 { deck.A.eq.low = -26dB }
at bar barNumber + 1 { deck.A.eq.low = 0dB }
}
wait 4 barsThe loop itself takes no time; it only fills the timeline. The wait afterwards keeps the main sequence in step with what was scheduled. At most 256 scheduled blocks can be pending at once.
Nested loops
// two bars: a four-step pattern played twice per bar
let steps = [0dB, -12dB, 0dB, -60dB]
repeat 4 {
for level in steps {
deck.A.volume = level
wait 1/2beat
}
}
deck.A.volume = 0dBHow much a loop may do
Loops are where a script can do a lot of work in no time, so two run-time limits apply (see Performance Guidelines):
- at most 20000 operations between two waits (
E-BUDGET); - at most 512 parameter changes and actions within one beat (
E-RATE).
repeat 2000 {
mixer.crossfader = 0.5
}More than 512 commands in one beat. The automation was stopped to protect the performance. [E-RATE]A loop that waits in its body spreads its work over time and stays far below both limits.
Choosing a loop
| You want | Use |
|---|---|
| The same thing N times | repeat N |
| Steps numbered 1 to N | for i in 1...N |
| A pattern of values | for x in [ … ] |
| Something on every beat, half-beat… for a fixed length | every P for T |
| Something on every beat or bar with no fixed end | on beat, on bar (Events) |
| To wait for a condition | while … limit, with a counter in the condition |