User Tools

Site Tools


This is an old revision of the document!

MIDI Crash Course

MIDI (Musical Instrument Digital Interface) is a standard for electronic musical devices to communicate. This page is a brief introduction to MIDI that should explain what you need to know to map MIDI controllers to Mixxx.

MIDI is a widely used standard that a lot of hardware and software support. It dates back to the 1980s when it was used to make synthesizers, samplers, and sequencers communicate. These older devices used cables with 5-pin DIN connectors to carry MIDI signals. Most MIDI devices today send the MIDI signals over a USB cable. Some modern devices can also can use cables with the 5-pin DIN connectors. DJ controllers with these 5-pin DIN connectors do not ordinarily use them to send signals to the computer; they are used to communicate via MIDI with other gear and the ability to use MIDI without being plugged into a computer (although they need to be plugged into another power source without a USB cable supplying power).

Controllers that comply with the USB MIDI class standard (also called “class compliant” devices) do not require any special drivers. Most controllers are USB MIDI class compliant, but not all. See the Mixxx DJ Hardware Guide for information about particular controllers.

Mixxx displays the numbers in MIDI signals in hexadecimal. If you are unfamiliar with hexadecimal numbers, read this tutorial.

An explanation of the MIDI signals that your controller sends to computers and how it reacts to MIDI signals that computers send to it should be available from the controller manufacturer. This is likely in a document on the product page for your controller on the manufacturer's website or in the support section of the website. If it is not in a separate document, it is likely at the end of the manual. Unfortunately, not every manufacturer provides this information.

MIDI Messages

Most MIDI messages are three bytes long. The first byte of any MIDI message is called the Status byte. The first nybble (hex digit) is the op-code and the second is the MIDI channel number. So if you have 0x90 the op-code is 0x9 and the channel number is 0x0 (Ch 1.) The full list of MIDI messages is below, where n represents the channel number (0..F inclusive):

StatusFunctionData bytes
0x8nNote offNote numberNote velocity
0x9nNote onNote numberNote velocity
0xAnPolyphonic after-touchNote numberAmount
0xBnControl/mode changeControl numberValue
0xCnProgram changeProgram number(n/a)
0xDnChannel after-touchAmount(n/a)
0xEnPitch wheelLSBMSB
0xF0System Exclusive messageVendor ID(data)
0xF1MIDI Time Code Qtr. Frame(see spec)
0xF2Song Position PointerLSBMSB
0xF3Song SelectSong number(n/a)
0xF6Tune request(n/a)
0xF7End of SysEx (EOX)(n/a)
0xF8Timing clock(n/a)
0xFEActive Sensing(n/a)
0xFFSystem Reset(n/a)

The boldface entries in the table above are the messages we are most concerned with since most DJ controllers use only these for all functions. You'll need to consult the MIDI spec for the DJ controller you're working with to determine which messages and note/control numbers correspond to the DJ controller functions & LEDs. If your controller's MIDI spec gives only note names and not numbers, use this table to convert them. To convert from decimal to hex, use this.

(Note that in order to use System Exclusive messages, you will need MIDI Scripting.)

Typical MIDI signals used by DJ controllers

Every controller works differently, but these are some typical patterns.


  • When pressed: Op-code 0x9, value of 0xf7
  • When released: Op-code 0x9, value of 0x00
    • or Op-code 0x8, value of 0x00


If there's a LED behind the button, usually it can be controlled by sending a message to the controller using the same status and note number that the controller sends when the button is pressed. As for the value field, for LEDs that can only be turned on or off, typically 0x00 turns it off and 0x01 or 0x7F turns it on. For multi-color LEDs, the color is typically controlled by sending different values. Which ones correspond to which colors should be in the MIDI specification document for your controller. If they are not, you will have to look at mappings for other DJ software, or just try a few different values.

Knobs & sliders

These usually send messages with an op-code of 0xB and a value corresponding to the absolute position of the knob or slider (between 0x00 and 0x7F

Endless knobs/encoders (that you can turn continuously) typically send messages with an op-code of 0xB and the value only indicates whether the encoder is being turned left or right (0x01 & 0x7F or 0x41 & 0x3F)

Jog wheels, touch strips, platters

These usually operate exactly like endless knobs/encoders above, and they usually also send messages just like buttons above when they're touched or released which is intended to mark when scratching begins and ends respectively.

Sniffing your controller with Mixxx

First, try using the MIDI Learn functionality in the Preferences→MIDI Devices window at the bottom. It will help you get many of the essential functions mapped quickly without having to manually edit XML.

Unfortunately, some manufacturers do not provide information about the MIDI signals used by the controllers they make. In that case, you have to see what signals the controller sends to be able to map it, which you can do with Mixxx. Even if the manufacturer does provide MIDI documentation, it may be easier to sniff your controller with Mixxx than keep looking up numbers in the controller's documentation.

  1. Start Mixxx from a command prompt using the --controllerDebug option like so:
    • Linux:
      [email protected]:~$ mixxx --controllerDebug
    • Windows:
      C:\Program Files\Mixxx>mixxx --controllerDebug
    • Mac OSX:
      $ open -a mixxx --args --controllerDebug
  2. Look at the output
    • Watch the console output or look at the Mixxx.log file which will contain all of the MIDI messages Mixxx receives. As you manipulate the controller, the MIDI commands it sends will be printed to the screen/logged to the file. Compare the status (first) byte in each line with the table above and note which button/slider/control sends what message.
    • For example, when you move a slider, you might see
      Debug: [...]: "MIDI ch 1: opcode: B0, ctrl: 2, val: 3D" 
      Debug: [...]: "MIDI ch 1: opcode: B0, ctrl: 2, val: 3A" 
      Debug: [...]: "MIDI ch 1: opcode: B0, ctrl: 2, val: 3D" 
      Debug: [...]: "MIDI ch 1: opcode: B0, ctrl: 2, val: 3B" 
      Debug: [...]: "MIDI ch 1: opcode: B0, ctrl: 2, val: 3C" 

In this instance, it's sending 0xB0 (which when we look at the table above, we see that it's a Control Change message on channel 1) We also see that the second byte, 0x02 in this case, is the control number that was moved, and the third is the value or position of that control, which you can ignore for the purposes of mapping.

  1. Add the byte values to a <control> block in the XML file

Sniffing MIDI messages sent your controller by commercial DJ applications

If you're running Linux, you can eavesdrop on the MIDI messages that are sent to your controller.

First, you need to load the kernel module that allows monitoring the USB connection:

$ sudo modprobe usbmon

Now run lsusb to find out with USB bus your controller is connected to, e.g.:

$ lsusb
Bus 001 Device 016: ID 0582:0208 Roland Corp. DJ-505

The controller in the example is connected to Bus 001, which means that you need to use the usbmon1 interface for capturing data.

Next, you can start monitoring the outgoing USB packets by using tshark or Wireshark. If you're using the former, just run:

$ tshark -i usbmon1 -Y 'usb.capdata && usb.src == host' -e usb.capdata -Tfields
Capturing on 'usbmon1'

This will print all outgoing USB packets on interface usbmon1 that have a usb.capdata field (that contains the MIDI messages).

The captured data will start with an extra byte which you'll have to ignore, e.g.:

Captured USB dataMIDI message
0990007f 90 00 7f
0bbf6400 bf 64 00
09900100 90 01 00

You can now start the application, either directly (if it runs on Linux) or in a virtual machine running Windows (e.g. VirtualBox or qemu/KVM/virt-manager). Note that you have to [redirect the USB device to the virtual machine]( to be able to access the controller from the VM.

Additional MIDI tools


Open a console and issue amidi -l. This will list the attached MIDI device(s) like so:

Dir Device    Name
IO  hw:1,0,0  SCS.3d MIDI 1

Then, to dump the data, you just issue amidi -p hw:1,0,0 -d (Replace hw:1,0,0 with whatever device ID your controller shows in the list.) You'll get output like this:

B0 02 3D
B0 02 3A
B0 02 3D
B0 02 3B
B0 02 3C

See above for how to interpret this data.

amidi can also be used to send MIDI messages to your controller with the -S option. Specify each byte as a hexadecimal number and separate the bytes by spaces. For example:

amidi -p hw:1,0,0 -S "b0 02 7f"

The program aseqdump works similarly, but is a bit more verbose than a series of hexadecimal numbers:

$ aseqdump -l
 Port    Client name                      Port name
  0:0    System                           Timer
  0:1    System                           Announce
 14:0    Midi Through                     Midi Through Port-0
 20:0    Tweaker                          Tweaker MIDI 1
 20:1    Tweaker                          Tweaker MIDI 2
$ aseqdump -p 20:0
Waiting for data. Press Ctrl+C to end.
Source  Event                  Ch  Data
 20:0   Note on                 0, note 1, velocity 127
 20:0   Note off                0, note 1
 20:0   Note on                 0, note 2, velocity 127
 20:0   Note off                0, note 2
 20:0   Note on                 0, note 3, velocity 127
 20:0   Note off                0, note 3


You can download tail.exe to watch mixxx.log as new messages are added or build Mixxx with scons msvcdebug=1 and run it with the --controllerDebug option. This will cause it to pop up a console window when you run it and the MIDI messages received by your controller will be displayed there.

MIDI OX can intercept MIDI messages from programs other than Mixxx.

Mac OS X

Download the free MIDI Monitor utility and run it. MIDI Monitor is a utility for Mac OS X which displays MIDI signals in a variety of formats. It can watch both incoming and outgoing MIDI streams, and can filter them by message type and channel.

Download the free MIDISimulator utility and run it. MidiSimulator is a tool to test midi devices like pianos or dj controllers. It allows you to receive and send midi events.

Translations of this page:
midi_crash_course.1580828044.txt.gz · Last modified: 2020/02/04 09:54 by hlzhs