djayMidiMapping files

September 9, 2017

I've been using djay 2 for iOS on my tablet for around 5 years, but a few years ago I bought my first MIDI controller, a Samson Conspiracy.

I was curious whether I'd be able to use the Conspiracy with my tablet, as it's Class Compliant (no drivers required). Plugging the Conspiracy in, via the Camera Connection Kit (CCK), other MIDI enabled apps (Korg Gadget, Garage Band, iMPC) were able to receive the MIDI notes and CCs.

I tried the Conspiracy with djay 2, but had no success.

After a little searching on Google I found a solution: a .djayMidiMapping file.

A .djayMidiMapping file is an Apple Property List XML file.

Once you have a mapping file for your controller (more on how to create one below) you copy it to your tablet via iTunes, then plug the controller in, open djay/djay Pro and voilĂ , the app responds to the controller!

Typically to create one, you'd use the MIDI Learn functionality in djay Pro for Windows/macOS, but as the file is just a text file you can create it yourself.

The core of an Apple Propery List ("Plist") file is:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
</dict>
</plist>

Within the <plist> tags are the guts of the mapping, all inside the <dict> tag.

First you need to define the details of the device so djay knows to match the plugged in device, to that mapping file. This is done with a key/value pair:

<key>USBID</key>
<integer>123456</integer>
<key>editor</key>
<string>djay Pro-1.2.1</string>
<key>endpointName</key>
<string>Conspiracy</string>
<key>schemeVersion</key>
<integer>1</integer>
<key>version</key>
<integer>0</integer>

...where 123456 is the USBID of your device (On macOS you can find this in the System Information application)

The main mapping info is a list of <dict> tags inside an <array> with the key: controls. For example:

<key>controls</key>
<array>
    <dict>
        <key>keyPath</key>
        <string>mixer.crossfade</string>
        <key>midiChannel</key>
        <integer>15</integer>
        <key>midiData</key>
        <integer>8</integer>
        <key>midiMessageType</key>
        <integer>3</integer>
    </dict>
</array>

In the above example we're mapping a CC (midiMessageType == 3) value of 8 (midiData) on channel 16 (midiChannel is 0 indexed, meaning channel one is 0, channel two is 1 etc.) to the crossfader (mixer.crossfade)

Below is an example of a mapping for a MIDI note (midiMessageType == 1). This maps MIDI note 0 on MIDI channel 1 to turntable1.playPause. Adding the <key>output</key> value means djay will send MIDI data out to the controller, allowing it to light up the LED on that button/pad if the controller supports it.

<dict>
    <key>keyPath</key>
    <string>turntable1.playPause</string>
    <key>midiChannel</key>
    <integer>0</integer>
    <key>midiData</key>
    <integer>0</integer>
    <key>midiMessageType</key>
    <integer>1</integer>
    <key>output</key>
</dict>

If you have any questions/comments please reach out to me on Twitter