ControllerDefinitionMIDI
Definition file for a MIDI Controller
The Definition File for a MIDI controller is a XML file installed in Documents/VirtualDJ/Devices/ folder and has the following form.
<device ...><audio ... />definition of all MIDI elements</device>
Example :
<device name="DDJSX" author="Atomix Productions" description="Pioneer DDJ-SX" version="800" type="MIDI" vid="0x08E4" pid="0x0171" decks="4" padColumns="4" padRows="2" padSides="2">
<audio description="Pioneer DDJ-SX" input="1" output="2" Mixer ="yes" mic="no" vid="0x08E4" pid="0x0171" asio="Pioneer DDJ_SX ASIO" />
<!-- Buttons-->*
<button note="0x34" name="PLAY_PAUSE" deck="1" channel="1" />
<!-- Sliders-->*
<slider ccmsb="0x08" cclsb="0x28" name="LEVEL" deck="1" channel="0"/>
..
</device>
* The <!-- --> are optional comments, not executable.
- <device>
The <device> line holds all the identifiers that will secure the unique and proper detection of a controller, and has the following parameters.
[list][list] - name - Provide a unique short name for the device, which will be used in the mapping file as well. The name will not be visible anywhere else. (E.g. name="DDJSX")
- type - For a MIDI Controller this must be set as type="MIDI"
- description - Provide a description. This will be visible in the Controllers tab of Config. (E.g. description="Pioneer DDJ-SX"). In v8 it is preferred to give this name in the definition instead of the mapping file because a single device can have multiple mappers.
- version - VDJ version this definition was created for. E.g. version="800"
- decks - Number of decks that can be controlled with this controller. E.g. decks="2" for a 2-sides controller, or decks="1" for a single-deck controller, or decks="4" for a 2-sides controller which offers additional layers for each deck per side.
- singledeck - Set to "yes" if it is a single-deck controller (decks="1") with a switch button to toggle to a second deck. When 1 controller is connected it will switch between 1 and 2, but when 2 controllers are connected, they will switch between 1 and 3, and 2 and 4. Can be used for 2-deck controller that can control 4 decks as well.
- padColumns padRows padSides - (Optional) Define the matrix that the controller provides to control the Sampler. If the controller has sampler pads, provide the number of horizontal pads in one sampler area, the number of vertical pads in one sampler area and the number of the sides. If the controller has a sampler area on each side, the padSides should be 2, if there is only one sampler area on the controller it should be 1. E.g. for the Pioneer DDJ-SX which offers a 4x2 Matrix per side, it should be .. padColumns="4" padRows="2" padSides="2"
- motor - This should be set to Yes (motor="yes") for controllers that have a motorized platter.
In case of 4-deck controller with 2 motors, make sure singledeck="yes" - platform="pc|mac" (Optional). Most of the time this shouldn't be needed, but if a controller has a different driver or firmware for mac or pc, use this to have the definition loaded only on the specified platform. In this case, use 2 definition files for the device, one with platform pc and one with platform mac.
Detect device by the device's midi name. Optionally drivernameout and macdrivername can be provided in case they are different.
If you don't provide any form of identification (vid/pid, sysexid etc) , then this definition file will be applied to all MIDI interfaces that are not matched by another definition. If you need to create a definition file for your own use, you can use this to quickly get your device working.
VirtualDJ 8 provides an implemented tool to get all the information that your Audio, MIDI and HID devices offer. Open VirtualDJ 8, goto the Options tab of the Config and set the setting CreateMidiLog to Yes from the Advanced Options. Close VirtualDJ 8 and make sure your device is properly connected and its drivers are installed. Launch VirtualDJ 8 and then close right after. Open the generated Log Report.txt file you will find in /Documents/VirtualDJ folder to get all the reported data.
Download Miditrace from here. In this tool, "F0 7E 7F 06 01 F7" is the Identity Request SysEx query needed to get the Identity Request SysEx answer to use in "sysexid".
The SysEx answer for an Identity Request should start with " F07E??0602 " (0xF0, 0x7E, <channel>, 0x06, 0x02), then the Manufacturer's ID (on 3 bytes, see some examples here), followed by the Device Family Code, the Device Family Member Code, the Software Revision Level, ... e.t.c. (the ?? means you will detect the device whatever the MIDI channel is)
If the device doesn't answer to standard ID SysEx, but answers to some other proprietary SysEx, you can use it to detect the device. Specify sysexquery= and sysexanswer= in the header, with the required SysEx codes.
[/list][/list]
The <audio> line is optional. If the controller has a built-in sound card, then define its properties using this line, in order a special button in the Audio tab of Config to be offered with a pre-defined audio configuration.
[list][list]
Alternatively, the image can be base64 encoded and embedded in the xml by using image="embedded://base64encodedstring"
vid/pid are required for any sound config
optionally, some devices may also require mid (usually not)
The <audio> definition can be used as a stand-alone definition file to offer a pre-defined audio configuration when the defined sound card is connected. The audio definition follows the above structure, with the difference that a name="" needs to be provided.
Example:
<audio name="TRAKTORAUDIO2" description="Traktor Audio 2" vid="0x17cc" pid="0x041d" identifier="#nita2_avs#" asio="Traktor Audio 2" Mixer ="no" output="2" >[/list]
</audio>
Each button, slider, knob, LED, LCD, etc, will be defined by a child item of the <device> element.
[list]
example:
<button note="0x11" name="PLAY" deck="1" channel="1" />
If the button sends CC MIDI codes instead of note-on/note-off, you can use a <button> element with the following properties:
- cc - the MIDI cc
- value - the on value of the MIDI cc (optional)
- off : the off value of the MIDI cc (optional).
Example:<button cc="0x68" value="0x7F" off="0x00" name="X1" deck="1" channel="1" />
If the button does not send messages on pushed/released, but on on/off, you can use a <toggle> element with the following properties:
- note - the MIDI note
- inverted - (optional) set to "true" if the device sends note-off when activated and note-on when deactivated.
Example:<toggle note="0x4E" name="XFADE_REVERSE" channel="0"/>
If the button sends CC MIDI codes instead of note messages, you can use<toggle cc="0x4E" name="XFADE_REVERSE" channel="0"/>
If the unit sends Midi In using sysex values instead of cc or notes, you can use a <sysexin> element with the following properties:
- sysexid - the sysex value sent from the unit (wild-chars can be used)
Example:<sysexin sysexid="F01452????00F7" name="USB_CONN_A" deck="1"/>
example:
<slider cc="0x28" ccmsb="0x08" zero="0x40" name="EQ_LOW" deck="1" channel="0" />
If a button offers MIDI notes (e.g. a button with MIDI velocity note messages), you can define it using a <slider> as following..
- note - the MIDI note of the button
- min - (optional) value corresponding to 0% (default 0)
- max - (optional) value corresponding to 100% (default 0x7F)
- ghost - (optional) set to "false" if you don't want the slider to offer a ghost fader (and by-pass the soft-takeover). Default is true.
- nozero - (optional) set to "yes" if you don't want the "slider" to return to the zero position.
Example:<slider note="0x01" name="EFFECT_PAD1_VEL" nozero="yes" ghost="no" deck="1" />
If a button offers After-Touch velocity notes you can define it using a <slider> as following..
- aftertouch - the MIDI after-touch note of the button
- min - (optional) value corresponding to 0% (default 0)
- max - (optional) value corresponding to 100% (default 0x7F)
- ghost - (optional) set to "false" if you don't want the slider to offer a ghost fader (and by-pass the soft-takeover). Default is true.
- nozero - (optional) set to "yes" if you don't want the "slider" to return to the zero position.
Example:<slider aftertouch="0x47" name="PAD1_AT_VEL" ghost="no" channel="0" />
If the slider sends MIDI PITCH messages, use a <slider> element with the following properties:
- pitch - set to "true"
- inverted -(optional) set to "true" if the slider is bottom-up
example:<slider pitch="true" channel="1" name="PITCH" deck="1" />
example:
<touchstrip cc="0x02" note="0x06" name="SEARCH_STRIP_REL" channel="1" deck="1" />The additional note can be defined separately as a <button> too
example:
<jog cc="0x24" zero="0x40" full="512" name="JOG" deck="1" />
If the jog wheel sends messages with its absolute position, you can define it with a <fulljog> element, with the following properties:
- cc - the MIDI cc
- ccmsb - (optional) the MIDI cc of the MSB (for 14-bit MIDI)
- inverted - (optional) set to "true" if the jog is inverted
- full - set to the number of steps sent while performing a full rotation (by default 128)
- max - (optional) specifies the value at which the jogwheel wraps
- mask - (optional) set a bitmask to apply to the cc value
- sendstatic - (optional) set to "true" if the wheel reports messages when it doesn't move and you want to receive them.
example<fulljog cc="0x20" ccmsb="0x00" max="512" full="3600" name="JOG" deck="1" channel="1" />
If the jog wheel sends different MIDI notes or cc for forward and backward movement, you can define it using the following:
- note/cc - the MIDI note or cc for forward movement
- inverted/ccback - the MIDI note/cc for reverse movement
- full - set to the number of steps sent while performing a full rotation (by default 128)
example:<jog note=”0x01” inverted=”0x02” full=”128” name="JOG" deck="1" />
<jog cc="0x01" ccback="0x14" full="280" name="JOG" channel="1" deck="1" />
Example:
<encoder cc="0x17" zero="0x40" name="ENC_FOLDER" deck="1" channel="0" />
If the encoder sends messages with its absolute position, you can defines it with a <fullencoder> element, with the following properties:
- cc - the MIDI cc
- inverted - (optional) set to "true" if the jog is inverted
- full - set to the number of steps sent while performing a full rotation (by default 128)
- mask -(optional) set a bitmask to apply to the cc value.
Example:<fullencoder cc="0x15" mask="0x1F" full="20" deck="1" name="SELECT" />
Examples:
<led note="0x42" name="LED_PLAY" default="PLAY" />
<led note="0x67" zero="0x00" min="0x01" max="0x18" name="LED_RING_RED_ROT" channel="1" deck="2" />
If the LED requires CC MIDI code to be sent, you can use a <led> element with the following properties:
- cc - the MIDI cc
- value - the CC value
- ccoff - (optional) a different MIDI cc to which to send "value" to turn the LED off
- zero -(optional) a different "value" to send when turning the LED off (For dim illumination of the LED)
- sendstatic - (optional) if set to "true", the cc will be sent once on init, even if it's 0.
Example:<led cc="0x4A" value="0x5C" ccoff="0x4A" zero="0x2C" sendstatic="true" name="LED_EFX1_BTN" default="EFX1_BTN" deck="1" channel="0" />
If the LED requires SysEx MIDI code to be sent, see "SysEx" below.
Example:
<bar cc="0x50" min="0x0A" max="0x10" ccoff="0x51" fill="yes" name="VU_METER" deck="1" channel="0" />
Alternatively, if the progress bar consists of several LEDs each with an individual MIDI note, you can use a <bar> element with the following properties:
- note - the MIDI note of the first LED
- nb - the number of LEDs (therefore the MIDI note of the last LED will be note+nb-1)
- inverted - (optional) if set to true, the LEDs will be lit from right to left.
Example:<bar note="0x0E" nb="7" name="BAR_LOOPS_REV" channel="0" deck="1" inverted="true"/>
Example:
<color ccred="0x35" ccgreen="0x36" ccblue="0x37" name="LED_DECK_LEFT" deck="1" channel="0" />
For LEDs that offer a MIDI note or cc with the colors defined in velocity you can define the color of each velocity value by providing a pre-defined color, an html color code etc as following:
- note/cc - the MIDI note or cc of the LED
- values - the velocity values and their assigned colors separated by comma (,). Can use :
[list] - pre-defined colors
"red",ARGB(255,255,0,0),
"green",ARGB(255,0,255,0),
"blue",ARGB(255,0,0,255),
"white",ARGB(255,255,255,255),
"black",ARGB(255,0,0,0),
"yellow",ARGB(255,255,255,0),
"cyan",ARGB(255,0,255,255),
"magenta",ARGB(255,255,0,255),
"gray",ARGB(255,127,127,127),
"transparent",ARGB(0,0,0,0)
"orange",ARGB(255,255,127,0),
"darkred",ARGB(255,127,0,0),
"darkgreen",ARGB(255,0,127,0),
"darkblue",ARGB(255,0,0,127),
"darkyellow",ARGB(255,127,127,0),
"darkcyan",ARGB(255,0,127,127),
"darkmagenta",ARGB(255,127,0,127),
"darkorange",ARGB(255,127,63,0), - hex values. E.g. "#102030"
- hex values with transaprency : "#80102030"
- decimal values : "255,255,255"
Examples:
<color note="0x59" values="0x00=#000000,0x01=#FF0000,0x02=#FF7F00,0x03=#7F3F00,0x04=#FFFF00,0x05=#00FF00,0x06=#007F00,0x07=#00FFFF,0x08=#00007F" name="LED_FX_PAD1" deck="1" channel="1"/>[/list]
<color note="0x3C" name="LED_PAD1" default="PAD1" values="0x00=black,0x18=blue,0x28=green,0x38=cyan,0x48=red,0x58=magenta,0x68=yellow,0x70=gray,0x78=white" deck="1" channel="7" />
Examples:
<digit cclsb="105" ccmsb="73" multiply="100" base="128" sign="255" sendstatic="true" name="MOTOR_SPEED" deck="1" />
<digit cc="0x2C" ccmsb="0x4C" base="128" name="DIGIT_BPM" deck="2" channel="1" />
<digit cc="0x2E" ccsign="0x36" signplus="0x01" signminus="0x00" name="LCD_KEY_VALUE" deck="1" channel="0" />
If the MIDI CC don't follow each other in order, you can use instead of cc=
- ccs - list all the MIDI cc, for example ccs="010A12" means CC 0x01 for the first character, CC 0x0A for the second character, CC 0x12 for the third character.
If the characters uses 14-bit MIDI, you can use instead of cc=
- ccs - list all the MIDI cc for the MSB values
- ccs_lsb - list all the MIDI cc for the LSB values
If the text is sent through a sysex, you can use instead of cc=
- sysex - the list of hexadecimal values to send in the sysex
- offset - the offset (in BYTEs) from the beginning of the sysex where to write the text. If offset+size>sizeof(sysex) then the text will be inserted at the offset. Otherwise it will overwrite the text at the offset (You will need to provide a buffer of the appropriate size at the offset, e.g: 20202020202020202020 if size is 10.)
- offsetbit- (optional) the offset (in bits) from the beginning of the sysex where to start writing the text, in case the text doesnt start from the 1st bit of the given byte.
- encoding- can be utf8 (8 bits per character) or utf16 (16 bits per character)
- size - Provide the number of the displayed characters (optional)
Examples:<text sysex="F000013F004002000C202020202020202020202020F7" offset="9" size="12" name="TEXT" deck="1" />
<text sysex="F07D013C62706D3EF7" offset="8" size="32" scroll="false" encoding="ascii" name="LCD_BPM" />
<text ccs="01020304050708090A0B0C0D" ccs_lsb="21222324252728292A2B2C2D" encoding="denon" name="TEXT1" channel="1" deck="2" />
If a sysex carries more than one text that need to be sent, you can nest other <sysex> and/or <digits>
- Example:
<text sysex="F04720330501021F021D0100 ........ F7">
<sysex name="TEXT_TITLE" encoding="utf16" offset="11" offsetbit="1" size="90" deck="1" />
<sysex name="TEXT_ARTIST" encoding="utf16" offset="120" offsetbit="6" size="90" deck="1" />
<sysex name="TEXT_BPM" encoding="utf8" offset="230" offsetbit="4" size="3" deck="1" />
<sysex name="TEXT_KEY" encoding="utf16" offset="237" offsetbit="3" size="8" deck="1" />
<digit name="TEXT_LENGTH" offset="290" nbbits="32" offsetbit="0" deck="1" />
</text>
example:
<init sendsysex="F00001020304057F" />
The <init> elements will be sent in the order they appear in the XML file
If the device requires specific SysEx to be sent on exit, you can use <exit> elements, with the following properties:
- sendsysex - the list of hexadecimal values to send
If the device has a SysEx defined to control the LEDs, you can define a <ledsysex> element, with the following properties:
- value - list of hexadecimal values to initialize the SysEx.
Then, the <ledsysex> element can have child elements <led> with the following properties:
[list] - bit - the position of the bit inside the SysEx that will be set to 1 or to 0 according to the LED status
- name, default, deck - same as regular <led> elements
Example:
<ledsysex value="F000014E10020F00010000000000F7">[/list]
<led sendstatic="true" name="VELOCITY_SAMPLER" bit="0x57" deck="1"/>
</ledsysex>
If the device has other type of SysEx that need to be sent, you can define a <sysex> element, with the following properties:
- value - list of hexadecimal values to send
- name, default, deck - the action that will trigger the sysex to be sent everytimes the action's value goes from 0 to 1 or from false to true.
Example:<sysex value="966F7F" name="DNC_RTNBLACK" default="DNC_BLACK" />
If the device sends Midi In as sysex (e.g. pressing a button provides a sysex instead of a note or cc), you can define a <sysexin> element, with the following properties:
- sysexid - the sysex value you receive
- name - provide a name for the Key
- deck, channel etc -optional (same as buttons and other elements)
Example:<sysexin sysexid="F020010001" name="HOTCUE_MODE" deck="1" channel="0"/>
<sysexin sysexid="F020010002" name="LOOP_MODE" deck="1" channel="0"/>
[/list][/list]
Navigation: