map.toml: [inputs]
Input binding forms, fields, modifiers, soft takeover, invert, absolute vs relative inputs, and rate limiting.
[inputs] is the hardware-to-app direction of a mapping. It binds the controls declared in device.toml to engine and library actions, so a pressed button or turned knob does something in Mixar.
Everything here is validated against the closed action and alias catalogs, so a name that is not in the catalog is rejected at load time. See Actions & aliases for the vocabulary, device.toml for the control declarations these bindings refer to, and outputs for the app-to-hardware direction.
Binding forms
[inputs.<section>] maps an input alias (the key) to a binding (the value). The section must be deck_1..deck_4, master, or sampler. The alias must be in that section’s closed catalog and must have a matching endpoint in device.toml, or load fails.
A binding has three interchangeable forms:
- String: the action id directly:
[inputs.deck_1] play_pause = "Deck(_)::toggle_play" - Table: an action plus options such as
modifier,soft_takeover,invert, or ascriptname:[inputs.deck_1] volume = { action = "Deck(_)::set_volume", soft_takeover = true, invert = false } - Array of tables: alternatives selected at runtime by modifier (see Modifiers & selection):
[inputs.deck_1] volume = [ { action = "Deck(_)::set_volume", soft_takeover = true }, { action = "Deck(_)::set_filter", modifier = "custom.shift", soft_takeover = true }, ]
The three forms normalize to a list of binding tables internally; a string becomes a single action binding and a table becomes a one-element list.
Binding fields
Every normalized binding table accepts these fields:
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
action |
string | exactly one of action/script |
— | A qualified action id; must be a known action. See Actions & aliases. |
script |
string | exactly one of action/script |
— | Name of a function in script.rhai. The bundle must contain the script file, or load fails. See Scripting. |
modifier |
string | no | none | Must be custom.<alias>; the alias must resolve in device.toml. |
soft_takeover |
boolean | no | on for absolute leaves, otherwise off | Explicit value overrides the default. |
invert |
boolean | no | false |
Flip the normalized value (1 - norm), or negate a relative delta. |
Validation requires exactly one of action or script to be present and non-empty. Both, or neither, is rejected with binding needs exactly one of action or script. A non-empty script also requires the bundle to carry script.rhai.
A leaf is the action named at the end of an action id, the set_volume in Deck(_)::set_volume. This page uses leaf throughout: absolute leaves consume a continuous value (set_volume), relative leaves consume a tick delta (jog_turn). See Absolute vs relative inputs and Actions & aliases for the full grammar.
Modifiers & selection
A modifier ties a binding to a control declared under [custom] in device.toml:
[inputs.deck_1]
filter = [
{ action = "Deck(_)::set_filter", soft_takeover = true },
{ action = "Deck(_)::set_eq_low", modifier = "custom.shift", soft_takeover = true },
]
The modifier value must start with custom. and the alias must exist in device.toml; anything else is a validation error. A modifier is held while its custom.<alias> control is active. The session adds the modifier when the control reports active and removes it when the control reports inactive.
When an input fires, the binding is selected as follows:
- The first binding whose
modifieris currently held wins. - Otherwise, the first binding with no modifier wins.
- If neither matches, the input is ignored.
Order inside the array matters for overlapping modifiers, and the unmodified binding (if any) is the fallback.
Soft takeover & invert
Soft takeover stops a hardware control from jumping the value it drives. Without it, a filter knob can slam the value the moment you touch it. A knob left at 80 % would jump a software value sitting at 40 %. With soft takeover the control is ignored until its physical position crosses the current value. Only then does it take over smoothly from there.
That helps every control whose position is shared with (or unknown to) the screen. Examples are mixer knobs after a page load, jog-adjacent encoders, and decks you have not touched yet.
It is enabled by default only for the absolute leaves that consume a continuous 0..1 value:
set_volume, set_filter, set_gain, set_eq_high, set_eq_mid, set_eq_low, set_stem_eq_high, set_stem_eq_mid, set_stem_eq_low, set_crossfader, set_cue_mix, set_speed.
Every other leaf defaults to soft takeover off. An explicit soft_takeover = true/false always wins, so you can opt an absolute control out or opt a non-absolute control in.
Invert is false by default. When invert = true, the value is flipped in the dispatch path before the action is resolved:
- absolute →
1 - norm - relative →
-delta
Use it for controllers whose physical direction is reversed, such as a Pioneer tempo fader:
[inputs.deck_1]
tempo = { action = "Deck(_)::set_speed", soft_takeover = true, invert = true }
Absolute vs relative inputs
A binding’s leaf takes one of two kinds of value:
- Absolute leaves consume a normalized
0..1value (clamped). A 7-bit CC is normalized from0..127; acc14endpoint pairs two CCs into one value. See device.toml. Relative ticks are never coerced into an absolute action: the action does not resolve. - Relative leaves consume a decoded tick delta:
jog_turnon a deck andnavigateonLibraryNavigation. Thedevice.tomlendpoint must declarerelative = "…"so the raw CC is decoded into signed ticks.
This pairing is enforced at load time. A type = "cc" endpoint that declares relative must be bound to a relative action, and a relative action must be bound to a relative endpoint. A mismatch fails map-check with a message naming the action and telling you to set relative only for jog_turn/navigate.
Rate limiting
Continuous CC input is coalesced to at most 60 Hz so a burst cannot flood the engine. Absolute CC keeps the latest value; relative CC sums the deltas. Either way the first message publishes immediately. Subsequent messages inside the ~16 ms window are held pending, then flushed by the MIDI pump. Notes are edge-triggered and bypass this coalescing: only a transition (press or release) dispatches.
An absolute value identical to the one last published for that binding is dropped. Some controllers answer a position query with a full state dump; the DDJ-400 does this on every idle heartbeat. Mixar therefore ignores the unchanged knob positions a controller repeats, so they do not revert a screen-side change to the same parameter.
Related
- outputs: signals, LED modes (on/off/blink), caching, refresh rules, VU meters.
- lifecycle: the three script hooks and when the session calls them.
- Actions & aliases: the action vocabulary and how aliases resolve.
- device.toml: the endpoint and alias declarations these bindings point at.
- Scripts: the Rhai side, when a binding names a function instead of an action.
- Validation: load-time checks, including the examples above.