Scripting (Rhai)
Lifecycle hooks and script bindings for mapping bundles that declarative actions cannot express.
script.rhai is an optional Rhai file in a mapping bundle. It implements the lifecycle hooks named in [lifecycle] and any input binding that names a function instead of an action.
When to script
Most controls should use the declarative action catalog: a binding like play_pause = "Deck(_)::toggle_play" is validated, documented, and needs no code. Use a Rhai script only when the catalog cannot express what the hardware needs:
- Raw SysEx handshakes / initialization. Forcing a controller into a mode with a vendor SysEx message, or re-asserting it while idle.
- Controller-specific behavior. Per-device quirks such as pad LEDs that only exist for a particular firmware.
- Custom engine publishes. Emitting a command with a payload the declarative actions do not cover.
Add a script
- Put
script.rhaiin the bundle directory. The file is optional until a[lifecycle]hook names a function or an input binding usesscript. - Name the functions you need. A
[lifecycle]key is the event name, and its value is the function inscript.rhai; the function names may be anything. An input binding usesscript = "<function>". - Make every named function exist. A
[lifecycle]block without a script file fails validation with[lifecycle] requires script.rhai in the mapping bundle. A binding that names a script without a file fails withMissingScript. A missing lifecycle function is a silent no-op at runtime; a missing input-binding function raises an error, logged asscript binding failed. - Run
map-check. It compiles the script and verifies every named function is defined, so it is the step that catches a typo.
A typo is reported as:
lifecycle.on_init: script function `on_init` not found in script.rhai
inputs.deck_1.play_pause[0]: script function `foo` not found in script.rhai
A bindings file that only uses the null-modifier form needs no script.
Host functions
The host functions are registered in a global module, so they are called flat: midi_out([...]), not host.midi_out(...).
| Function | Purpose | Notes |
|---|---|---|
midi_out(bytes_array) |
Send raw MIDI bytes to the device output port. | Array of integers; payload capped at 256 bytes. Non-integer elements are ignored. Over the cap raises midi_out payload too large. |
publish(origin, kind, payload) |
Publish an engine command. | See the rules below. |
modifier_active("custom.<alias>") |
true while a [custom] modifier control is held. |
Pass the full custom.<alias> name. |
publish arguments
origin: one of"engine","mixer","deck1"…"deck4".kind: one of"play","pause","set_volume","notice","error".payload: a JSON string that is parsed into the command body. An empty string produces an empty body.
An unrecognized origin or kind falls back to "engine" / "notice". If the payload is non-empty but not valid JSON, that publish is skipped and a script publish payload parse failed warning is logged.
The set_volume example (from the test suite):
fn on_init() {
publish("deck1", "set_volume", "{\"type\":\"set_volume\",\"volume\":0.5}");
}
deck1 maps to deck index 0, so this calls set_volume on the first deck with volume = 0.5.
Lifecycle hooks
Lifecycle hook names are configured in [lifecycle]; each maps an event to a function name in script.rhai:
| Hook | When it runs | MIDI output |
|---|---|---|
on_init |
When the mapping attaches to a device. | Allowed: receives the real output port. |
on_shutdown |
When the mapping detaches. | Allowed. |
idle_heartbeat |
Roughly once per second, only while no deck is playing. | Allowed. |
Hooks take no arguments (fn on_init() { ... }); they use the host functions for all I/O. A hook that is named but missing from the script is a no-op at runtime, so map-check is what catches typos.
idle_heartbeat is driven from the MIDI pump, not a timer thread. It fires at most once per second (the first call fires immediately). It is suppressed while any deck is playing, and the host also refuses to schedule it when a deck is active. That makes it a keepalive for controllers that need periodic traffic, without stomping on normal play.
Input script bindings
An input binding may name a script function instead of a declarative action. A binding is exactly one of action or script. Supplying both, or neither, is a validation error.
[inputs.deck_1]
play_pause = { script = "on_play_pause" }
The runtime calls:
fn on_play_pause(value_01, active) {
// ...
}
value_01: the normalized0..1control value for absolute controls. For relative controls (jog wheels) it is the integer delta of the tick, which may be negative.active: the button / press state.
Globals
Top-level const and let declarations in script.rhai are evaluated once and remain visible inside every hook and input-script call. This is what lets on_init and idle_heartbeat share a constant SysEx payload:
const PC_MODE_SYSEX = [
0xF0, 0x00, 0x40, 0x05, 0x00, 0x00, 0x02, 0x06, 0x00, 0x03, 0x01, 0xF7
];
fn idle_heartbeat() {
midi_out(PC_MODE_SYSEX);
}
Limits and error reporting
| Limit | Value | On violation |
|---|---|---|
| Operations per call | 50,000 | Raises an error (e.g. an infinite loop ends with an “operations” error). |
| Expression depth | 64 function / 32 caller | Raises an error. |
midi_out payload |
256 bytes | Raises midi_out payload too large. |
Compile errors are reported by map-check (ScriptCompile); runtime failures are reported by the host:
- A failed input script binding is logged as
script binding failed, with the mapping id, device id, port name, section, alias, and function. - A failed lifecycle hook is logged as
controller lifecycle failed(rate-limited) with the hook name; recovery logscontroller lifecycle recovered.
Full DDJ-400 example
The DDJ-400 needs a Pioneer SysEx at startup to stay in PC MIDI mode. Every pad and mode LED is declarative ([outputs.*] in map.toml). The script owns only the SysEx handshake and the two track-loaded lamps. Here is the shipped script.rhai, trimmed to the essentials:
mappings/ddj-400/script.rhai:
// Forcing SysEx so the unit stays in PC MIDI mode.
const PC_MODE_SYSEX = [
0xF0, 0x00, 0x40, 0x05, 0x00, 0x00, 0x02, 0x06, 0x00, 0x03, 0x01, 0xF7
];
fn on_init() {
// Track-loaded pad lights (Mixxx uses 0x9F note 0/1); harmless if unsupported.
midi_out([0x9F, 0x00, 0x7F]);
midi_out([0x9F, 0x01, 0x7F]);
// PC MIDI mode + query current knob/fader positions (Mixxx PioneerDDJ400.init).
midi_out(PC_MODE_SYSEX);
}
// Keepalive while stopped — re-assert PC MIDI mode.
fn idle_heartbeat() {
midi_out(PC_MODE_SYSEX);
}
fn on_shutdown() {
midi_out([0x9F, 0x00, 0x00]);
midi_out([0x9F, 0x01, 0x00]);
}
The matching map.toml block:
[lifecycle]
on_init = "on_init"
idle_heartbeat = "idle_heartbeat"
on_shutdown = "on_shutdown"
Line by line:
PC_MODE_SYSEXis a top-levelconst, so bothon_initandidle_heartbeatcan send the identical message without duplicating it.on_initlights the two track-loaded pads with note-on messages on the0x9Fchannel first. Then it sends the mode SysEx, which also queries the unit’s current knob and fader positions. Soft takeover uses the reply to adopt the first value.idle_heartbeatre-asserts the same SysEx roughly once a second while the decks are stopped. That keeps the unit from falling out of PC MIDI mode. The host skips it while a deck is playing.on_shutdownclears the two LEDs with note-off (0x00velocity).
For the action-catalog side of the same bundle, see inputs.
Related
- map.toml: lifecycle: the hook keys and the LED refresh around them.
- map.toml: inputs: the
scriptbinding field and the rest of the binding options. - Actions & aliases: the declarative alternative to a script.
- Validation: the
map-checkrun that compiles the script.