SPB Git

Repository Public

conditions.md 6.3 KB 218 lines markdown

1# Conditions23A 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.45## `if`67```orixdj8if deck.B.loaded {9    deck.B.play()10}11```1213The 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.1415## `else`1617```orixdj18if deck.A.playing {19    deck.A.pause()20} else {21    deck.A.play()22}23```2425## `else if`2627Conditions are tried in order; the first true one wins and the others are skipped.2829```orixdj30let left = deck.A.remaining31if left < 15s {32    print("deck A: mix now")33} else if left < 60s {34    print("deck A: get ready")35} else {36    print("deck A: plenty of time")37}38```3940## The condition must be true or false4142A condition is a value of type `bool`. A number is not a condition; compare it with something.4344```orixdj-error45if deck.A.bpm {46    deck.A.play()47}48```4950```text51The condition must be true or false, not number. Compare it, e.g. deck.A.bpm > 120. [E-TYPE]52```5354## Comparisons5556| Operator | Meaning | Works on |57| --- | --- | --- |58| `==` | equal | two values of the same type (not arrays) |59| `!=` | not equal | the same |60| `<`, `<=` | less than, at most | number, gain, frequency, duration |61| `>`, `>=` | greater than, at least | number, gain, frequency, duration |6263Both sides must have the same type, and the unit must be written:6465```orixdj66if deck.A.volume < -20dB { print("deck A is low") }67if deck.A.filter.highpass > 200Hz { print("the bass of deck A is filtered") }68if deck.A.remaining <= 16 bars { print("last sixteen bars") }69if mixer.crossfader == 0.5 { print("crossfader centred") }70if mixer.curve == "cut" { print("cut curve") }71```7273```orixdj-error74if deck.A.remaining < 30 { deck.B.play() }75```7677```text78Operator '<' cannot combine duration and number. Add the unit: 4beats. [E-TYPE]79```8081A 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.8283Be 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.8485## Combining conditions8687| Operator | Also written | True when |88| --- | --- | --- |89| `a and b` | `a && b` | both are true |90| `a or b` | `a \|\| b` | at least one is true |91| `not a` | `!a` | a is false |9293`not` binds tighter than `and`, which binds tighter than `or`. Use parentheses when in doubt.9495```orixdj96if deck.A.playing and not deck.B.playing {97    deck.B.play()98}99100if deck.A.trackBpm == 0 or deck.B.trackBpm == 0 {101    print("one of the decks has no tempo")102}103104if (deck.A.playing or deck.B.playing) and mixer.master.volume > -60dB {105    print("something is audible")106}107```108109`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.110111## What a script can look at112113Every readable path can be used in a condition. The ones used most:114115| Question | Expression |116| --- | --- |117| Is a track loaded? | `deck.B.loaded` |118| Is the deck playing? | `deck.A.playing` |119| Is a loop active? | `deck.A.looping` |120| Is sync on? | `deck.B.sync` |121| Does the track have a known tempo? | `deck.B.trackBpm > 0` |122| How much time is left? | `deck.A.remaining` |123| Where is the playhead? | `deck.A.position`, `deck.A.beat` |124| Which deck drives the clock? | `master.deck == "A"` |125| What is the tempo? | `master.bpm`, `deck.A.bpm` |126| Is the effect on? | `fx.echo.enabled`, `deck.A.fx.gate.enabled` |127| How loud is it? | `deck.A.level`, `mixer.master.level` |128| Which key? | `deck.A.key == deck.B.key` |129130The full list is in the reference chapters: every path marked "read" can be used.131132## Guard clauses: check first, then act133134The 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`.135136```orixdj137automation "Guarded Blend" quantize bar {138    if not deck.B.loaded {139        print("Deck B is empty.")140        stop141    }142    if deck.B.playing {143        print("Deck B is already playing.")144        stop145    }146    if deck.A.trackBpm == 0 or deck.B.trackBpm == 0 {147        print("Both tracks need an analysed tempo.")148        stop149    }150151    deck.B.sync(true)152    deck.B.volume = -60dB153    deck.B.play()154    over 8 bars {155        deck.B.volume -> 0dB156        deck.A.volume -> -60dB157    }158    deck.A.pause()159    deck.A.volume = 0dB160}161```162163A statement written directly after `stop` in the same block can never run; the compiler points that out with the warning `W-UNREACHABLE`.164165## Choosing a value166167There is no "a if c else b" expression. Declare a `var` and assign it in the branches.168169```orixdj170var length = 8 bars171if deck.A.remaining < 16 bars {172    length = 4 bars          // not much track left: shorter blend173}174over length { deck.A.volume -> -12dB }175deck.A.volume = 0dB176```177178For numbers, `min`, `max` and `clamp` often replace an `if`:179180```orixdj181let safeLevel = min(deck.A.volume, -6dB)       // never above -6 dB182let fade = clamp(deck.A.remaining, 4 bars, 16 bars)183print(safeLevel, fade)184```185186## Conditions and time187188An `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:189190- an event handler, if there is an event for it ([Events](events.md));191- a `bar` or `beat` handler that tests the condition on every bar or beat;192- a bounded `while` loop that waits and tests again ([Loops](loops.md)).193194```orixdj195// wait until deck B is playing, checking on every beat, for at most 64 beats196var waited = 0197while not deck.B.playing and waited < 64 limit 64 {198    wait 1 beat199    waited = waited + 1200}201if deck.B.playing {202    print("deck B started")203} else {204    print("gave up waiting for deck B")205}206```207208The 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.209210## Related211212- [Types](types.md)213- [Loops](loops.md)214- [Events](events.md)215- [Variables](variables.md)216- [Deck Commands](deck-api.md)217- [Error Handling](errors.md)218
Files main
Menu

Theme