As a relative newcomer to Cocoa and OSX some of Cocoa's frameworks seem very good, some I've looked at are what I expected, but recently I had to do some MIDI work and frankly, CoreMIDI is just weird and confusing. The documentation is limited, to say the least, and really not what I've come to expect from Apple. But I got what I needed done and so this post, more than some others, is to serve two purposes. One, to help me remember what I worked out, and two, maybe it'll help someone else.
I have a few MIDI controllers lying around, and what I wanted to do was to read the MIDI data as the various knobs and faders and buttons are manipulated and have it tell me what was happening.
In CoreMIDI we create input and output ports, and connect them to other ports or endpoints. For our case we want to create an input port, and connect this to the external MIDI controller. When we create an input port we also give it a callback function that will get called when the MIDI controller sends data.
The first step to create an input port is to create a MIDIClient
MIDIClientRef midiClient;
OSStatus result;
result = MIDIClientCreate(CFSTR("MIDI client"), NULL, NULL, &midiClient);
if (result != noErr) {
NSLog(@"Error creating MIDI client: %s - %s",
GetMacOSStatusErrorString(result),
GetMacOSStatusCommentString(result));
return;
}
The first parameter gives the MIDIClient a name and as we're working with CoreFoundation here we use the CFSTR macro. The second and third parameters are for receiving notifications when the MIDI system changes, but we don't care about that here and so just pass NULL. The final parameter is for obtaining our MIDIClientRef. A lot of the CoreMIDI functions return OSStatus to indicate success or failure, and it's a good idea to check there wasn't any errors before continuing. In the following code snippets, I'll leave out the error checking as it's the same as the check above to save space, but it is present in the example code.
Once we have a MIDIClient, we can then create an input port.
MIDIPortRef inputPort;
result = MIDIInputPortCreate(client, CFSTR("Input"), midiInputCallback, NULL, &inputPort);
The first parameter it takes is our MIDIClientRef that we created earlier, and the second is the name of the port. At the end, the final parameter is for obtaining our newly created port. The third and fourth parameters are the callback for whenever there is MIDI data available on the port. The third is the function and the fourth is data that will be passed into that function as context. Here we don't have any context data, but in a more complicated objective C program we would pass usually pass self or some other object. It is in this callback that the MIDI parsing happens. Care needs to be taken as it is also called on a separate, high priority thread, which means that any data access needs to be done in a thread safe manner, and any UI updating needs to be triggered on the main UI thread using performSelectorOnMainThread.
So what does this callback function look like then? Something like this:
static void
midiInputCallback (const MIDIPacketList *list,
void *procRef,
void *srcRef)
{
NSLog(@"midiInputCallback was called");
}
We'll go into detail about what goes into it, and what the various parameters are for later, as first I want to get the rest of the ports hooked up.
So we want to get an endpoint on the external MIDI device and functions such as MIDIGetSource seem perfect for it, but they take an index to where the device is in the system. This is useful when you want to offer a list of devices for the user to choice the device from, but makes things more complicated for us. For this initial example we're going to use MIDIObjectFindByUniqueID but it needs a unique ID. To get this we need a helper program first.
A Brief Interlude
Make a new command line project, I called it MidiLister. Basically it is going to list all the MIDI devices and print their Unique IDs. First we need to add the CoreMIDI framework to it. If you select the MidiLister target, and go to the Build Phases page. Then in the section titled Link Binary With Libraries, click the plus symbol, type coremidi and select it.
Now in the main.m file import CoreMIDI/CoreMIDI.h and add the following code to the main function:
ItemCount numOfDevices = MIDIGetNumberOfDevices();
for (int i = 0; i < numOfDevices; i++) {
MIDIDeviceRef midiDevice = MIDIGetDevice(i);
NSDictionary *midiProperties;
MIDIObjectGetProperties(midiDevice, (CFPropertyListRef *)&midiProperties, YES);
NSLog(@"Midi properties: %d \n %@", i, midiProperties);
}
We're getting all the MIDI devices that the system knows about, and printing out their properties. If you build, run it, and look at the output somewhere in the output will be the MIDI device you want to use, and it will print something like this
entities = (
{
destinations = (
{
uniqueID = "-2123048758";
}
);
embedded = 0;
maxSysExSpeed = 3125;
name = LPD8;
sources = (
{
uniqueID = 1759718006;
}
);
uniqueID = "-2133248137";
}
);
image = "/Library/Audio/MIDI Devices/Generic/Images/USBInterface.tiff";
manufacturer = "AKAI professional LLC";
model = LPD8;
name = LPD8;
There may be a lot of devices and there are quite a lot of unique IDs for each device, each entity has a one and the device has one of its own. Which one do we want? Well, if you look through the output for something related to the MIDI controller you want to use. I knew that the model name for my controller was the Akai LPD8, and in this case we're wanting to receive data from the controller, so we want to use a source entity. This device only has one source, and its UniqueID is 1759718006. It will probably be different on your machine and for your controllers. Write the UniqueID down, and go back to the original project.
Now that we can use MIDIObjectFindByUniqueID to get the endpoint to use with this.
MIDIObjectRef endPoint;
MIDIObjectType foundObj;
result = MIDIObjectFindByUniqueID(1759718006, &endPoint, &foundObj);
Obviously in the above code, you should replace the uniqueID with the one for your device. We don't actually care about the foundObj, what we're interested in is the endPoint parameter and once we have that, we can link the input port that we created earlier to this endpoint.
result = MIDIPortConnectSource(inputPort, endPoint, NULL);
This function is quite straight forward, it connects the port that we created earlier (inputPort) to the end point that we got from our device (endPoint) and the last parameter is for some context data. Finally by adding a CFRunLoop so that any input events will be processed we will see that our callback is triggered whenever you do something on the MIDI controller.
CFRunLoopRun();
Processing MIDI Events
Now that we have a program that can read MIDI events, we need to work out what the MIDI data is actually telling us. Unfortunately CoreMIDI is only used for configuring, sending and receiving MIDI data, it doesn't have anything to help with creating or parsing that MIDI data. Luckily the upside is that MIDI is a very simple protocol and there are various places online that describe it (without you needing to spend big bucks on the official MIDI spec). CoreMIDI passes the data to our callback function in a MIDIPacketList. Remember this was our callback function's protocol:
static void
midiInputCallback (const MIDIPacketList *list,
void *procRef,
void *srcRef)
The MIDIPacketList parameter contains all the data related to the control change, and the two void * parameters are two pieces of context data. The first (procRef) is the context data that was set when the port was created via MIDIInputPortCreate, the second (srcRef) is the context data that was set when the port was connected to the endpoint with MIDIPortConnectSource.
To process a MIDIPacketList we iterate through the list, processing the MIDIPackets that are contained in it. A
MIDIPacket contains at least one complete MIDI message, except for Sysex messages which can be spread over multiple packets.
A MIDI message consists of a status byte, and then fixed number of bytes, depending on the message (apart from SysEx messages again but we'll ignore them for now). The high bits of the status byte tell us the message type, and the low bits tell us the channel number. So, for example, the status 0x83 tells us that a Note Off message was received from channel 4 (in MIDI messages the channels are numbered from 0-F, but in MIDI terminology they are numbered from 1-16, so 3 is really the fourth channel).
To find out the length of each message,
http://home.roadrunner.com/~jgglatt/tech/midispec.htm is a pretty good guide. Looking at the 0x83 message again, we can see that Note Off has 2 bytes of data afterwards. This way we can iterate over the data contained in the MIDIPacket finding all the messages and acting on them.
As mentioned above, the exception to all this is the SysEx message. This message starts with 0xF0 (SysEx Start) and all the following data until the message 0xF7 (SysEx End) is part of the SysEx message. This means it could be over multiple MIDIPackets, but all the data for a SysEx message will not be spread over multiple MIDIPacketLists. Also, if there is a SysEx message in a MIDIPacket there will not be any other messages in that MIDIPacket. This simplifies processing SysEx messages considerably.
Here is an example of how you could process some MIDI messages in the midiInputCallback function. I'm not claiming this is perfect ands there's probably lots of places where it could be improved. If you know an improvement or spot an error, feel free to leave a comment.
#define SYSEX_LENGTH 1024
We define a maximum length for a SysEx message.
void midiInputCallback (const MIDIPacketList *list,
void *procRef,
void *srcRef)
{
bool continueSysEx = false;
UInt16 nBytes;
const MIDIPacket *packet = &list->packet[0];
We get the first MIDIPacket in the list. Although we use ->packet[0] to get the first packet, the other packets are not accessed by ->packet[1], [2] etc. We need to use MIDIPacketNext, as you'll notice at the end of the function.
unsigned char sysExMessage[SYSEX_LENGTH];
unsigned int sysExLength = 0;
This is just a buffer for collecting the SysEx messages.
We start by going through all of the MIDIPackets in the MIDIPacketList
for (unsigned int i = 0; i < list->numPackets; i++) {
nBytes = packet->length;
We want to check if we're gathering a SysEx message that is spread over many MIDIPackets. If it is, then we need to copy the data into the message buffer.
// Check if this is the end of a continued SysEx message
if (continueSysEx) {
unsigned int lengthToCopy = MIN (nBytes, SYSEX_LENGTH - sysExLength);
// Copy the message into our SysEx message buffer,
// making sure not to overrun the buffer
memcpy(sysExMessage + sysExLength, packet->data, lengthToCopy);
sysExLength += lengthToCopy;
Now we've copied the data, we check if the last byte is the SysEx End message.
// Check if the last byte is SysEx End.
continueSysEx = (packet->data[nBytes - 1] == 0xF7);
If we've finished the message, or if we've filled the buffer then we have a complete SysEx message to process. Here we're not doing anything with it, but in a proper application we'd pass it to whatever acts on the MIDI messages.
if (!continueSysEx || sysExLength == SYSEX_LENGTH) {
// We would process the SysEx message here, as it is we're just ignoring it
sysExLength = 0;
}
} else {
If we weren't continuing a SysEx message then we need to iterate over all the bytes in the MIDIPacket parsing the messages that are contained in it.
UInt16 iByte, size;
iByte = 0;
while (iByte < nBytes) {
size = 0;
// First byte should be status
unsigned char status = packet->data[iByte];
if (status < 0xC0) {
size = 3;
} else if (status < 0xE0) {
size = 2;
} else if (status < 0xF0) {
size = 3;
} else if (status == 0xF0) {
// MIDI SysEx then we copy the rest of the message into the SysEx message buffer
unsigned int lengthLeftInMessage = nBytes - iByte;
unsigned int lengthToCopy = MIN (lengthLeftInMessage, SYSEX_LENGTH);
memcpy(sysExMessage + sysExLength, packet->data, lengthToCopy);
sysExLength += lengthToCopy;
size = 0;
iByte = nBytes;
// Check whether the message at the end is the end of the SysEx
continueSysEx = (packet->data[nBytes - 1] != 0xF7);
} else if (status < 0xF3) {
size = 3;
} else if (status == 0xF3) {
size = 2;
} else {
size = 1;
}
unsigned char messageType = status & 0xF0;
unsigned char messageChannel = status & 0xF;
Now we know the size of each message, what type it is, and what channel it was received on and we can pass it off to something that will parse it. For this example, here is some code that just prints the message and the values. Ideally this would happen on a low priority thread so that it doesn't block the thread that receives the MIDI messages, but for this example it doesn't matter too much.
switch (status & 0xF0) {
case 0x80:
NSLog(@"Note off: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);
break;
case 0x90:
NSLog(@"Note on: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);
break;
case 0xA0:
NSLog(@"Aftertouch: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);
break;
case 0xB0:
NSLog(@"Control message: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);
break;
case 0xC0:
NSLog(@"Program change: %d", packet->data[iByte + 1]);
break;
case 0xD0:
NSLog(@"Change aftertouch: %d", packet->data[iByte + 1]);
break;
case 0xE0:
NSLog(@"Pitch wheel: %d, %d", packet->data[iByte + 1], packet->data[iByte + 2]);
break;
default:
NSLog(@"Some other message");
break;
}
iByte += size;
}
}
As mentioned above, to get the next MIDIPacket you need to use MIDIPacketNext.
packet = MIDIPacketNext(packet);
}
}
And thats how you read data from a MIDI controller. Hopefully this is useful to some people.
Apple documentation for CoreMIDI -
https://developer.apple.com/library/mac/#documentation/MusicAudio/Reference/CACoreMIDIRef/MIDIServices/
