SPB Git

Repository Public

loops.md 7.3 KB

# 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

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

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

orixdj
for step in 1...4 {
    deck.A.filter.highpass = hz(200 * step)       // 200, 400, 600, 800 Hz
    wait 1 beat
}
deck.A.filter.highpass = 20Hz
orixdj
for 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

orixdj
let pattern = [0dB, -60dB, 0dB, 0dB, -60dB, 0dB, -60dB, -60dB]
for level in pattern {
    deck.A.volume = level
    wait 1/2beat
}
deck.A.volume = 0dB

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

orixdj
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 beats runs 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

orixdj
var level = 0dB
while level > -24dB limit 16 {
    level = level - 3dB
    deck.A.eq.mid = level
    wait 1 beat
}
deck.A.eq.mid = 0dB

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

orixdj-error
while deck.A.playing {
    wait 1 beat
}
text
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:

orixdj-error
var k = 0
while k >= 0 limit 50 {
    k = k + 1
}
text
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:

orixdj
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

  • break leaves the innermost loop at once.
  • continue ends the current turn and goes to the next one. In an every loop the next turn still starts on the grid.
orixdj
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.

orixdj
// 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 bars

The 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

orixdj
// 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 = 0dB

# How 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).
orixdj-error
repeat 2000 {
    mixer.crossfader = 0.5
}
text
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
Files main
Menu

Theme