SPB Git

Repository Public

timing.md 12.5 KB

# Timing

Timing is the heart of ORIX Script. This chapter explains how an automation moves through time, the three timing statements (wait, over, at), how ramps are computed, and how seconds relate to beats.

# The cursor

Think of an automation as a finger moving along a timeline, like the playhead of a deck. That finger is the cursor. Statements are executed at the cursor, one after the other.

  • Most statements take no time. Setting a control, calling an action, declaring a variable, testing a condition: the cursor does not move. Ten assignments in a row all happen at the same instant.
  • wait moves the cursor forward.
  • over moves the cursor forward by its duration while it ramps.
  • at does not move the cursor. It puts a block on the timeline at a given position and carries on immediately with the next statement.
orixdj
deck.A.eq.low = -26dB        // cursor at beat 0
wait 4 beats                 // cursor moves to beat 4
deck.A.eq.low = 0dB          // happens at beat 4
wait 2 bars                  // cursor moves to beat 12
deck.A.eq.high = -6dB        // happens at beat 12
wait 1 bar
deck.A.eq.high = 0dB         // happens at beat 16

Time is counted in beats of the master clock. The automation's own timeline starts at beat 0 when the automation starts; that instant is also called "bar 1, beat 1".

# wait

# Wait for a duration

orixdj
wait 1 beat
wait 2 bars
wait 1/2beat
wait 750ms

The duration must be zero or more and at most 100000 beats. A plain number is not a duration: wait 4 is an error, wait 4 beats is correct.

# Wait for the next beat or bar of the master clock

wait nextBeat and wait nextBar move the cursor to the next beat or bar line of the master clock. They are how an automation that was started at an arbitrary moment gets back onto the grid.

orixdj
wait nextBar
deck.B.play()

If the cursor is already exactly on a beat (or bar) line, wait nextBeat (or wait nextBar) does not wait: "the next line" includes the one you are standing on. An automation declared with quantize bar starts on a bar line, so a wait nextBar as its first statement does nothing. To skip to the following bar, wait a full bar: wait 1 bar.

# Wait until a position

wait until moves the cursor to a position counted from the start of the automation.

orixdj
wait until bar 3             // start of the automation's third bar (8 beats in)
deck.B.play()
wait until beat 13           // the automation's 13th beat (12 beats in)
deck.A.pause()
wait until 20 beats          // 20 beats after the start
deck.A.play()

If the position is already behind the cursor, wait until does not wait and the log shows a warning: 'wait until' names a position that has already passed.

wait until nextBar and wait until nextBeat are the same as wait nextBar and wait nextBeat.

# over: ramps

over moves controls smoothly. Inside the block, path -> value means "be at this value when the block ends".

orixdj
over 8 bars {
    deck.A.filter.highpass -> 8kHz
    deck.A.volume -> -20dB
    mixer.crossfader -> 1
}
deck.A.filter.highpass = 20Hz
deck.A.volume = 0dB

What happens, precisely:

  1. When the cursor reaches over, each ramp reads the current value of its control. That is the starting point; you do not write it.
  2. All the ramps of the block run together for the duration.
  3. The cursor moves to the end of the block. Each ramp writes its exact target at the end beat, and then the statement after the block runs, at that same beat.

The duration must be greater than zero.

At the end beat, the ramps are completed before anything else that is due at that beat. So the statement after the block already sees every ramped control on its exact target: reading the control returns the target, a second ramp on the same control starts from the target, and stop directly after the block leaves the control on its target.

orixdj
mixer.crossfader = 0
over 4 beats { mixer.crossfader -> 1 }
print(mixer.crossfader)                      // 1
over 4 beats { mixer.crossfader -> 0.5 }     // starts from exactly 1
stop                                         // the crossfader is at 0.5

# What can be inside over

Only two kinds of statement:

  • ramps, path -> value;
  • immediate statements: path = value, an action call, let/var, print.

Immediate statements run at the start of the block, before the ramps begin, whatever their position inside the block.

orixdj
fx.reverb.mix = 0
over 2 bars {
    fx.reverb.enable()           // at the start
    fx.reverb.mix -> 0.6
}
fx.reverb.mix = 0
fx.reverb.disable()

wait, at, loops, conditions and calls to your own procedures are not allowed inside over (E-OVER). Put them before or after the block.

-> is valid only inside over. Outside, it is the error E-RAMP:

orixdj-error
deck.A.volume -> -60dB
text
'->' ramps a parameter over time and is only valid inside an 'over' block, e.g. over 8bars { deck.A.volume -> … }. Use '=' to set a value now. [E-RAMP]

# What can be ramped

A control can be ramped when it is writable and its type is number, gain or frequency. The reference tables say "read, write, ramp" for those.

Switches (bool), text (string) and durations cannot be ramped; set them with =. That includes the time of a delay, the rate of a gate and the pre-delay of a reverb. master.bpm cannot be ramped either; ramp deck.X.bpm or deck.X.rate of the master deck instead.

orixdj-error
over 4 bars { fx.delay.time -> 1/4beat }
text
'fx.delay.time' (duration) cannot be ramped; set it with '='. [E-RAMP]

To change a duration parameter in steps, use a loop:

orixdj
fx.delay.enable()
for slice in [1 beat, 1/2beat, 1/4beat, 1/8beat] {
    fx.delay.time = slice
    wait 1 bar
}
fx.delay.disable()

# Curves

By default a ramp is linear. curve chooses another shape.

orixdj
over 4 bars curve easeIn { deck.A.filter.highpass -> 4kHz }
over 1 bar curve easeOut { deck.A.filter.highpass -> 20Hz }
Curve Shape Progress at the halfway point Feels like
linear Straight line 50 % A steady hand
easeIn Starts slowly, ends fast 25 % A build that accelerates into the drop
easeOut Starts fast, ends slowly 75 % A quick move that settles gently
smooth Slow, fast, slow 50 % A natural fader move
exp Very slow start, very fast end about 12 % A riser that explodes at the end

Every curve starts exactly at the current value and ends exactly at the target. The curve applies to all the ramps of the block. An unknown curve name is the error E-CURVE.

# How values are interpolated

The curve gives a progress from 0 to 1; the value is then computed according to the type of the control.

  • Gain ramps are linear in decibels. Halfway through a linear ramp from 0 dB to -40 dB, the level is -20 dB. This matches how a fader is heard.
  • Frequency ramps are logarithmic. Halfway through a ramp from 20 Hz to 2 kHz, the corner is at 200 Hz (the geometric middle), not at 1010 Hz. A filter sweep therefore sounds even across octaves.
  • Number ramps are linear.

# Two ramps on the same control

A control has at most one ramp at a time. Starting a new ramp on a control replaces the one that was running; the new ramp starts from the value the control has at that instant.

If the same control is ramped twice in one over block, the last ramp wins and the compiler warns (W-RAMP).

# = cancels a ramp

A direct assignment to a control that is being ramped stops the ramp. The control keeps the assigned value.

orixdj
at beat 3 { mixer.crossfader = 0.2 }       // two beats into the ramp
over 8 beats { mixer.crossfader -> 1 }
// the crossfader is at 0.2 here: the assignment cancelled the ramp
mixer.crossfader = 0.5

This is the script equivalent of grabbing a fader: the last direct instruction wins.

# over without ramps

An over block that contains no ramp only waits, and the compiler says so (W-OVER). Use wait for that.

# at: schedule without waiting

at schedules a block at a position on the automation's timeline, and the cursor does not move. Use it for things that must happen at a known place while something else is going on, such as a ramp.

orixdj
at bar 3 { deck.A.eq.low = -26dB }       // will happen 8 beats in
at bar 4 { deck.A.eq.low = 0dB }         // will happen 12 beats in
over 4 bars { deck.A.filter.highpass -> 2kHz }
deck.A.filter.highpass = 20Hz

The two at statements are read at beat 0 and take no time. The ramp then starts at beat 0 as well. During the ramp, the scheduled blocks fire at their positions.

Positions:

Form Meaning
at bar N { … } The first beat of bar N of the automation. at bar 1 is the start.
at beat N { … } Beat N of the automation. at beat 1 is the start; at beat 5 is the first beat of bar 2.
at 16 beats { … }, at 2 bars { … }, at 30s { … } That long after the start. at 0 beats is the start.
at nextBeat { … }, at nextBar { … } The next beat or bar line of the master clock after the cursor (or now, if the cursor is on one).

Bars and beats count from 1, as musicians count them. Durations count from 0. So at bar 3, at beat 9 and at 8 beats are the same instant.

A block scheduled with at has its own cursor. It can contain wait and over; they do not delay the main sequence.

orixdj
at bar 2 {
    over 1 bar { deck.A.eq.high -> -12dB }
    deck.A.eq.high = 0dB
}
over 4 bars { deck.B.volume -> -6dB }
deck.B.volume = 0dB

# at blocks keep the values they were scheduled with

A scheduled block sees each variable with the value it had when the at statement was executed. See Variables.

# A position that has already passed

at counts from the start of the automation, not from the cursor. If the cursor is already beyond the position, the block runs immediately and the log shows a warning.

orixdj
over 8 bars { deck.A.volume -> -60dB }     // the cursor is now 32 beats in
at bar 8 { deck.A.pause() }                // bar 8 started at beat 28: already past
deck.A.volume = 0dB
text
line 3: 'at' names a position 4 beats in the past; running it now

Write at statements before the wait or over they are meant to overlap. More in Beats and Bars and Troubleshooting.

# Seconds and tempo

Durations in seconds are converted to beats when the statement that uses them is executed, with the tempo of the master clock at that moment:

text
beats = seconds × BPM / 60
Duration At 120 BPM At 128 BPM At 140 BPM
500ms 1 beat 1.07 beats 1.17 beats
1s 2 beats 2.13 beats 2.33 beats
10s 20 beats 21.33 beats 23.33 beats

Consequences:

  • A wait in seconds started at 128 BPM is fixed in beats from that moment. If the tempo changes during the wait, the wait still ends after the same number of beats, so its length in real seconds changes.
  • A script that must stay on the grid should use beats and bars. Use seconds for things that are not musical.
  • For the conversion, a tempo below 20 BPM is treated as 20 BPM.

The compiler records that a script uses seconds; Claude Studio mentions it among the things to check.

# Starting on the grid: quantize

An automation starts at the instant it is launched, unless its header says otherwise.

Header The automation's beat 0 is
automation "X" { … } the moment it is started
automation "X" quantize none { … } the same
automation "X" quantize beat { … } the next beat of the master clock
automation "X" quantize bar { … } the next bar line of the master clock

If the automation is started exactly on a line, it starts at once. See Automation Scheduling.

# Summary

Statement Moves the cursor Runs its block
wait d yes, by d –
wait nextBar yes, to the next bar line of the clock –
wait until bar N yes, to that position of the automation (never backwards) –
over d { … } yes, by d immediate statements at the start, ramps during d
at position { … } no at the position, independently
every p for t { … } yes, by t every p (see Loops)
on event { … } no each time the event fires (see Events)
Files main
Menu

Theme