Skip to content

README.md

Latest commit

 

History

History
60 lines (44 loc) · 5.87 KB

README.md

File metadata and controls

60 lines (44 loc) · 5.87 KB
Raw

Mappers

Real, working VirtualDJ mapper XML files used as ground truth for the mapper file format.

What a mapper is (and is not)

VirtualDJ splits controller support into two layers:

  1. Device definition — declares the hardware: MIDI notes/CCs or HID offsets, LEDs, encoders, value ranges. Built-in definitions ship compiled inside the app (Resources/controllers.dat and Devices/controllers.dat, a non-XML binary), so they cannot be copied here as XML. Custom definitions are XML; the official schema lives on the wiki (ControllerDefinitionMIDIv8.html, ControllerDefinitionHIDv8.html).
  2. Mapper — binds named controls from a device definition to VDJScript. This folder contains real mappers. Root element: <mapper device="" author="" version="" date="">; every binding is <map value="CONTROL_NAME" action="vdjscript" />.

See docs/Mapper XML.md for the format reference.

Local/

Copies of mapper XML from a working local VirtualDJ install (~/Library/Application Support/VirtualDJ/Mappers/, VirtualDJ 8.5.9307 / bundle 18.0.9482, copied 2026-07-12).

author does NOT indicate who wrote a mapping. Do not use it to grade evidence. (Corrected 2026-07-27.) The decisive fact on this install: KEYBOARD - DeathDisco Keybindings v2025.12.xml carries author="Atomix Productions", and its owner confirms the bindings are entirely their own. So the tag can sit on a file whose content is wholly user-written, which is all that is needed to disqualify it as an evidence grade. AKAI APC Mini MK2 - Custom Mapping.xml carries the same tag despite its name.

Why the tag lands where it does is unknown and is not worth guessing at — the two untagged files here (DeathDisco DDJ-GRV6 v1, Factory Default) do not settle it either, and the Factory Default file in particular has a separate documented reason for its missing tag (see below), so it is not independent evidence about tagging at all.

Grade these files by their name and content instead, and default to Local test working example, never Built-in app resource. In particular, never treat a verb name found only in one of these files as evidence that the verb exists — a personal mapping legitimately contains experiments and guesses that were never claimed to work. Verb existence is settled by the binary symbol/string test and the HTTP error-code sweep (see Undocumented VDJScript Candidates.md), not by appearing in a mapping.

The DDJ-GRV6 Factory Default file below holds VirtualDJ's shipped mapping for that controller, but it is a local export, not a shipped file: it was produced on this machine via Settings → Controllers → Factory default → Save (VirtualDJ 2026, bundle 18.0.9482, 2026-07-27) rather than being an app-saved factory file. It is still Built-in app resource-grade — it is VirtualDJ's shipped mapping (e.g. PLAY_PAUSE → pioneer_play), distinct from the user-customized DeathDisco version — but the save did not stamp the author tag, and it contains only the <mapper>, never the compiled <device> definition. See Mapper XML.md §<map> semantics for the export procedure and its save quirk.

File Device Maps Author Notes
Pioneer DDJ-XP2 - Pioneer DDJ-XP2.xml DDJXP2 617 Atomix Factory mapping for a pad controller; ONINIT, SHIFT, LED_*, DNC_* idioms
AlphaTheta DDJ-GRV6 - Factory Default.xml DDJGRV6 293 Atomix (factory, no tag) Shipped factory mapping, exported via Factory default → Save (see note above); PLAY_PAUSE → pioneer_play, pioneer_*/padshift/touchwheel/wheel_mode hardware idioms; mapper firing HTTP-verified on this hardware (docs/VDJScript Local Test Tracker.md §Mapper Firing)

Observed special value="" names across these files: ONINIT, ONEXIT, UNMAPPED, SHIFT, DNC_MODE, DNC_LOADED, plus SHIFT_-prefixed and LED_-prefixed control names.

Do not hand-edit these copies. Refresh from the live Mappers folder when useful, then review the diff.

Quarantine/

Personal/local-authorship mapper files, moved out of Local/ so the ground-truth table above stays official-only (Atomix factory mappings and factory-default exports). These remain real, useful evidence for format idioms (key-name syntax, control-name conventions, ONINIT/ONEXIT structure) but never for verb existence — see the warning above: a personal mapping legitimately contains experiments and guesses that were never claimed to work.

File Device Maps Notes
AKAI APC Mini MK2 - Custom Mapping.xml APCMINI2 301 Grid controller, named "Custom Mapping"; mode switching via global variables + refresh_controller. User-authored.
KEYBOARD - DeathDisco Keybindings v2025.12.xml KEYBOARD 204 Personal keybindings, confirmed by their author; the Atomix author tag is not meaningful here. Useful for key-name idiom (ALT+1, RIGHT ALT, UNMAPPED fallback). Contains experimental bindings such as browser_filter/browser_search, which are not verbs — the mapper-lint warnings on this file are expected personal-authorship artifacts, not reference defects.
AlphaTheta DDJ-GRV6 - DeathDisco DDJ-GRV6 v1.xml DDJGRV6 293 User-authored; heavy ONINIT/ONEXIT setup, setting_setsession, effect_clone.

tools/lint_mappers.py still recurses into this folder (examples/Mappers/**/*.xml), so structural/verb warnings here remain visible — they are just not evidence-grade.