Skip to content

map.toml

What map.toml contains, how the file is shaped, and where [inputs], [outputs], and [lifecycle] are documented.

map.toml is the behavioral half of a mapping bundle. It binds the controls declared in device.toml to engine and library actions, drives device LEDs from watched signals, and names the optional script lifecycle hooks.

How the three tables relate

The tables point in opposite directions.

Table Role Reference
[inputs] How the hardware talks to the app: every control event is mapped to an engine action. inputs
[outputs] How the app talks back to the hardware: watched engine state is written out as MIDI, almost always to light LEDs. outputs
[lifecycle] Neither direction: it names script.rhai hooks the session calls when a controller attaches, idles, or detaches. lifecycle

Everything 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 and device.toml for the control declarations map.toml refers to.

Keys

A map has one required key (schema_version), two optional tables ([inputs] and [outputs]), and an optional [lifecycle] table.

Key Required Notes
schema_version yes Must be exactly 1; any other value is a schema error.
[toml-schema] no Editor aid only. It is removed from the parsed table before deserialize and never consulted at runtime.
[inputs] no Per-section input bindings; see inputs.
[outputs] no Per-section signal-to-MIDI output bindings; see outputs.
[lifecycle] no Script hook names. Only meaningful with script.rhai; see lifecycle.

Sections

Sections are deck_1 through deck_4, master, and sampler. [outputs] also accepts custom for host-driven lamps.

Complete example

# map.toml — declares what each device control does.
schema_version = 1

# Editor-only pointer to the TOML schema. Peeled off before deserialize; ignored at runtime.
[toml-schema]
version = "1.0.0"
location = "../../schemas/map.tosd"

# Optional script hooks. Requires script.rhai in the same mapping bundle.
[lifecycle]
on_init = "on_init"
idle_heartbeat = "idle_heartbeat"
on_shutdown = "on_shutdown"

# ---- Inputs ---------------------------------------------------------------
# One table per section: deck_1..deck_4, master, sampler.
[inputs.deck_1]
# String form: bind the input alias straight to an action.
play_pause = "Deck(_)::toggle_play"

# Table form: action + per-binding options.
volume = { action = "Deck(_)::set_volume", soft_takeover = true }

# Array form: modifier-selected alternatives (first active modifier wins).
filter = [
  { action = "Deck(_)::set_filter", soft_takeover = true },
  { action = "Deck(_)::set_eq_low", modifier = "custom.shift", soft_takeover = true },
]

# Relative leaf: the device endpoint must declare `relative = "…"`.
jog_turn = "Deck(_)::jog_turn"

[inputs.master]
crossfader = { action = "Mixer::set_crossfader", soft_takeover = true }

# ---- Outputs --------------------------------------------------------------
# Watched signal -> on/off MIDI (typically LEDs).
[outputs.deck_1]
play_pause = { signal = "playing", on = "play_led", off = { type = "note", channel = 1, note = 0x0B, velocity = 0x00 } }
cue = { signal = "cue_hold", on = { type = "note", channel = 1, note = 0x0C, velocity = 0x7F }, off = { type = "note", channel = 1, note = 0x0C, velocity = 0x00 } }