Overview
How a mapping bundle is packaged, where Mixar reads it, and how to attach, trust, and update it.
A MIDI mapping teaches Mixar how one specific controller is wired. It records which note or CC each physical control sends and what that control should do in the app. It also records which LEDs Mixar drives back. A mapping is a directory (a bundle), not a single file, and the directory name is the mapping id used everywhere in the app.
| File | Required | Purpose |
|---|---|---|
device.toml |
yes | Hardware identity plus one endpoint per physical control |
map.toml |
yes | Binds each control to a Mixar action and (optionally) an LED output |
script.rhai |
no | Optional Rhai script for behavior the declarative bindings cannot express |
Bundle layout
Every bundle is a directory containing two required files and one optional file:
mappings/
└── dj-controller/ # folder name = mapping id
├── device.toml # required — identity + control endpoints
├── map.toml # required — inputs → actions, outputs → LEDs
└── script.rhai # optional — scripted behavior
Keep these two identities apart:
- The bundle id is the folder name (for example
dj-controller). Settings and the attach/detach controls operate on it. - The
device.tomlid(for examplepioneer.ddj-400) is the device identity. It is the key used for Trust, not the id shown in the Mappings list.
Where Mixar reads bundles
Mixar reads mappings from app data, not from the repository or the app bundle. The path is {app support}/mappings/<id>/. On Linux with the app id top.mixar.app it is:
~/.local/share/top.mixar.app/mappings/
At start-up Mixar scans each subdirectory there and loads every bundle it finds. A bundle needs both device.toml and map.toml. A directory that fails to load is skipped with a warning and does not appear in the app.
Mixar also seeds app data from its built-in mappings at start-up: any built-in mapping missing from {app support}/mappings/ is copied in. An existing folder is never overwritten, so your edits and the mappings you add yourself survive.
How a port finds a bundle
Each live MIDI port is matched to a bundle by midi_name_contains, plus the optional USB VID/PID in device.toml. A match associates that port with the bundle’s mapping id, which is the id the attach controls operate on.
Managing bundles in the app
Attaching, trusting, and updating happen in Settings ▸ Controllers.
The Mappings list shows one row per bundle found in app data:
| Control | Effect |
|---|---|
| Attach / detach toggle | Enables or disables the mapping against its matched live input port. Unavailable while no controller host is running. |
| Trust toggle | Adds or removes the bundle’s device.toml id from the trusted list. Saved with settings; the device then auto-enables on connect. |
| Update | Re-copies this mapping, picking up a newer version if one is available. |
| Update All (list header) | Re-copies every mapping, picking up newer versions. |
A row shows the bundle’s mapping_version (for example v1.0.0) when it sets one. The row flags Update available when a built-in mapping ships a newer version. Mappings you add yourself are never flagged.
A matched device that is trusted attaches automatically when it connects. A device that is recognized but not trusted is offered here; attach and trust it, and later connects auto-attach. Detaching suppresses that port until it is disconnected and reconnected.
The MIDI ports list shows each detected port as direction port-name → matched-mapping-id. The → <id> suffix appears only when the port name matches a bundle; unmatched ports show no arrow. Direction is input or output. The list refreshes live from attach/detach events. Empty states read “No mappings in app data yet.” and “No MIDI ports detected.”
A minimal bundle
The smallest useful bundle is one deck’s worth of controls. This example maps play/pause, headphone cue (PFL), one hot-cue pad, jog turn, and volume with a shift modifier to filter. It also maps library browse and the play/PFL/hot-cue LEDs. Create a folder named minimal-controller under {app support}/mappings/ and drop in these two files.
device.toml:
schema_version = 1
id = "example.minimal"
vendor_name = "Example"
product_name = "Minimal Controller"
# Port names containing any of these strings match this bundle.
midi_name_contains = ["Minimal"]
[toml-schema]
version = "1.0.0"
location = "schemas/device.tosd"
[deck_1]
play_pause = { type = "note", channel = 1, note = 0x0B }
volume = { type = "cc", channel = 1, cc = 0x13 }
headphone_cue = { type = "note", channel = 1, note = 0x54 }
pad_1 = { type = "note", channel = 1, note = 0x2E }
jog_turn = { type = "cc", channel = 1, cc = 0x22, relative = "BINARY_OFFSET" }
play_led = { type = "note", channel = 1, note = 0x0B, velocity = 0x7F, direction = "out" }
pause_led = { type = "note", channel = 1, note = 0x0C, velocity = 0x7F, direction = "out" }
pfl_led = { type = "note", channel = 1, note = 0x54, velocity = 0x7F, direction = "out" }
hot_cue_1_led = { type = "note", channel = 1, note = 0x2E, velocity = 0x7F, direction = "out" }
vu_meter = { type = "cc", channel = 1, cc = 0x02, direction = "out" }
[master]
browse = { type = "cc", channel = 7, cc = 0x40, relative = "TWOS_COMPLEMENT" }
[custom]
shift = { type = "note", channel = 1, note = 0x3F }
map.toml:
schema_version = 1
[toml-schema]
version = "1.0.0"
location = "schemas/map.tosd"
[inputs.deck_1]
play_pause = "Deck(_)::toggle_play"
headphone_cue = "Deck(_)::set_headphone_cue"
pad_1 = "Deck(_)::hot_cue_pad(n:1)"
jog_turn = "Deck(_)::jog_turn"
volume = [
{ action = "Deck(_)::set_volume", soft_takeover = true },
{ action = "Deck(_)::set_filter", modifier = "custom.shift", soft_takeover = true },
]
[inputs.master]
browse = "LibraryNavigation::navigate"
[outputs.deck_1]
play_pause = { signal = "playing", on = "play_led", off = { type = "note", channel = 1, note = 0x0B, velocity = 0x00 } }
headphone_cue = { signal = "headphone_cue", on = "pfl_led", off = { type = "note", channel = 1, note = 0x54, velocity = 0x00 } }
hot_cue_1 = { signal = "hot_cue_1", on = "hot_cue_1_led", off = { type = "note", channel = 1, note = 0x2E, velocity = 0x00 } }
What each part does:
device.tomlcarries the identity (id,vendor_name,product_name,midi_name_contains) and one named endpoint per control:play_pause,headphone_cue,pad_1,jog_turn, and so on. Endpoints markeddirection = "out"are outputs Mixar drives, such as the LEDs andvu_meter.map.tomlbinds those endpoints to actions:Deck(_)::toggle_play,Deck(_)::set_headphone_cue,Deck(_)::hot_cue_pad(n:1),Deck(_)::jog_turn. The_is the deck placeholder.volumeis a two-entry list: the default action isset_volume, and while thecustom.shiftmodifier is held it becomesset_filter. Both usesoft_takeoverso the hardware knob and the software value do not fight.browseis bound toLibraryNavigation::navigateunder the master input section. It browses whichever library pane owns focus.LibraryNavigation::focus_next/focus_prevare the press-and-SHIFT-press bindings that move focus between the sidebar and the track list (the DDJ-400’s rotary selector).[outputs.deck_1]mirrors player state onto the LEDs: play/pause swaps betweenpause_ledandplay_led, and the PFL and hot-cue-1 LEDs follow their controls. Anonoroffmay name a device endpoint or inline a raw note.- The
[toml-schema]tables are editor hints (schema autocompletion); Mixar ignores them at runtime.
Where to go next
The reference pages follow the order you author a bundle:
- device.toml reference: identity fields, sections, endpoint fields, and validation rules.
- map.toml: inputs: binding forms, modifiers, soft takeover, absolute vs relative inputs, rate limiting.
- map.toml: outputs: signal catalog, LED modes (
on/off/blink), caching and refresh rules. - map.toml: lifecycle: the three script hooks and their session semantics.
- Actions & aliases: the action-id grammar and the closed alias catalog.
- Scripts: Rhai hooks for behavior beyond declarative bindings.
- Validation:
map-checkand common errors.