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, asection.aliasreference, 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. Anonis followed by anoff, not by repeatedonmessages. - 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_initscript 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
offbytes 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. |
Related
- 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.