Repository Public
1# Introduction23ORIX Script is the automation language of ORIX DJ. A script describes, in musical time, what should happen to the decks, the mixer and the effects: "start deck B on the next bar, sweep a high-pass on deck A over eight bars, then pause deck A". ORIX DJ checks the script completely before it runs, then performs it in time with the master clock.45This manual describes version 1.0 of the language. The console command `version` prints the version built into your copy of ORIX DJ.67```console8> version9ORIX Script 1.010```1112## What a script looks like1314```orixdj15automation "Eight Bar Blend" quantize bar {16 deck.B.sync(true)17 deck.B.volume = -12dB18 deck.B.play()1920 over 8 bars {21 deck.A.filter.highpass -> 12kHz22 deck.A.volume -> -60dB23 deck.B.volume -> 0dB24 }2526 deck.A.pause()27 deck.A.filter.highpass = 20Hz28 deck.A.volume = 0dB29}30```3132Read it from top to bottom, the way you would read a set list:33341. The automation waits for the next bar line (`quantize bar`).352. Deck B is synced, set 12 dB down and started.363. For eight bars, three controls move together: the high-pass of deck A rises, deck A fades out, deck B fades in.374. When the eight bars are over, deck A is paused and its controls are put back.3839Values carry their unit (`-12dB`, `12kHz`, `8 bars`), so a script reads like the labels on a mixer.4041## What ORIX Script is for4243- **Transitions** that must land on a bar line: blends, bass swaps, cuts, echo exits.44- **Effect moves** that need more than two hands: several parameters ramped together, restored at the right moment.45- **Rhythmic tricks** on a grid: stutters, loop rolls, gate patterns.46- **Reactions** to what happens in the set: a track ending, a deck starting, a pad being hit.47- **Repeatable routines**: the same move, performed identically every time.4849## What a script can do5051A script can only use what is listed in the reference chapters:5253- read and set deck parameters and call deck actions ([Deck Commands](deck-api.md));54- read and set the mixer and read the master clock ([Mixer Commands](mixer-api.md));55- set up, switch and automate effects in the master rack and in each channel rack ([Effects Commands](effects-api.md));56- wait, schedule, ramp, loop, branch and react to events;57- print text to the automation log with `print(…)`.5859## What a script cannot do6061These limits are part of the design; they are what makes it reasonable to run a script in front of an audience.6263- **No file, network, shell or system access.** The language has no statement or function for any of them. The only link to your music library is `deck.X.load("title")` and `deck.X.loadNext()`, which ask ORIX DJ to load a track that is already in the library.64- **It never runs on the audio thread.** The runtime works on its own scheduler thread and only sends time-stamped parameter changes and actions to the audio engine. A slow or failing script cannot interrupt the sound.65- **It cannot run forever by accident.** Every loop has a bound, functions cannot call themselves, and the runtime counts the work a script does. See [Performance Guidelines](performance.md).66- **It cannot read MIDI, the keyboard or the screen.** It can react to sixteen numbered triggers, which you map to pads or keys. See [MIDI Integration](midi.md).67- **It cannot define new effects or process audio.** It controls the effects that exist.6869## Checked before it runs7071A script is compiled before any of it is executed. The compiler verifies every name, every type and unit, every constant value against the range of its parameter, the bound of every loop, and the use of every timing statement. If there is one error, nothing runs. Each message has a line, a column and a stable code such as `E-RANGE`; the codes are explained in [Error Handling](errors.md).7273```orixdj-error74deck.A.volume = 6dB75```7677```text786 dB is outside the range of 'deck.A.volume' (-60 dB … 0 dB). [E-RANGE]79```8081Some things can only be known while the script runs, for example whether a track is loaded. Those are run-time errors: the automation is cancelled, the effects it had switched on are switched off, and the audio keeps playing.8283## Deterministic8485The same script started in the same situation does the same thing. Time is counted in beats of the master clock, not in timer ticks, and even `random()` produces the same sequence on every run of an automation. That is why a script can be tried in the simulator first and trusted to behave the same way live.8687## One language, several ways in8889Everything in ORIX DJ that automates the mix uses this same language, the same compiler and the same runtime:9091| Where | What it does with ORIX Script |92| --- | --- |93| Automation Studio | The editor, the console, the simulator, the debugger, the presets gallery and the visual builder in one place. In the editor you write and save automations. Saved scripts can be exported as `.orixdj` text files and imported again. |94| Console | Each line you type is compiled as a small anonymous automation and run at once. See [Console Usage](console.md). |95| Presets | The 24 bundled presets are ordinary scripts that you can open, read and change. See [Presets](presets.md). |96| Visual builder | It generates ORIX Script text, which goes through the same compiler and has the same limits as a script typed by hand. |97| Docs tab | This documentation, inside the application. Examples can be opened in the editor or run in the simulator from there. |98| Claude Studio | Claude writes or corrects a script as text. ORIX DJ compiles it and runs it in the simulator on your Mac before showing it to you; it is never executed directly. See [Security Model](security.md). |99| Auto DJ | The transition between two Auto DJ tracks is a generated script, run like any other. |100| Simulator and debugger | Run a script against a simulated rig, without touching the audio. See [Debugging](debugger.md). |101102Because they share one runtime, what you learn in one place applies everywhere: a line that works in the console works in a script, and a preset is a good starting point for your own automation.103104## Files105106- A script file is UTF-8 text with the extension `.orixdj`.107- A file contains one or more `automation "Name" { … }` blocks, and optionally constants (`let`) and functions (`fn`) shared by them.108- A file exported by ORIX DJ starts with a short comment header (`// ORIX DJ Script v1`, then name, tags and dates, then `// ---`). The header is made of comments, so the file is still a valid script.109- Projects (`.orixdjproject`) store the scripts they use together with the language version.110111## How to read this manual112113If you have never programmed, read [Quick Start](quickstart.md), [First Automation](first-automation.md), [Timing](timing.md) and [Beats and Bars](beats-and-bars.md) in that order, then browse the [Examples](examples/README.md). If you program already, [Language Syntax](syntax.md), [Types](types.md) and [Automation Scheduling](scheduling.md) contain the precise rules.114115## Related116117- [Quick Start](quickstart.md)118- [First Automation](first-automation.md)119- [Language Syntax](syntax.md)120- [Security Model](security.md)121- [Complete API Reference](api-reference.md)122- [Version Compatibility](versions.md)123