Midi Controller Mapping File Format

MIDI Controller Mapping File Format

Support for additional MIDI devices can be added to Mixxx by creating a new "MIDI preset" file. This file tells Mixxx how to translate, or map, MIDI messages from a controller into commands that Mixxx understands.

The easiest way to create a new MIDI preset is by using the MIDI Learning Wizard in the Preferences > Controllers. This will generate an XML file located in the user controller mapping folder. You can then modify this XML file it creates (or any of the ones that ship with Mixxx or found on the forum) using the information on this page. This will work for most basic functions on most controllers, but most controllers will require some use of MIDI scripting with JavaScript for a complete mapping.

If you are unfamiliar with how MIDI works, see the MIDI Crash Course.

XML Crash Course

Mixxx uses a well defined XML format to store its MIDI mappings. It is easy to learn the basics of XML so you can edit Mixxx mappings. If you know HTML, the language that is used to define web pages, that will help because XML is very similar.

XML is a language for describing data. It does not do anything by itself and it has no predefined uses. Many other programs have their own ways of using XML that convey different information. For example, Traktor TSI controller mapping files are XML files, but Traktor's mapping system is completely different from Mixxx's mapping systems, so TSI files make no sense to Mixxx.

XML files are hierarchies of elements. Elements have starting and closing tags surrounded by angle brackets (also known as less than (<) and greater than (>) signs). The starting tags can be as simple as naming the element surrounded by angle brackets, for example, <group>. Starting tags can also have attributes to specify more detail about the element, for example, in <controller name="Stanton SCS.3d">, name is an attribute of the controller element with a value of Stanton SCS.3d. Ending tags have a slash after the <, for example, </group>. Between the starting and ending tags, elements can contain data or other elements. Empty elements are also allowed, which have a slash before the >, for example, <SelectKnob/>.

Header

Each XML mapping file starts with a header with metadata:

<?xml version="1.0" encoding="utf-8"?>
    <MixxxMIDIPreset schemaVersion="1" mixxxVersion="1.11.0+"> <!-- Schema version number to help compatibility, should the MIDI format change -->
    <info>
        <name>Example MIDI Preset for Mixxx</name>
        <author>Tom Care</author>
        <description>This is an example XML MIDI preset for Mixxx. The scope of the preset could be from a small functionality addition, to a complete mapping for a controller, to a complex personal setup with multiple controllers. This description is intended for distribution and could include comments about the extent of the functionality.</description>
                <wiki>Encoded URL to Mixxx wiki page documenting this controller mapping</wiki>
                <forums>Encoded URL to Mixxx discussion forums page for this controller mapping</forums>
    </info>
    <controller id="controller name"> <!-- Many controllers in one file supported. A controller should only appear once -->

The schemaVersion and mixxxVersion attributes of the MixxxMIDIPreset element are important for future compatibility as the Mixxx MIDI mapping format changes. The child elements of the <info> element are used to display information about the mapping in the Mixxx controller preferences. Note that & is a reserved character in XML, so the URL to the forum thread must use & instead of just &. (When a preset does not have a name in its <info> section, Mixxx 1.11+ use the filename without extension.)

Write the brand and model of the controller (for example, "Stanton SCS.3d") in the id attribute of the <controller> element. The <controller> element is a container for a <controls> element and an <outputs> element, which are described below.

Inputs

The <controls> element tells Mixxx what to do with signals it receives from your controller such as knob turns and button presses. Within the <controls> element, put as many <control> elements as necessary.

        <controls> <!-- One control group -->
            <control> <!-- Several controls -->
                <group>[Master]</group>
                <key>crossfader</key>
                <status>0xB0</status> <!-- CC on channel 1 -->
                <midino>0x07</midino>
                <options>
                    <!-- all control specific options should go here - sensitivity etc. Specifics to be decided by spec -->
                </options>
            </control>
        </controls>

The <group> and <key> elements define the value in Mixxx that this MIDI signal controls. The Mixxx Controls page lists the available values for these group and key elements.

The <status> and <midino> elements define the MIDI signal that Mixxx will listen for. See the MIDI Crash Course for a brief introduction to MIDI signals.

Input options

These are all specified with empty XML elements as children of the <options> element. For example, to use the SelectKnob option, in the XML, write:

                <options>
                    <SelectKnob/>
                </options>

Normal: No modifications
Script-Binding: Bind to a MIDI script function given in the "key" tag. (See MIDI Scripting for details.)
SelectKnob: For relative controls centered on 64 (0x40)
Diff: Adds the current value of a relative control to the previous value
Invert: Subtracts the value from 127, giving an inverted control (-127..0)
Rot64inv: ?
Rot64fast: ?
Rot64: ?
Button: a button has a Down (non-zero) and an Up (zero) state, these occur together when pressed/released, this switch only triggers on the Down, Up is ignored. (Herc)
Switch: a switch has a On (non-zero) and an Off (zero) state, these occur separately. (Herc)
Spread64: Exponential spread either side of 64, aka "relative" controller

Outputs

The <outputs> element defines outputs that use "short" (3-byte) MIDI messages. Use this to control LEDs and other features of your controller to make them react to changes in Mixxx. Within the <outputs> element, put as many <output> elements as necessary. Note that this can only send either of two different values, so it is most useful for LEDs that can only be switched on and off. For other parts of controllers that are controlled with more than two values such as multicolored LEDs or VU meters, you need to use MIDI scripting. Scripting is also necessary for sysex messages.

        <outputs>
            <output>
                <group>[Channel1]</group>
                <key>play</key>
                <status>0x7F</status>  <!-- First byte sent to device -->
                <midino>0x08</midino>  <!-- Second byte -->
                <on>0x01</on>  <!-- Third byte. If not specified, 0x7F is used. -->
                <off>0x00</off> <!-- Alternate third byte. 0x00 is the default. If set to 0xFF, nothing is sent.-->
                <maximum>0.99</maximum>  <!-- Optional upper value for the Mixxx control, above which the 'off' value is sent. 1.0 is the default. -->
                <minimum>0.9</minimum>   <!-- Lower value for the Mixxx control, below which the 'off' value is sent -->
            </output>
        </outputs>

This allows you to send any three bytes to the MIDI controller in the order <status>, <midino>, <on>/<off>. The <minimum> and <maximum> elements define the range of the Mixxx Control's values within which the <on> MIDI value is sent. Outside this range, the <off> MIDI value is sent. If <off> is set to 0xFF, no message will be sent outside the range. (Useful for LED sequences.)