Conditional Cue Triggering

The if: parameter allows any cue to be conditionally triggered based on the current value of a control signal. This enables scores that respond dynamically to performer input, external OSC data, or other real-time signal sources.

Syntax

cue(..., if:"signal>threshold")   // quoted — see below
cue(..., if:signal)               // truthy check (value > 0), no quotes needed

A comparison must be quoted. The DSL lexer does not read > or < inside an unquoted parameter value, so if:fader1.t>0.7 fails to parse and the whole cue is skipped. Quoting hands the comparison through as a string, which is what the condition parser wants. A bare truthy check has no operator in it and needs no quotes.

Examples

audio(src:hit.wav, if:"fader1.t>0.7")
scale(dur:2, if:"slider.y>=0.5")
nav(scroll@B, if:"knob.t>0.8")
rotate(dur:3, speed:90, if:adc.onset)

if: gates — trig: causes

if: asks "should this cue be allowed to fire?" — something else does the firing. To make the signal itself start a cue, put the same condition in trig::

audio(src:hit.wav, if:"adc.amp>0.7")     // plays IF loud, when the playhead arrives
audio(src:hit.wav, trig:"adc.amp>0.7")   // plays BECAUSE it got loud

A threshold trig: fires on the rising edge — as the condition becomes true — and re-arms when the value falls back. Without that it would fire on every frame the condition held, which for audio is sixty times through one clap. once:1 limits it to the first crossing ever.

See random() for the fullest use of this: an onset rolling a number that picks a picture.

Signal Path Format

One format: source.channel — the uid of whatever publishes the signal, then the channel name.

fader1.t        an o2p fader's position
knob.x          a controlXY handle
r1.norm         a rotate cue's angle, normalised
adc.amp         the audio input's level
transport.t     the playhead

Earlier versions also wrote a type-prefixed path (o2p:slider.t, audio:mic.amp) and the documentation presented it as the fuller of two forms. Nothing ever read it: the prefixed path was written on every frame and subscribed to by nothing. It is gone — use source.channel, and if you have an old score carrying a prefix, drop it.

The full list of what each cue publishes is in Control & Modulation.

Comparison Operators

If no operator is provided, the condition performs a truthy check (signal value > 0).

Behaviour

• Condition not met: Cue is skipped entirely
• Re-triggering: If the playhead crosses the cue again later and the condition is now met, the cue will fire
• Works with all cues: Animation, audio, navigation, OSC - any cue type accepts if:

Use Cases

Amplitude-gated audio

audio(src:accent.wav, if:"adc.amp>0.8")

Only plays when input amplitude exceeds threshold.

Performer-controlled branching

nav(scroll@sectionA, if:"fader1.t>0.5")
nav(scroll@sectionB, if:"fader1.t<=0.5")

Score navigation depends on fader position.

Animation triggered by external control

scale(dur:2, values:[1,2,1], if:osc:/trigger>0)

Animation only starts when OSC message received.

Conditional visual feedback

fade(target:highlight, to:1, dur:0.2, if:"slider.y>=0.9")

Element fades in when slider reaches top position.

Technical Notes

• Conditions are evaluated against the ParamBus signal store
• Signal must exist and have a numeric value for comparison to succeed
• Unknown signals or undefined values cause condition to fail (cue skipped)
• Floating point comparisons use a small epsilon (0.0001) for == and !=

Tip: use ← → or ↑ ↓ to navigate the docs