VDJPedia



 ControllerDefinitionMIDI

Definition for MIDI Controllers in Version 7


The Controller Definition File for a MIDI controller is a XML file installed in MyDocuments/VirtualDJ/Devices/ folder on PC or /users/YOURNAME/Documents/VirtualDJ/Devices/ on Mac, with these properties:

The root element of the xml must be <device>, with these properties:
- name: unique string that identifies the controller, as will be used in the mapper
- author: (optional) name of the author of this xml file
- type: must be "MIDI"
- decks: can be "1" if the controller represents one deck, or "2" if it controls both decks at once.
- sysexid: (optional) answer to the Identity Request SysEx (see "identification" below)
- vid: (optional) VendorID of the device
- pid: (optional) ProductID of the device
- drivername: (optional) name of the driver
- macdrivername: (optional) name of the Mac OSX driver (if different than the PC name)
- drivernameout: (optional) name of the output driver if different
- midiin: (optional) number of the midi input interface on this computer
- midiout: (optional) number of the midi output interface on this computer
- sysexquery: (optional) SysEx to send to test for the device
- sysexanswer: (optional) SysEx to expect as an answer for this device

Example:
<?xml version="1.0" encoding="UTF-8"?>
<device name="MYCONTROLLER" author="Me" type="MIDI" decks="2" sysexid="F07E??06020001020304" drivername="My MIDI Controller">
<button note="0x01" name="CUE" channel="0" deck="1" />
<button note="0x01" name="CUE" channel="1" deck="2" />
<button note="0x02" name="PLAY" channel="0" deck="1" />
<button note="0x02" name="PLAY" channel="1" deck="2" />
<led note="0x01" name="LED_CUE" default="CUE" channel="0" deck="1" />
<led note="0x01" name="LED_CUE" default="CUE" channel="1" deck="2" />
<led note="0x02" name="LED_PLAY" default="PLAY" channel="0" deck="1" />
<led note="0x02" name="LED_PLAY" default="PLAY" channel="1" deck="2" />
<jog cc="0x01" zero="0x40" name="JOG" channel="0" deck="1" />
<jog cc="0x01" zero="0x40" name="JOG" channel="1" deck="2" />
<slider cc="0x02" name="PITCH" channel="0" deck="1" />
<slider cc="0x02" name="PITCH" channel="1" deck="2" />
</device>



MIDI devices tool : Click here to download it.
(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". See below)


Device Identification

In order to be automatically detected by VirtualDJ, the definition file must provide a way to identify if the device is present, and on which MIDI ports.
Several options are possible to achieve this, depending on how MIDI-compatible the device is.

If the device complies with MIDI specifications and answers to Identity Request SysEx ("System Exclusive"), then the best way is to provide the device ID answer.
You can do this by specifying sysexid= in the header with the expected SysEx answer.

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, ...
(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.

Alternatively, if the device doesn't implement any SysEx, you can identify the device by the name of its driver.
Beware though that the driver name on Windows VISTA and Mac OSX can be changed by the user, or might differ on non-english versions of the OS, so this method is not 100% reliable.
To use the driver name as an identification, you can specify drivername= in the header.
If the output interface has a different name than the input, you can also add drivernameout=

If the driver doesn't have a unique name, as a last recourse you can identify the device by its number in the list of MIDI devices.
This would work only on the computer where you create the definition, and only as long as you don't add/remove new MIDI devices on your computer.
This form of identification can therefore be used only for development purpose, during the development and test stages of the controller.
To use this, specify midiin= and midiout= in the header.

Alternatively, if you don't provide any form of identification, 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.


MIDI Items

Each button, slider, knob, LED, LCD, etc, will be defined by a child item of the <device> element.
All elements (excepts <init> and <exit>) can implement these properties:
- name: the name of this element, as will be used in the mapper
- deck: (optional) the deck on which this element apply, if the device controls two decks
- channel: (optional) the MIDI channel (if you need to differentiate between different channels)


Buttons
A button is defined by a <button> element, with the following properties:
- note: the MIDI note
- inverted: (optional) set to "true" if the device sends note-off when pressed and note-on when released

example:
<button note="0x1F" name="PLAY" deck="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
- off : the off value of the MIDI cc

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


Sliders
A slider is defined by a <slider> element, with the following properties:
- cc: the MIDI cc
- ccmsb: (optional) the MIDI cc of the MSB (for 14-bit MIDI)
- min: (optional) value corresponding to 0% (default 0)
- max: (optional) value corresponding to 100% (default 0x7F)
- zero: (optional) value corresponding to 50%
- inverted: (optional) set to "true" if the slider is bottom-up

example:
<slider cc="0x42" name="VOLUME" />


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" />



Jog Wheels
A jog wheel is defined by a <jog> element, with the following properties:
- cc: the MIDI cc
- inverted: (optional) set to "true" if the jog is inverted
- zero: set the cc value that represents zero. For a jog that sends 0x01 for forward movement and 0x7F for rewind, set this to "0" (default). For a jog that sends 0x41 for forward movement and 0x3F for rewind, set this to "0x40"
- full: set to the number of steps sent while performing a full rotation (by default 128)

example:
<jog cc="0x24" 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

If the jog wheel sends MIDI notes for forward and backward movement, you can define it using the following:
- note: the MIDI note for forward movement
- inverted: the MIDI note 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" />



Encoders
If the encoder sends messages for increments and decrements of its position, you can defines it with a <encoder> element, with the following properties:
- cc: the MIDI cc
- inverted: (optional) set to "true" if the jog is inverted
- zero: set the cc value that represents zero. For a jog that sends 0x01 for forward movement and 0x7F for rewind, set this to "0" (default). For a jog that sends 0x41 for forward movement and 0x3F for rewind, set this to "0x40".
- max: (optional) specifies the value at which the encoder wraps

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


LEDs
a LED is defined by a <led> element, with the following properties:
- note: the MIDI note
- default: (optional) gives the name of the corresponding <button> element. If the mapper doesn't specifically provide an action for this LED, the action of the button will automatically be used to get the state of the LED.
- zero: (optional) a different "value" to send when turning the LED off (For dim illumination of the LED)
- min / max: (optional) sets the minimum and maximum velocity values to send to the LED (For LED's that support different levels of intensity.)

example:
<led note="0x42" name="LED_PLAY" default="PLAY" />


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

If the LED requires SysEx MIDI code to be sent, see "SysEx" below.


Digits
Digits on a LCD are defined by a <digit> element, with the following properties:
- cc: the MIDI cc
- blank: (optional) the value to send not to display any digit
- ccmsb: (optional) the MIDI cc where to send the MSB
- ccmsb2: (optional) the MIDI cc where to send the MMSB (value/(base*base))
- base: (optional) the base by which to compute what is LSB and what is MSB (by default 100)
- multiply: (optional) if you want to display one decimal digit, set this to "10"
- max: (optional) the maximum value that can be sent (after applying the multiplier)
- ccsign: (optional) the MIDI cc that controls the + or - sign
- signplus: (optional) the value to send to the sign CC to set "+"
- signminus: (optional) the value to send to the sign CC to set "-"
- sendstatic: (optional) if set to "true", the cc will be sent once on init, even if it's 0


Progress bars and VU meters
Progress bars are defined by a <bar> element, with the following properties:
- cc: the MIDI cc
- min: (optional) value to send for 0% (default 0)
- max: (optional) value to send for 100% (default 0x7F)
- inverted: (optional) invert the direction of the bar
- mask: (optional) mask to apply to the value to send
- ccoff: (optional) MIDI cc where to send the value before it changes

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


Text displays
Text displays are defined by a <text> element, with the following properties:
- cc: the MIDI cc for the first character
- size: the number of characters
- encoding: (optional) the encoding to use (can be "urf8", "iso-8859-1", "ascii", etc)
- scroll: set to "false" to prevent the display from scrolling too long strings (default is "yes")

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 offest (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.)


SysEx commands
If the device requires SysEx initialization, you can use <init> elements, with the following properties:
- sendsysex: the list of hexadecimal values to send

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:
- 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

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.

Go Back to Controller Definition Wiki page

Wiki HOME