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_vidandusb_pidare 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_containsis 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_versionmust equal1.idmust be non-empty;product_namemust be non-empty.- Section keys must be
deck_1…deck_4,master,sampler, orcustom; anything else is rejected, and deck indices outside1..=4are rejected. - Alias names must be snake_case: non-empty, first character a lowercase ASCII letter, remaining characters lowercase ASCII letters, digits, or underscores.
noteendpoints requirenote.ccrequires a 7-bitcc(usecc14for msb/lsb).cc14requires{ msb = …, lsb = … }withmsb != lsb.channelmust be in1..=16;note,velocity, andvaluemust be in0..=127.relativeis rejected on anything other thantype = "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. Acc14endpoint contributes two CC identities (itsmsband itslsb), 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.
Related
- map.toml: the behavioral half, and its keys.
- map.toml: inputs: binding aliases to actions, and the input-side checks.
- map.toml: outputs: the LED targets these endpoints feed.
- Validation:
map-checkoutput for the rules above.