Skip to content

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

  1. Put script.rhai in the bundle directory. The file is optional until a [lifecycle] hook names a function or an input binding uses script.
  2. Name the functions you need. A [lifecycle] key is the event name, and its value is the function in script.rhai; the function names may be anything. An input binding uses script = "<function>".
  3. 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 with MissingScript. A missing lifecycle function is a silent no-op at runtime; a missing input-binding function raises an error, logged as script binding failed.
  4. 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 normalized 0..1 control 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 logs controller 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_SYSEX is a top-level const, so both on_init and idle_heartbeat can send the identical message without duplicating it.
  • on_init lights the two track-loaded pads with note-on messages on the 0x9F channel 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_heartbeat re-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_shutdown clears the two LEDs with note-off (0x00 velocity).

For the action-catalog side of the same bundle, see inputs.