SPB Git

Repository Public

conditions.md 6.3 KB

# Conditions

A condition lets a script look at the rig and decide. Is deck B loaded? Is deck A the faster one? Is there less than a minute left? With if, the same automation can do the right thing in different situations instead of assuming one.

# if

orixdj
if deck.B.loaded {
    deck.B.play()
}

The block runs only when the condition is true. The condition is read at the moment the cursor reaches the if; it is not watched afterwards.

# else

orixdj
if deck.A.playing {
    deck.A.pause()
} else {
    deck.A.play()
}

# else if

Conditions are tried in order; the first true one wins and the others are skipped.

orixdj
let left = deck.A.remaining
if left < 15s {
    print("deck A: mix now")
} else if left < 60s {
    print("deck A: get ready")
} else {
    print("deck A: plenty of time")
}

# The condition must be true or false

A condition is a value of type bool. A number is not a condition; compare it with something.

orixdj-error
if deck.A.bpm {
    deck.A.play()
}
text
The condition must be true or false, not number. Compare it, e.g. deck.A.bpm > 120. [E-TYPE]

# Comparisons

Operator Meaning Works on
== equal two values of the same type (not arrays)
!= not equal the same
<, <= less than, at most number, gain, frequency, duration
>, >= greater than, at least number, gain, frequency, duration

Both sides must have the same type, and the unit must be written:

orixdj
if deck.A.volume < -20dB { print("deck A is low") }
if deck.A.filter.highpass > 200Hz { print("the bass of deck A is filtered") }
if deck.A.remaining <= 16 bars { print("last sixteen bars") }
if mixer.crossfader == 0.5 { print("crossfader centred") }
if mixer.curve == "cut" { print("cut curve") }
orixdj-error
if deck.A.remaining < 30 { deck.B.play() }
text
Operator '<' cannot combine duration and number. Add the unit: 4beats. [E-TYPE]

A musical duration and an absolute one can be compared; both are converted to beats with the current tempo. deck.A.remaining <= 16 bars compares the time left on deck A (in seconds) with sixteen bars at the master tempo.

Be careful with == on values that are computed or that come from a moving control: two fractional numbers are rarely exactly equal. Prefer < and > for anything that moves.

# Combining conditions

Operator Also written True when
a and b a && b both are true
a or b a || b at least one is true
not a !a a is false

not binds tighter than and, which binds tighter than or. Use parentheses when in doubt.

orixdj
if deck.A.playing and not deck.B.playing {
    deck.B.play()
}

if deck.A.trackBpm == 0 or deck.B.trackBpm == 0 {
    print("one of the decks has no tempo")
}

if (deck.A.playing or deck.B.playing) and mixer.master.volume > -60dB {
    print("something is audible")
}

and and or stop as soon as the answer is known: in a and b, b is not evaluated when a is false; in a or b, b is not evaluated when a is true.

# What a script can look at

Every readable path can be used in a condition. The ones used most:

Question Expression
Is a track loaded? deck.B.loaded
Is the deck playing? deck.A.playing
Is a loop active? deck.A.looping
Is sync on? deck.B.sync
Does the track have a known tempo? deck.B.trackBpm > 0
How much time is left? deck.A.remaining
Where is the playhead? deck.A.position, deck.A.beat
Which deck drives the clock? master.deck == "A"
What is the tempo? master.bpm, deck.A.bpm
Is the effect on? fx.echo.enabled, deck.A.fx.gate.enabled
How loud is it? deck.A.level, mixer.master.level
Which key? deck.A.key == deck.B.key

The full list is in the reference chapters: every path marked "read" can be used.

# Guard clauses: check first, then act

The most valuable use of if in a live script is refusing to start when the situation is wrong. Check at the top, explain with print, and stop.

orixdj
automation "Guarded Blend" quantize bar {
    if not deck.B.loaded {
        print("Deck B is empty.")
        stop
    }
    if deck.B.playing {
        print("Deck B is already playing.")
        stop
    }
    if deck.A.trackBpm == 0 or deck.B.trackBpm == 0 {
        print("Both tracks need an analysed tempo.")
        stop
    }

    deck.B.sync(true)
    deck.B.volume = -60dB
    deck.B.play()
    over 8 bars {
        deck.B.volume -> 0dB
        deck.A.volume -> -60dB
    }
    deck.A.pause()
    deck.A.volume = 0dB
}

A statement written directly after stop in the same block can never run; the compiler points that out with the warning W-UNREACHABLE.

# Choosing a value

There is no "a if c else b" expression. Declare a var and assign it in the branches.

orixdj
var length = 8 bars
if deck.A.remaining < 16 bars {
    length = 4 bars          // not much track left: shorter blend
}
over length { deck.A.volume -> -12dB }
deck.A.volume = 0dB

For numbers, min, max and clamp often replace an if:

orixdj
let safeLevel = min(deck.A.volume, -6dB)       // never above -6 dB
let fade = clamp(deck.A.remaining, 4 bars, 16 bars)
print(safeLevel, fade)

# Conditions and time

An if is evaluated once, when the cursor arrives. It does not wait for the condition to become true. To act when something becomes true later, use one of these:

  • an event handler, if there is an event for it (Events);
  • a bar or beat handler that tests the condition on every bar or beat;
  • a bounded while loop that waits and tests again (Loops).
orixdj
// wait until deck B is playing, checking on every beat, for at most 64 beats
var waited = 0
while not deck.B.playing and waited < 64 limit 64 {
    wait 1 beat
    waited = waited + 1
}
if deck.B.playing {
    print("deck B started")
} else {
    print("gave up waiting for deck B")
}

The branches of an if may contain waits and ramps; the cursor follows whichever branch runs. When the two branches do not take the same time, the length of the automation is no longer known in advance, which only affects what the scheduler display can show.

Files main
Menu

Theme