Skip to content

device.toml

Field-by-field reference for the device.toml half of a Mixar mapping bundle.

device.toml is the hardware half of a mapping bundle: it describes the device and declares one MIDI endpoint per physical control. Each endpoint names the MIDI messages that control sends and receives. map.toml binds those endpoints to engine actions, and the alias names you can use as inputs are catalogued in Actions.

The file holds scalar identity fields, an optional [audio] hint table, and one table per control section ([deck_1]…[deck_4], [master], [sampler], [custom]). Every section maps a snake_case alias to a MIDI endpoint.

Top-level fields

Field Type Required Notes
schema_version integer yes Must be 1; any other value is rejected.
id string yes Non-empty, stable bundle id (e.g. pioneer.ddj-400).
vendor_name string yes Display vendor.
product_name string yes Must be non-empty.
description string no Free-form.
usb_vid integer no USB vendor id, written hex (e.g. 0x2b73).
usb_pid integer no USB product id, written hex.
midi_name_contains array of strings no Case-insensitive port-name substrings used for identity matching.
mapping_version string no Optional bundle version, e.g. "1.0.0". Settings compares it with the built-in mapping to show an “Update available” marker.
[toml-schema] table no Editor aid only; ignored at runtime.
[audio] table no Audio-output hints.
Sections tables no [deck_1]…[deck_4], [master], [sampler], [custom].

The UI offers a device as "Vendor Product"; vendor_name and product_name are joined with a space, skipping empty parts.

[audio]

Optional hints used to match the controller’s own audio output interface and to offer switching Mixar’s output buses to it when the controller connects.

Field Type Required Notes
output_name_contains array of strings no Substrings matched case-insensitively against output device names.
master_channels array of 2 integers no 1-based left/right channels for the master bus on that device.
headphone_channels array of 2 integers no 1-based left/right channels for the preview (headphone / cue) bus.
sample_rate integer no Rate to open the device at. Omit to follow the device default.

Declaring either channel pair makes Mixar prompt when the controller’s output device is present. The prompt appears after the mapping attaches, and confirming it runs the master bus (and, when headphone_channels is set, the preview bus) on the controller without changing the saved bus routes. That live override is kept in memory only; detaching the mapping or quitting Mixar resumes the saved routes. Settings marks the affected bus cards as overridden by the mapping. Declining leaves Settings → Audio untouched.

[audio]
output_name_contains = ["DDJ-400"]
master_channels = [1, 2]
headphone_channels = [3, 4]

Channel numbers are validated when the bundle loads: they are 1-based, left and right must differ, and at least one output_name_contains entry is required to declare a route. A bundle that only names devices (no channels) is valid but does not offer an output switch.

Sections

Each section is a table of alias = { endpoint }. Unknown section keys are rejected.

Section Scope
deck_1 … deck_4 Per-deck controls. The deck index must be in 1..=4.
master Mixer-wide controls: crossfader, cue mix, master cue, browse, load buttons.
sampler Sampler triggers and ends.
custom Free-form aliases, usable only as modifiers, referenced as custom.<alias>.

For deck_*, master, and sampler, the alias names of input controls are a closed catalog. See Actions for the full list rather than duplicating it here. In shape, deck aliases include play_pause, cue, sync, volume, gain, tempo, eq_high/eq_mid/eq_low, filter, the jog_* family, headphone_cue, loop_in/loop_out, the pad_mode_* selectors, and numbered names such as hot_cue_<n>, pad_<n>, jump_pad_<n>, and sampler_pad_<n> (any n from 1 up; the engine rejects slots it cannot use).

Out-only names are not restricted to the catalog. Extra aliases for LEDs (play_led, cue_led, hot_cue_<n>_led, …) and vu_meter are allowed and expected. [custom] is exempt from the catalog entirely. An extra input-eligible name in these sections is accepted by device.toml. It cannot be used as a [inputs.*] key in inputs, which runs the catalog check.

Endpoint fields

Field Applies to Required Type Notes
type all yes string "note", "cc", or "cc14".
channel all yes integer 1..=16.
note note yes for note integer 0..=127.
cc cc, cc14 yes integer or table A 7-bit number for cc; { msb = …, lsb = … } for cc14.
velocity note (output) no integer 0..=127; output default is 0x7F (127).
value cc / cc14 (output) no integer 0..=127; output default is 0x7F.
direction all no string "in", "out", or "inout"; default "inout".
relative cc (7-bit) only no string "BINARY_OFFSET", "TWOS_COMPLEMENT", or "SIGN_MAGNITUDE".

direction decides how the endpoint may be used: in and inout allow input, out and inout allow output. Only input-eligible endpoints are checked against each other for clashes.

Complete example

schema_version = 1                    # required, must be 1
id = "vendor.product"                 # required, stable bundle id
vendor_name = "Vendor"                # required display vendor
product_name = "Product"              # required, must be non-empty
description = "Optional one-liner"    # optional
usb_vid = 0x2b73                      # optional hex USB vendor id
usb_pid = 0x0026                      # optional hex USB product id
midi_name_contains = ["Product"]      # optional; case-insensitive port-name hints
mapping_version = "1.0.0"             # optional; version for the Settings update check

[toml-schema]                         # editor metadata ONLY (ignored at runtime)
version = "1.0.0"
location = "../../schemas/device.tosd"

[audio]                               # optional; hints for the controller's audio out
output_name_contains = ["Product"]
master_channels = [1, 2]              # 1-based pair for the master bus
headphone_channels = [3, 4]           # 1-based pair for the preview / cue bus

[deck_1]                              # alias = { endpoint }
play_pause = { type = "note", channel = 1, note = 0x0B }
volume     = { type = "cc14", channel = 1, cc = { msb = 0x13, lsb = 0x33 } }
jog_turn   = { type = "cc",   channel = 1, cc = 0x22, relative = "BINARY_OFFSET" }
play_led   = { type = "note", channel = 1, note = 0x0B, velocity = 0x7F, direction = "out" }

[deck_2]
play_pause = { type = "note", channel = 2, note = 0x0B }

# [deck_3] and [deck_4] follow the same shape; deck indices are 1..=4.

[master]
crossfader = { type = "cc14", channel = 7, cc = { msb = 0x1F, lsb = 0x3F } }

[sampler]
trigger_1 = { type = "note", channel = 1, note = 0x00 }

[custom]                              # free-form; usable only as modifiers (custom.<alias>)
shift = { type = "note", channel = 1, note = 0x3F }

Message types

note: buttons, pads, jog-touch

play_pause = { type = "note", channel = 1, note = 0x0B }

An incoming note-on with velocity greater than 0 is active; a note-on with velocity 0 is treated as a note-off (and matches the same channel/note). On output, the velocity defaults to 0x7F unless velocity is set.

cc: knobs and faders (7-bit)

filter = { type = "cc", channel = 1, cc = 0x14 }

cc is a single 7-bit controller number. The incoming value maps to a 0..1 control value as value / 127.

cc14: 14-bit knobs and faders

volume = { type = "cc14", channel = 1, cc = { msb = 0x13, lsb = 0x33 } }

cc14 pairs an MSB and an LSB controller into a single 0..1 value: ((msb << 7) | lsb) / 16383. The session tracks the pair per alias and only publishes once both bytes have been seen. msb and lsb must differ. On the map.toml side the alias is bound once, like any absolute leaf. See inputs.

Relative encoders

Set relative on a 7-bit cc endpoint to treat its data byte as a signed tick delta rather than an absolute value. It is only valid on type = "cc".

Mode Decode of data byte v (0..127)
BINARY_OFFSET v - 64; center is 64 → 0.
TWOS_COMPLEMENT Signed 7-bit: 0 → 0, 1..63 → +v, 64..127 → v - 128 (so 127 → -1).
SIGN_MAGNITUDE Bit 6 is the sign, bits 0–5 the magnitude: 0x03 → +3, 0x43 → -3.
jog_turn = { type = "cc", channel = 1, cc = 0x22, relative = "BINARY_OFFSET" }
browse   = { type = "cc", channel = 7, cc = 0x40, relative = "TWOS_COMPLEMENT" }

Identity & matching

A device file is matched against a detected MIDI port if the USB identity matches or the port name matches:

  • USB. When both usb_vid and usb_pid are set, the host must report both and they must be equal. If only one is set, that one must match. If the host cannot read USB ids, the USB path never matches.
  • Name. If midi_name_contains is non-empty, the match succeeds when any entry is a case-insensitive substring of the port name.

The two paths are OR’d; either is sufficient.

Validation rules

device.toml is validated when loaded; a violation is a load error.

  • schema_version must equal 1.
  • id must be non-empty; product_name must be non-empty.
  • Section keys must be deck_1…deck_4, master, sampler, or custom; anything else is rejected, and deck indices outside 1..=4 are rejected.
  • Alias names must be snake_case: non-empty, first character a lowercase ASCII letter, remaining characters lowercase ASCII letters, digits, or underscores.
  • note endpoints require note. cc requires a 7-bit cc (use cc14 for msb/lsb). cc14 requires { msb = …, lsb = … } with msb != lsb.
  • channel must be in 1..=16; note, velocity, and value must be in 0..=127.
  • relative is rejected on anything other than type = "cc" (7-bit).
  • Input MIDI clash. Across the whole file, two input-eligible endpoints may not claim the same identity. That is the same (channel, note) for notes, or the same (channel, cc) for CCs. A cc14 endpoint contributes two CC identities (its msb and its lsb), so both must stay clear of other inputs.

Editor schema

The [toml-schema] table (version, location) is editor metadata pointing at schemas/device.tosd; it is peeled off before parsing and never used at runtime. The .tosd file is the authoritative field list, allowed values, and ranges for autocompletion; it mirrors the Rust validation described above.