Skip to content

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 a script name:
    [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:

  1. The first binding whose modifier is currently held wins.
  2. Otherwise, the first binding with no modifier wins.
  3. 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..1 value (clamped). A 7-bit CC is normalized from 0..127; a cc14 endpoint 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_turn on a deck and navigate on LibraryNavigation. The device.toml endpoint must declare relative = "…" 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.

  • 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.