Skip to content

map.toml: [outputs]

Signal-driven LED and meter outputs: binding fields, the signal catalog, LED modes, and caching rules.

[outputs.<section>] is the app-to-hardware direction of a mapping. It watches a closed-catalog signal for the section and emits MIDI when that signal turns on or off. That is how the app lights LEDs and drives callbacks on the controller. map.toml is the overview, inputs covers the opposite direction, and the control declarations these targets point at live in device.toml.

Sections

Sections are deck_1 through deck_4, master, sampler, and custom. Only deck_* sections resolve signals, and master resolves master_cue, fx_armed, the crossfader behavior flags, and crossfader_curve_<id>. sampler and custom are host-driven only.

Binding fields

Every output binding accepts these fields:

Field Required Default Notes
signal no — Closed-catalog signal name driving the LED. Absent → host-driven via apply_output_signal.
on yes — Target sent when the signal turns true. Alias or inline endpoint.
off yes — Target sent when the signal turns false. Alias or inline endpoint.
blink no — Third-state target: while the signal is true the LED alternates blink/off. Requires signal.
[outputs.deck_1]
play_pause = { signal = "playing", on = "play_led", off = { type = "note", channel = 1, note = 0x0B, velocity = 0x00 } }

Targets: aliases vs inline

Each of on, off, and blink is one of:

  • an alias resolved against device.toml: a section-local bare name, a section.alias reference, or a bare name searched across sections;
  • an inline endpoint table (type, channel, and the fields its type requires) serialized directly.

Alias targets resolve exactly like input aliases, so an unresolvable name fails with outputs.<section>.<alias>.on: alias '<name>' missing from device.toml.

Signal catalog

Signals are a closed catalog per section: a name outside the list fails load with unknown signal 'x' for 'deck_1'.

Deck signals

Signal Meaning
playing Deck playhead running.
cue_hold Cue held.
sync Deck is sync master.
quantize Quantize on.
stem_eq_enabled Deck header ST armed. It reports the toggle, not the live routing: the knobs only drive the stem EQ while the deck is really playing stems (stems_audible), so an armed deck can be on the channel EQ and the LED stays on.
headphone_cue Headphone cue (PFL) on.
track_loaded Track loaded in the deck.
loop_active Loop engaged.
loop_in_set Loop-in point set.
shift_held A custom.<alias> modifier for the section is held. Resolved from the session modifier set, not the engine snapshot.
pad_mode_hot_cue Deck pad mode is Hot Cue.
pad_mode_loop_roll Deck pad mode is Loop Roll.
pad_mode_beat_jump Deck pad mode is Beat Jump.
pad_mode_sampler Deck pad mode is Sampler.
pad_mode_stems Deck pad mode is Stems.
pad_mode_keyboard Deck pad mode is Keyboard.
pad_mode_key_shift Deck pad mode is Key Shift.

Slot signals

Pattern Range Meaning
hot_cue_<n> n = 1..=16 Library hot-cue slot n holds a cue.
loop_slot_<n> n = 1..=8 Saved-loop slot n is populated.
pad_hot_cue_<n> n = 1..=8 Mode-gated: the slot has a cue only on the Hot Cue page.
pad_loop_<n> n = 1..=8 Mode-gated: the slot is backed by a saved loop only on the Loop Roll page.
pad_beat_jump_<n>, pad_sampler_<n>, pad_stems_<n> n = 1..=8 Mode-gated, but always resolve false: there is no engine slot LED state for these pages yet. Bind them anyway so attach forces the bank off.

Because a pad bank is mode-gated, only the deck’s active page can light. The previous page’s bank goes dark as soon as the mode changes. pad_keyboard_* / pad_key_shift_* are not advertised: those banks are host-driven (see Host-driven outputs below).

Master signals

Signal Meaning
master_cue Mixer master cue (PFL) on.
fx_armed The shared Beat FX unit is armed (SlotEnabled on slot 0).
crossfader_hamster The invert flag is on (wire name hamster; A and B gains swapped).
crossfader_disabled The crossfader curve is bypassed (both sides full gain).
crossfader_curve_<id> true when <id> is the active crossfader curve (preset, custom group, or curve set); e.g. crossfader_curve_fast_cut.

LED modes

Each binding resolves to one of three states:

State Condition Wire effect
Off Signal false Sends off.
On Signal true, no blink declared Sends on.
Blink Signal true and blink declared Alternates blink and off every 200 ms (≈2.5 Hz full cycle). The lit phase uses blink, never on.

The session advances the blink phase from the MIDI pump (tick_leds); a bundle whose outputs declare no blink anywhere skips the scan entirely.

The DDJ-400 uses blink for the +SHIFT mode indicators: while shift_held is true the lamp flashes instead of sitting solid.

pad_mode_loop_roll_shift = { signal = "shift_held", blink = "pad_mode_loop_roll_shift_led", on = "pad_mode_loop_roll_shift_led", off = { type = "note", channel = 1, note = 0x1E, velocity = 0x00 } }

Caching and refresh

  • The last state per binding is cached as section.alias, so the same state is never re-sent. An on is followed by an off, not by repeated on messages.
  • State is forced to re-send after a pad-mode switch (set_deck_pad_mode → refresh_deck_leds), since hardware often clears pad LEDs when the page changes. The session drops the cached value and replays the hot-cue LED state.
  • On attach, the [lifecycle] on_init script runs first. Then a forced sweep (refresh_all_leds) re-asserts every lamp, since the unit may still hold state from a previous run.
  • On shutdown and detach, every mapped lamp’s off bytes are sent (clear_leds). The cache is dropped first so a failure mid-sweep cannot leave a stale lit entry.
  • Continuous-value commands (jog, EQ, volume, …) skip the per-deck LED resolve.

Host-driven (signal-less) outputs

Without signal, the binding key doubles as the watch name. It must be a closed input alias for that section, except in custom, where any snake_case key is allowed. The host lights these via apply_output_signal.

The DDJ-400’s Keyboard and Key Shift pad banks are signal-less:

keyboard_pad_1 = { on = "keyboard_pad_1_led", off = { type = "note", channel = 8, note = 0x40, velocity = 0x00 } }

The host re-drives them whenever the deck enters a keyboard or key-shift page (refresh_key_shift_leds), following the key-shift state, the keyboard page, and the root cue. These are host-owned lamps, unlike the declarative signals above: [lifecycle] scripts cannot read or write them.

VU meters are not [outputs] bindings. The host drives the vu_meter endpoint declared in device.toml (set_deck_vu). It sends CC value level × 150 clamped to 127 (the Mixxx scale) and skips duplicate values.

DDJ-400 worked examples

Control Signal On target Off target
Play/pause lamp playing alias play_led inline note ch 1 0x0B
Loop group (loop_out, loop_out_shift, exit_loop, exit_loop_shift) loop_active per-lamp aliases inline notes ch 1 0x11/0x4E/0x4D/0x50
Hot-cue pad bank (deck 1) pad_hot_cue_1 … pad_hot_cue_8 alias hot_cue_pad_led1..8 inline notes ch 9 0x00..0x07
Master cue master_cue alias master_cue_led inline note ch 7 0x63
Beat FX ON/OFF (beat_fx_on, beat_fx_on_shift) fx_armed aliases beat_fx_on_led / beat_fx_shift_led inline notes ch 5 0x47 / 0x43
+SHIFT mode indicators shift_held alias (also blink) inline notes ch 1 0x1E/0x6B

Validation errors

Error Fix
unknown outputs section 'x' Use deck_1..deck_4, master, sampler, or custom.
outputs.<section>.<alias>: alias must be snake_case Rename the binding key.
outputs.<section>.<alias>: watch key not in closed catalog A signal-less binding key must be a closed input alias for that section (any snake_case key works in custom), or add a signal.
outputs.<section>.<alias>: 'blink' requires 'signal' (otherwise the binding is never resolved) Add signal = "…". Without one the binding is only host-driven and can never blink.
outputs.<section>.<alias>: unknown signal 'x' for 'deck_1' Use a signal from this page’s catalog for that section.
outputs.<section>.<alias>.on: alias '<name>' missing from device.toml Declare the alias in device.toml, or switch to an inline endpoint.
  • inputs: binding forms, fields, modifiers, soft takeover, absolute vs relative inputs, rate limiting.
  • lifecycle: the three script hooks and when the session calls them.
  • Actions & aliases: the action vocabulary and how aliases resolve.
  • Scripts: the Rhai side (on_init, idle_heartbeat, on_shutdown).
  • Validation: load-time checks and the common errors above.