VDJPedia

Quick Sign In:  


 ControllerDefinitionMIDI

Back to Controllers Developing Wiki HOME

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.



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

    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.

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


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


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


  • 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:
      [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">
    <led sendstatic="true" name="VELOCITY_SAMPLER" bit="0x57" deck="1"/>
    </ledsysex>
    [/list]
    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:

    Back to Controllers Developing Wiki HOME