SPB Git

Repository Public

timing.md 12.5 KB 315 lines markdown

1# Timing23Timing 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.45## The cursor67Think 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.89- 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.10- **`wait` moves the cursor** forward.11- **`over` moves the cursor** forward by its duration while it ramps.12- **`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.1314```orixdj15deck.A.eq.low = -26dB        // cursor at beat 016wait 4 beats                 // cursor moves to beat 417deck.A.eq.low = 0dB          // happens at beat 418wait 2 bars                  // cursor moves to beat 1219deck.A.eq.high = -6dB        // happens at beat 1220wait 1 bar21deck.A.eq.high = 0dB         // happens at beat 1622```2324Time 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".2526## `wait`2728### Wait for a duration2930```orixdj31wait 1 beat32wait 2 bars33wait 1/2beat34wait 750ms35```3637The 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.3839### Wait for the next beat or bar of the master clock4041`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.4243```orixdj44wait nextBar45deck.B.play()46```4748If 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`.4950### Wait until a position5152`wait until` moves the cursor to a position counted **from the start of the automation**.5354```orixdj55wait until bar 3             // start of the automation's third bar (8 beats in)56deck.B.play()57wait until beat 13           // the automation's 13th beat (12 beats in)58deck.A.pause()59wait until 20 beats          // 20 beats after the start60deck.A.play()61```6263If 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`.6465`wait until nextBar` and `wait until nextBeat` are the same as `wait nextBar` and `wait nextBeat`.6667## `over`: ramps6869`over` moves controls smoothly. Inside the block, `path -> value` means "be at this value when the block ends".7071```orixdj72over 8 bars {73    deck.A.filter.highpass -> 8kHz74    deck.A.volume -> -20dB75    mixer.crossfader -> 176}77deck.A.filter.highpass = 20Hz78deck.A.volume = 0dB79```8081What happens, precisely:82831. When the cursor reaches `over`, each ramp reads the current value of its control. That is the starting point; you do not write it.842. All the ramps of the block run together for the duration.853. 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.8687The duration must be greater than zero.8889At 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.9091```orixdj92mixer.crossfader = 093over 4 beats { mixer.crossfader -> 1 }94print(mixer.crossfader)                      // 195over 4 beats { mixer.crossfader -> 0.5 }     // starts from exactly 196stop                                         // the crossfader is at 0.597```9899### What can be inside `over`100101Only two kinds of statement:102103- ramps, `path -> value`;104- immediate statements: `path = value`, an action call, `let`/`var`, `print`.105106Immediate statements run at the **start** of the block, before the ramps begin, whatever their position inside the block.107108```orixdj109fx.reverb.mix = 0110over 2 bars {111    fx.reverb.enable()           // at the start112    fx.reverb.mix -> 0.6113}114fx.reverb.mix = 0115fx.reverb.disable()116```117118`wait`, `at`, loops, conditions and calls to your own procedures are not allowed inside `over` (`E-OVER`). Put them before or after the block.119120`->` is valid only inside `over`. Outside, it is the error `E-RAMP`:121122```orixdj-error123deck.A.volume -> -60dB124```125126```text127'->' 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]128```129130### What can be ramped131132A 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.133134Switches (`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.135136```orixdj-error137over 4 bars { fx.delay.time -> 1/4beat }138```139140```text141'fx.delay.time' (duration) cannot be ramped; set it with '='. [E-RAMP]142```143144To change a duration parameter in steps, use a loop:145146```orixdj147fx.delay.enable()148for slice in [1 beat, 1/2beat, 1/4beat, 1/8beat] {149    fx.delay.time = slice150    wait 1 bar151}152fx.delay.disable()153```154155### Curves156157By default a ramp is linear. `curve` chooses another shape.158159```orixdj160over 4 bars curve easeIn { deck.A.filter.highpass -> 4kHz }161over 1 bar curve easeOut { deck.A.filter.highpass -> 20Hz }162```163164| Curve | Shape | Progress at the halfway point | Feels like |165| --- | --- | --- | --- |166| `linear` | Straight line | 50 % | A steady hand |167| `easeIn` | Starts slowly, ends fast | 25 % | A build that accelerates into the drop |168| `easeOut` | Starts fast, ends slowly | 75 % | A quick move that settles gently |169| `smooth` | Slow, fast, slow | 50 % | A natural fader move |170| `exp` | Very slow start, very fast end | about 12 % | A riser that explodes at the end |171172Every 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`.173174### How values are interpolated175176The curve gives a progress from 0 to 1; the value is then computed according to the type of the control.177178- **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.179- **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.180- **Number** ramps are linear.181182### Two ramps on the same control183184A 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.185186If the same control is ramped twice in one `over` block, the last ramp wins and the compiler warns (`W-RAMP`).187188### `=` cancels a ramp189190A direct assignment to a control that is being ramped stops the ramp. The control keeps the assigned value.191192```orixdj193at beat 3 { mixer.crossfader = 0.2 }       // two beats into the ramp194over 8 beats { mixer.crossfader -> 1 }195// the crossfader is at 0.2 here: the assignment cancelled the ramp196mixer.crossfader = 0.5197```198199This is the script equivalent of grabbing a fader: the last direct instruction wins.200201### `over` without ramps202203An `over` block that contains no ramp only waits, and the compiler says so (`W-OVER`). Use `wait` for that.204205## `at`: schedule without waiting206207`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.208209```orixdj210at bar 3 { deck.A.eq.low = -26dB }       // will happen 8 beats in211at bar 4 { deck.A.eq.low = 0dB }         // will happen 12 beats in212over 4 bars { deck.A.filter.highpass -> 2kHz }213deck.A.filter.highpass = 20Hz214```215216The 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.217218Positions:219220| Form | Meaning |221| --- | --- |222| `at bar N { … }` | The first beat of bar N of the automation. `at bar 1` is the start. |223| `at beat N { … }` | Beat N of the automation. `at beat 1` is the start; `at beat 5` is the first beat of bar 2. |224| `at 16 beats { … }`, `at 2 bars { … }`, `at 30s { … }` | That long after the start. `at 0 beats` is the start. |225| `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). |226227Bars 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.228229A block scheduled with `at` has its own cursor. It can contain `wait` and `over`; they do not delay the main sequence.230231```orixdj232at bar 2 {233    over 1 bar { deck.A.eq.high -> -12dB }234    deck.A.eq.high = 0dB235}236over 4 bars { deck.B.volume -> -6dB }237deck.B.volume = 0dB238```239240### `at` blocks keep the values they were scheduled with241242A scheduled block sees each variable with the value it had when the `at` statement was executed. See [Variables](variables.md).243244### A position that has already passed245246`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.247248```orixdj249over 8 bars { deck.A.volume -> -60dB }     // the cursor is now 32 beats in250at bar 8 { deck.A.pause() }                // bar 8 started at beat 28: already past251deck.A.volume = 0dB252```253254```text255line 3: 'at' names a position 4 beats in the past; running it now256```257258Write `at` statements **before** the `wait` or `over` they are meant to overlap. More in [Beats and Bars](beats-and-bars.md) and [Troubleshooting](troubleshooting.md).259260## Seconds and tempo261262Durations in seconds are converted to beats when the statement that uses them is executed, with the tempo of the master clock at that moment:263264```text265beats = seconds × BPM / 60266```267268| Duration | At 120 BPM | At 128 BPM | At 140 BPM |269| --- | --- | --- | --- |270| `500ms` | 1 beat | 1.07 beats | 1.17 beats |271| `1s` | 2 beats | 2.13 beats | 2.33 beats |272| `10s` | 20 beats | 21.33 beats | 23.33 beats |273274Consequences:275276- 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.277- A script that must stay on the grid should use beats and bars. Use seconds for things that are not musical.278- For the conversion, a tempo below 20 BPM is treated as 20 BPM.279280The compiler records that a script uses seconds; Claude Studio mentions it among the things to check.281282## Starting on the grid: `quantize`283284An automation starts at the instant it is launched, unless its header says otherwise.285286| Header | The automation's beat 0 is |287| --- | --- |288| `automation "X" { … }` | the moment it is started |289| `automation "X" quantize none { … }` | the same |290| `automation "X" quantize beat { … }` | the next beat of the master clock |291| `automation "X" quantize bar { … }` | the next bar line of the master clock |292293If the automation is started exactly on a line, it starts at once. See [Automation Scheduling](scheduling.md).294295## Summary296297| Statement | Moves the cursor | Runs its block |298| --- | --- | --- |299| `wait d` | yes, by d | – |300| `wait nextBar` | yes, to the next bar line of the clock | – |301| `wait until bar N` | yes, to that position of the automation (never backwards) | – |302| `over d { … }` | yes, by d | immediate statements at the start, ramps during d |303| `at position { … }` | no | at the position, independently |304| `every p for t { … }` | yes, by t | every p (see [Loops](loops.md)) |305| `on event { … }` | no | each time the event fires (see [Events](events.md)) |306307## Related308309- [Beats and Bars](beats-and-bars.md)310- [Automation Scheduling](scheduling.md)311- [Loops](loops.md)312- [Events](events.md)313- [Units](units.md)314- [Troubleshooting](troubleshooting.md)315
Files main
Menu

Theme