How to add or tweak a controller mapping

Here is the recommended order of things to do to add support for a new MIDI controller to Mixxx. To tweak an existing one, you’ll want to skip step 1 and just start editing the mapping and/or script file(s).

[]Use the MIDI Learn Wizard available on the MIDI controller pane (except in v1.11.x) to map essential controls quickly. After you close Mixxx, find the XML file with your controller name in the controllers sub-directory (midi directory on Mixxx v1.10.x and below) where mixxx.log is located (depends on the OS and Mixxx version…search your computer.) Then copy/move that file to the controllers sub-directory under your Mixxx installation (midi directory on Mixxx v1.10.x and below.)[/]
[]To map additional controls, edit that XML file with your favorite text editor using the information on this wiki page. The page also contains information on how to read the data your controller sends so you know which values to use incase you can’t find the controller’s user guide.[/]
[]For more advanced behaviors, fine-tuning (like for jog wheels) and otherwise full control, use MIDI scripting. Don’t be afraid! It uses an easy-to-learn Javascript-like language that gives you great power.[/]

(Quick links to these pages are on our Wiki’s main page.)

Once you have a mapping (and script file if you made one) that works 100%, please send it to the mixxx-devel mailing list and/or file it as a Wishlist bug so it can be included in a future Mixxx release!

EDIT: updated directory and listed version-specific caveat

Finally, here is a video that walks you through mapping a jog wheel to scratching and pitch-bending from nothing:

It’s really not that bad. Let me know if you have questions!

Very usefull MIDI tool for everybody, who watns to make his own controller’s mapping and script:

Includes MIDI monitor to check controller’s MIDI commands.

got anything to send or monitor LED signals as well?

How can I apply scratching to a physical MIDI-knob? In your video you said it can be done, but it is more in depth than what you are covering… I’m not good with manuels so could you at least summarize how to do it?

Kytrooper: You mean a knob like a volume knob? Something that has a hard top and bottom? If it’s an endless knob, then you can use the exact procedure the video shows.

Is there something like a API specification for MIDI scripting for Mixxx? It’d be interesting to see all the values you could get and set, for instance.

Yes ->

That page is far from complete.

Do you mean it’s missing controls? We try to add them as we update the code on GitHub. I’m about to go through and make sure that some brand new ones for Mixxx 1.12.0 (effects framework, harmonic mixing, master sync, beatjumps, loop move, and talkover ducking) are documented.

However, that page is just a list of the possible controls you can change. For more info about how to use them with mappings or how to write Javascript to control them then click the wiki links in point #2 and #4 of the first post in this thread.

Feel free to post in this forum if you need help. Many of us hang out on IRC if you want to chat :slight_smile:.


Recently bought a Numark MIXTRACK EDGE and am looking to make a map for it for Mixxx since the software it comes with is garbo. There are several buttons on the controller that are supposed to activate different modes for the buttons/jog-wheels. How would one go about coding some sort of conditional function?
(i.e. if the FX key is pressed [status: 0x90; midino:0x1F], the jog wheels [L-- status: 0x1B; midino: 0x25 :: R-- status: 0xB2; midino: 0x25] scratch. When pressed again [status: 0x80; midino: 0x1F], the jog wheels stripsearch.)

Hey, i just bought the same product and having the same issues. Where do you input the mappings manually? it only lets me map it using the wizard.

Please read the first post in the thread.

After you have made a mapping and it has been approved for inclusion in the next Mixxx release, please add it to the appropriate tables DJ Hardware Guide on the wiki. If the controller has an integrated sound card, also add details about that to the appropriate table towards the bottom of the page. Make a new wiki page with the name of the controller. On that page, put a picture of the controller, a link to the page on the manufacturer’s website for the controller, a description of your mapping (and ideally a diagram too), and a link to any documentation (such as the manufacturer’s manual) that you used to make the mapping.

Hello! My name is Marto from Argentina.
I recentely bouhgt an Iconpad controller (not a DJ controller).

The issue is that ribbon faders are detected only as on/off (touch/release) buttons.
When pressed and slide over it, the leds on the ribbon shows the possition you are touching when slide your finger over it, but Mixxx (best DJ softwre ever!!!) only enable the pre-fixed position of the fader on the screen (i.e. Deck A master volume) when you held (and/or move over the ribbon) your finger or mute (the "in screen fader goes to bottom) when you release it, using the built-in midi learn functuion to map it.

Now Im reading all the documentation about midi mapping and scripting, but maybe (not only maybe, I hope) someone here can give me a little kickstarter advice (but not to throw away the device) in how to the make Mixxx (is the best DJ software ever, did I tell it before?) recognize the main function of the ribbon (to be a fader) and not the first data recieved from the device (the I/O finger-press sensor).
Dont have any experience dealing with midi devices, but maybe someone has deal with this issue or similar before, and have a near idea in how to make it works properly.
Im interested in this device because it had:
4 layers of 8 channel ribbon faders+4 control buttons for each+one rotary knob with push function for each
3 layers of 9 customizable pads
and a transport ontrol layer.

It seems very flexible for multipurpose audio working, including simultaneuos control of several software switching between layers.

I saw the Pegasus youtube video for scratching. Helped my a lot to learn how the scripts works.
Im not sure if I have to make a script that ignores the push/release sensor data or make one that took that info as conditional (like a “shift” or “function” key) to allow to move the fader.

Im running Mixxx on a winbug 7 64bit machine.

Thanks a lot in advance!!!

It’s possible that your controller sends both a note on/off MIDI signal when the touch strips are touched and released as well as a control change (CC) MIDI signal indicating where on the strip you are touching. The MIDI Learning Wizard may only be reacting to the on/off signal. If this is the case, you should be able to take care of this with just XML and won’t need scripting. However, you’ll need to edit the XML manually rather than rely entirely on the Learning Wizard. Look at the incoming MIDI signals to Mixxx to figure out what’s going on. See the MIDI Crash Course for instructions on how to view the incoming MIDI signals.

Thanks for your answer!!!
This is what I get from the debugger when touched and slide from bottom to top.
Sorry for the extension.
Could you plesae help me to quick understand what data I have to take from here to use with the XML file?
Thanks again!!

Use the signals with status 0xE0 rather than 0x90. It seems that it’s sending 14-bit pitch bend signals. I’m not sure how to map those. I think the XML format assumes that the second byte (MIDI note) of each message is constant for every component of the controller, so you may need a separate element with a different element for every possible value (0 through 0x7F) :confused: There are fourteen-bit-lsb/fourteen-bit-msb options, but I think those are for controllers that send two separate MIDI messages, each with a constant note number, for a single component of the controller.

Those are mapped in XML just like any other control, except you skip the element. (There is only one 0xEn message per MIDI channel.) Mixxx knows that the next two bytes after an 0xEn are a little-endian 14-bit value per the MIDI standard. (Wiki updated with this info.)


I have a Behringer 1002 desk connected to an audio interface that I want to use for my radio broadcast using Mixx.

Can anyone tell me in ‘Janet and John’ language how to use this as the controller? P.s I am using Mac.