VDJPedia

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

• <device>
  The <device> line holds all the identifiers that will secure the unique and proper detection of a controller, and has the following parameters.
  
  
  
  • 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.
    
  • Unique Identifiers
    [list]
  • vid pid - Detect device by vid/pid. Whenever available, include this, preferred and safer detection for Windows 7 and later E.g. vid="0x06F8" pid="0xB109"
    
  • sysexid - Detect device by sysex id. E.g. sysexid= "F07E??060200014E0200090001000000F7"
    
  • drivername, drivernameout, macdrivername, macdrivernameout
    Detect device by the device's midi name. Optionally drivernameout and macdrivername can be provided in case they are different.
    
  • identifier - Use this in combination with vid/pid to extract a vid/pid from a driver address that does not contain it. E.g. when the driver's path is \\?\usb#mydevicename#9&29ce5e5a&0&0000#{6994ad04-93ef-11d0-a3cc-00a0c9223196}\global, use identifier="#mydevicename#
    
    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.
    
    
    
  • How to get the Unique Identifiers :
    VirtualDJ provides an implemented tool to get all the information that your Audio, MIDI and HID devices offer. Open VirtualDJ, 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.
    
    
  • How to get the sysexid value :
    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.
    

• <audio>
  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.
  
  • description - Provide a name that will be shown in the "special" button in the Audio tab of Config. It is possible to use \n if the name would be too long to fit properly on one line.
    
  • image - (Optional) Name of the Image shown in the audio configuration for this controller. E.g. image="mycontroller.png". It will look for a .png file with this name in the /Devices folder. If not provided, it will look for a png file with the same filename as the definition file.
    Alternatively, the image can be base64 encoded and embedded in the xml by using image="embedded://base64encodedstring"
    
  • input Provide the number of (stereo) inputs available for this device.
    
  • output - Provide the number of (stereo) outputs available for this device
    
  • mic - [Yes/No] Define, if this device has a microphone input that should be configured (default is No)
    
  • linein - Define the number of line inputs that should be configured for this device. E.g. linein="2" will auto create linein1 and linein2 in the audio configuration of this unit.
    
  • timecode - Define the number of time code inputs that should be configured for this device
    
  • record - If the unit offers a dedicated Record Input, define the channels that will be used as a Record Loopback. E.g. record="11,12" will set Input channels 11 & 12 as Recording Input.
    
  • sampler - If the unit offers a dedicated Sampler Output, define the channels that will be used for Sampler Output. E.g. sampler="9,10" will use output channels 9 & 10 to output Sampler.
    
  • booth - If the unit offers a dedicated Booth Output, define the channels that will be used for Booth Output. E.g. booth="7,8" will use output channels 7 & 8 to output Booth.
    
  • mixer - [Yes/No/Internal] If set to yes, master and headphones output will be created. If set to no, deck 1, deck 2 outputs will be created. If set to internal, deck 1 and deck 2 outputs will be created and its used when the device mixes the channels instead of the computer (fake mixer)
    
  • asio - Name of the ASIO driver for this device. E.g. asio="Pioneer DDJ-SX ASIO"
    
  • coreAudio - Name of the mac core audio name of the device. Only required if the name is different from the midi name, and the device is not found without.
    
  • vid pid mid - vid/pid of this devices sound card (for wasapi when asio is not available and for detecting if the device is connected or not)
    vid/pid are required for any sound config
    optionally, some devices may also require mid (usually not)
    
  • vid2 pid2 mid2 - When the different output channels are shown as separate sound cards, sometimes they get a different pid and/or mid
    
  • identifier - Optional, for some devices, the pid/vid cannot be found in the device instance id. In this case, use a unique string inside the device instance id as identifier. The vid/pid can be copied from the midi part in this case. E.g. ideintifier=" #NUMARKV7AUDIOADAPTER#"
    
  • asioOnly - If a sound card doesn't show up as a usbAudio on windows, set this to "Yes", so that the vid/pid listed should be looked for in the USB MEDIA class, instead of usbAudio devices
    
  • controllerIdentifier - If no vid/pid's or other identifiers are available, this can be used to say that the audio device is available if the controller with name NAME is available (the name="" entry of the device description above)
    
  • outputChannels - Optional when using default order. Use this to re-order the Output channels. E.g. in case Channels 3,4 should be used first for master out, and Channels 1,2 for headphones have outputChannels="3,4,1,2" (default is 1,2,3,4).
    
  • inputChannels - Optional when using default order. Use this to re-order the Input channels. E.g. in case Channels 3,4 should be used first for Linein 1 or Timecode 1, and Channels 1,2 for Linein 2 or Timecode 2 have inputChannels="3,4,1,2" (default is 1,2,3,4).
    
  
  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" >
  </audio>

• MIDI elements
  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:
    [list]
  • 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 additional 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="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"/>

  
  
• 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%
    
  • zerorange - (optional) threshold value for zero="" corresponding to 50%. E.g. zerorange="2" and zero="0x40" considers values from 0x3E (-2) to 0x42 (+2) as center 50%.
    
  • inverted - (optional) set to "true" if the slider is bottom-up
    
  • 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.
    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" />

  
  
• Touch Strips. A Touch-Strip which offers cc notes (0x00 to 0x7F) and an additional note when touched/released can be defined as a <touchtrip> element if you wish to provide "relative" actions (will start interpret the received cc starting from the touched-point) with the following properties:
  
  • cc - the MIDI cc that the Touch-Strip sends
    
  • note- the additional note that the Touch-Strip sends when touched
    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
  
  
• 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" 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" />

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

  
  
• LEDs. A LED is defined by a <led> element, with the following properties:
  
  • note - the MIDI note
    
  • noteoff - (optional) a different MIDI note to which to send "value" to turn the LED off
    
  • 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.)
    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.
  
  
• 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.
    
  • fill - (optional) Set to No if you want the bar to indicate only its peak.
    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"/>

  
  
  
• RGB - Multicolor LEDs Leds that can offer various colors can be defined with a <color> element with the following properties:
  
  • ccred - MIDI cc for the red color intensity
    
  • ccgreen - MIDI cc for the green color intensity
    
  • ccblue - MIDI cc for the blue color intensity
    
  • default - Provide the name of the key that the LED will follow if no action is assigned to the LED
    
  • defaultcolor - Provide the color that the LED will get if no action is assigned to and its default="" key returns 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"/>
   <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" />

<init sendsysex="F00001020304057F" />

  <ledsysex value="F000014E10020F00010000000000F7">
     <led sendstatic="true" name="VELOCITY_SAMPLER" bit="0x57" deck="1"/>
  </ledsysex>