Hardware controllers for Deejaysystem(tm) MK2 / VJ2 Ver. 2009.11.11 (c) 1998-2009 Angel García "Edy"   Manual > Hardware controllers > Generic MIDI devices Español

Generic MIDI devices

Deejaysystem can use any controller compatible with the MIDI standard. You only need to write a configuration file in XML format.

MIDI controllers supported by Deejaysystem are defined in the file plugins\MidiDevices.xml. Default control mappings are in the Plugins\MidiDefaults.xml. Do not edit these files because they are updated in each new version of Deejaysystem, and you would lose your changes.

You can write your own definitions of controllers in the file Plugins\UserMidiDevices.xml, with their default mappings in Plugins\UserMidiDefaults.xml. Create the files if they don't exist. Deejaysystem will load them at startup.

Contact us if you want your MIDI controller to be officially supported in Deejaysystem.

MIDI devices definition file

Defines the controls offered by each MIDI device and the data to interact with them. Deejaysystem reads the definitions from the files MidiDevices.xml and UserMidiDevices.xml.

The main section MidiDevices contains a Device section for each supported device. Each Device section contains the subsections Info, Inputs, Outputs and OutputMaps (the latter two are optional).

<MidiDevices>
    <Device>
         <Info>
            ...
         </Info>
         <Inputs>
              <Input ... />
         </Inputs>
         <Outputs>
              <Output ... />
         </Outputs>
         <OutputMaps>
              <OutputMap ... />
         </OutputMaps>
    </Device>
</MidiDevices>

1. The Info section

Provides data to identify the device:

<MidiDevices>
    <Device>
        <Info>
            <Name>Numark Omni Control</Name>
            <PrefixId>NMC</PrefixId>
            <MidiInName>Numark OMNI CONTROL MIDI</MidiInName>
            <MidiOutName>Numark OMNI CONTROL MIDI</MidiOutName>
        </Info>

A device may have several MIDI names:

    <Device>
        <Info>
            <Name>Hercules DJ Console Mk2 / DJ Control MP3</Name>
            <PrefixId>HDC</PrefixId>
            <MidiInNames>
                <MidiName>Hercules DJ Console Mk2 MIDI</MidiName>
                <MidiName>Hercules DJ Control MP3 MIDI</MidiName>
            </MidiInNames>
            <MidiOutName>Hercules DJ Console Mk2 MIDI</MidiOutName>
        </Info>

Identification of the device by vendor and product codes. Also uses an external DLL module for translating MIDI messages:

   <Device>
        <Info>
            <Name>Denon DN-HC4500</Name>
            <PrefixId>DNHC</PrefixId>
            <MidiInVendor>0xFFFF</MidiInVendor>
            <MidiInProduct>0xFFFF</MidiInProduct>
            <MidiOutVendor>0xFFFF</MidiOutVendor>
            <MidiOutProduct>0xFFFF</MidiOutProduct>
            <MidiOutDeviceType>1</MidiOutDeviceType>
            <ExternalModule>MidiDevices.dll</ExternalModule>
        </Info> 

* Mandatory

2. The Inputs section

Defines the available MIDI controls offered by the device and the MIDI data to interpret them. Each control (INPUT) is defined in a subsection Input. The values depend on the type of control.

<Inputs>
    <Input Name="A_MONITOR"
           Type="BUTTON"
           Command="0x0B" 
           Id="0x15"
           Press="0x7F"
           Release="0"
           />
    <Input Name="A_VOLUME"
           Type="ANALOG"
           Command="0x0B"
           Id="0x32"
           Min="0"
           Max="127"
           Default="127"
           NoCenter="1" 
           />
    <Input Name="A_JOG"
           Type="ENCODER"
           Command="0x0B"
           Id="0x36"
           Mode="1"
           Left="127"
           Right="1"
           Pulses="45"
           />
    <Input Name="A_PITCH"
           Type="ANALOGHR"
           Channel="0"
           Command="0x0E"
           Min="0"
           Max="16383"
           Center="8192"
           Invert="1"
           />
       ... 

Values common to all the controls:

* Mandatory

BUTTON type controls

Two-state controls (button, switch...). Generate logical values 0 (off) and 1 (on).

ANALOG y ANALOGHR type controls

They emit a limited range of values (wheel, slider, fader ...). Generate analog logical values from -1.0 (one end of the run), 0.0 (middle), and +1.0 (other end of the run). If NOCENTER is specified they generate values between 0.0 and 1.0.

ANALOGHR controls emit a 14-bit value by combining Data1 (7 bit lower) and Data2 (7 bit higher). Various ANALOGHR controls on the same device differ by the CHANNEL value instead of ID.

ENCODER type controls

Analog wheels that indicate motion in one direction or another (jog-wheel, shuttle-dial...). Generate logical values between -1.0 (left) and +1.0 (right) depending on the speed and direction of the motion. If not moving generate 0.

Operation modes (MODE):

• 0 - Single left-right values. Data2 contains only LEFT or RIGHT.
• 1 - Base 0. Data2 is a 7 bits signed value indicating the units and the direction of motion. 0 means rest.
• 2 - Base 64. Data2 is a 7 bits unsigned value indicating the units and the direction of motion. 64 means rest.

3. The Outputs section

Defines the MIDI outputs offered by the device for display, lights, etc.. and the MIDI data to trigger them. Each output (OUTPUT) is defined with a subsection Output.

<Output Name="A_CUE" Type="BOOL" Channel="0" Command="0x0B" Data1="0x4A" Data1Off="0x4B" Data2="0x26" />
<Output Name="A_TIME" Type="INT" Mode="TRANSLATED" ExternalId="0x01" />
<Output Name="A_DATAREQUEST" Type="CONTROL" Channel="0" Command="0x0B" Data1="0x4A" Data2="0x3C" />

* Mandatory

MIDI operation mode

All the data needed to operate the MIDI output is specified:

<Output Name="A_CUE" Type="BOOL" Channel="0" Command="0x0B" Data1="0x4A" Data1Off="0x4B" Data2="0x26" />
<Output Name="A_PLAY" Type="BOOL" Channel="0" Command="0x0B" Data1="0x4A" Data1Off="0x4B" Data2="0x27" />
<Output Name="A_DATAREQUEST" Type="CONTROL" Channel="0" Command="0x0B" Data1="0x4A" Data2="0x3C" />

TRANSLATED operation mode

Used when multiple MIDI messages are required to act on the value of an output in the device.

The output value is identified with an EXTERNALID value. On each action the function <PREFIX>_MidiProc is invoked in the external module, which will translate the action into a sequence of MIDI messages. This sequence is then sent to the device. PREFIX is defined in the Info section.

 <Output Name="A_TIMEMODE" Type="BOOL" Mode="TRANSLATED" ExternalId="0x00" />
 <Output Name="A_TIME" Type="INT" Mode="TRANSLATED" ExternalId="0x01" />
 <Output Name="A_PITCH" Type="INT" Mode="TRANSLATED" ExternalId="0x02" />
 <Output Name="A_TEXT1" Type="TEXT" Mode="TRANSLATED" ExternalId="0x05" Lines="1" Length="12" />      

The external module is the DLL file specified in the Info section (EXTERNALMODULE). It is necessary only when the device has any output in TRANSLATED mode. Must be located in the same folder as MidiDevices.xml. Contains one or more exported functions as follows:

DWORD __stdcall
HDC_MidiProc(DWORD dwCommand, DWORD dwOutputId, LONG lValue, void* pData, DWORD dwDataSize);

DWORD __stdcall
DNHC_MidiProc(DWORD dwCommand, DWORD dwOutputId, LONG lValue, void* pData, DWORD dwDataSize);

dwCommand: Action to be executed on the output:

dwOutputId: Id of the output specified on EXTERNALID.

lValue: Value to be sent to the output in the action VALUE (dwCommand = 0), or string pointer in action TEXT (dwCommand = 4).

pData:  Pointer to a buffer of SMidiMessage structures. The function should fill one struct for each MIDI message that must be sent in order to implement the action, and return the number of MIDI messages that it has filled.

struct SMidiMessage
       {
       union {
             // Mensaje en bruto

             DWORD dwMessage;

             // Mensaje por componentes

             struct {
                    BYTE  nChannel : 4;    // Status byte
                    BYTE  nCommand : 4;

                    BYTE  nData1   : 7;
                    BYTE  nSpacer1 : 1;    // Always 0

                    BYTE  nData2   : 7;
                    BYTE  nSpacer2 : 1;    // Always 0

                    BYTE  nUnused  : 8;
                    };
             };
       };

dwDataSize: Maximum number of MIDI messages that can be put into the buffer.

Return value: The number of MIDI message that has been filled into the buffer. They will be sent in order to the MIDI device.

4. The OutputMaps section

Associates the data and values of Deejaysystem to the outputs available on the device (as defined in Outputs). Each association or map is made by a subsection OutputMap.

<OutputMaps>
    <OutputMap Source="DjsA_PlayLed" Output="A_PLAY" />
    <OutputMap Source="DjsA_CueLed" Output="A_CUE" />
    <OutputMap Source="DjsA_TimeValue" Output="A_TIME"
               Requires="DjsA_IsTrackOpen" Blink="DjsA_IsTimeBlink" />
    <OutputMap Source="DjsA_TrackValue" Output="A_TRACK" 
               Requires="DjsA_TrackValue" />

Currently available source data (2009.11.11). Those that begin by DjsA_ are also available as DjsB_.

Default MIDI maps file

Defines the default configurations (maps) of the MIDI devices. These definitions are loaded on the frist startup and in Settings > Control > Defaults.

Deejaysystem reads the maps from the files MidiDefaults.xml and UserMidiDefaults.xml.