Thursday, September 17, 2009

NAudio Tutorial 7 – The Basics of MIDI Files


After the invigorating ride with the MIDI interface, I've done what I didn't originally set out to do and fallen for MIDI. It's been a bit of an arms length association for me; I actually started developing OpenSebJ (and BeatIt before that) many years ago because I didn't want to buy a MIDI keyboard and because I admittedly wasn't impressed with what what I associated with MIDI – that tinny sound that streams through your speakers when you started browsing the internet, after founding some ones home page on a free hosting site, that thought it would be wonderful to share with you a piece of music that could only be pitifully rendered through some inbuilt wave table on your Sound Blaster 16 (if you were so fortunate).

I digress; however that history is somewhat important as my focus has shifted since those humble beginnings to now understanding that MIDI does have a role in my future, for two primary reasons

1) It's the industry standard for interfacing Audio Equipment with a computer

2) It's a standard file format that can be read and written by most audio applications and means that layout's and scores using this information are almost universally transferable.

Don't get me wrong, I'm still a sucker for samples and that's where I'll end up targeting all of my development and time any way but MIDI in and of itself, is certainly an assisting means to that end.

This NAudio tutorial will be focusing on the MIDI File Format; we will start with the basics before moving on to the more intricate elements within the format. If you haven't had a chance to review the other posts in the NAudio Tutorial series yet, you can find them here:

The Format of Events

We can basically think of a MIDI file as a collection of events. These events are the same type of events which were introduced in the previous tutorial. The NoteOnEvent is arguably the most important and it is made up of:

AbsoluteTime – The time when this event will occur, in milliseconds
Channel – The channel (or you can think of it as the instrument), which this event relates to
NoteNumber – The number for the note; basically each note is assigned a number and this is how we work out which note on the scale will be played. Have a look at this nice SVG on Wikipedia which explains it.
Velocity – How hard we want to play the note
NoteLength (Duration) – How long the note is to be played for

So to put this together and create an event:

int AbsoluteTime = 1000; // 1 Second in on the track
int Channel = 1; // Channel needs to be between 1 and 16
int NoteNumber = 54;
int Velocity = 127; // Velocity is from 0 which is considered off, to 127 which is the maximum
int Duration = 250;

NoteOnEvent note1On = new NoteOnEvent(AbsoluteTime, Channel, NoteNumber, Velocity, Duration);

NoteOnEvent note1Off = new NoteOnEvent(AbsoluteTime + Duration, Channel, NoteNumber, 0, 0); // This is in effect a note off event – letting us know that the note can stop playing now.

Each NoteOn needs a corresponding NoteOff. A note off is defined by the Velocity == 0. If we don't have a corresponding NoteOff for a NoteOn event we will get a lovely exception thrown informing us of our civic duty to add a NoteOff for every NoteOn.

One note on and note off event by itself is interesting but not very useful. If we want to keep a set of events together then we should use the MidiEventCollection.

The Collection of Events

A MidiEventCollection is exactly what the name suggests, a collection of MIDI events. However it is a very sophisticated collection and is structured in such a way that allows for easy translation to a Midi file when required. If we have a look at the constructor we have the following:

MidiEventCollection events = new MidiEventCollection(FileType, DeltaTicksPerQuarterNote);

The file type is referring to what format we will be using for the MIDI File – we can set this to one for the purposes of this demonstration.

DeltaTicksPerQuarterNote is what it implies but we wont be going in to detail on this item in this tutorial, for now you can just set it to a value of 120.


The MIDI specification can contain a number of tracks (think separate instruments) within the one file. Therefore each Event needs to be associated to a Track. In the version of the MIDI file we are working with in this example, Track 0 is used to store basic meta data about the composition. We add tracks to the MidiEventCollection like so:

int outputTrackCount = 2;
for (int track = 0; track < outputTrackCount; track++)

Add Events to the Collection

To add an event to a track all we need to use the Add method of the MidiEventCollection class. The Track is used as the array position identifier and the method then stores the events on that track – like so:


Export the Collection to a file (Save MIDI File)

Quick recap, we now have a single note being played defined, which is made up of 2 events, a NoteOn event and a corresponding NoteOff event. We have added 2 tracks to the MidiEventCollection, Track 0 & Track 1 and finally we have added the 2 events to Track 1. Before we export our lone playing note composition EndMarkers need to be appended to each Track. Fortunately there is a pre-supplied function for this which makes it rather straight forward, you will need to add it to your class though:

private void AppendEndMarker(IList<MidiEvent> eventList)
    long absoluteTime = 0;
    if (eventList.Count > 0)
        absoluteTime = eventList[eventList.Count - 1].AbsoluteTime;
    eventList.Add(new MetaEvent(MetaEventType.EndTrack, 0, absoluteTime));

Then it's just a matter of calling the method:


After this it's matter of calling the Export function and passing in the file name where the file is to be saved and the MidiEventCollection storing all of the events, aka:

MidiFile.Export(filename, events);

That's seriously it. We have saved our Midi file to some location. Go play it and hear a single note, exciting.

Other NAudio Tutorials

For more tutorials in this series, please see the following:


jcoburn said...

hi -- great series. I'm trying to do something much more basic (I think) though. I'm collecting data from an analog input card (as a 2D array inputed every 150msec). the data is in double format and represents a voltage level of a non-periodic but varying signal of about 12Hz. I want to output it to a sound card. I went through your tutorial for wav output and the tutorial works fine, but I'm looking for a starting point in the NAudio dll so that i can feed data to the output stream in real time -- instead of the wav file. the purpose of all this is so somebody can hear a change in voltage levels as a change in sound.

Anonymous said...

Who knows where to download XRumer 5.0 Palladium?
Help, please. All recommend this program to effectively advertise on the Internet, this is the best program!

Anonymous said...

Hello DSebJ,
first off all let me say, your naudio library is great.
I try to use it, for my own programmed Database in C# to analyize midi-File collections. I made some changes, like Yamaha XG Sysex a.s.o, but I didn't find the solution to calculate the length of a midifile.
I tried to compare the length-value from mci-api, absoluteTime, Tempo and deltaTicksPerQuarterNote (from class MidiFile) but it seems that here is no relation. Please, could you post how the midifile length (in ms) can be calculated? Thanks of all midibase:)

Harriet said...

Great guide, I just got some professional free midi files and plan on messing around with them a bit, probably nowhere near in the detail that you guys can do.

Anonymous said...

Hi, DSebJ..
I'm planning to create a project to play midi files to a custom-made sampler that was recorded in .wav format.
I'm currently looking at C# Synth and NAudio but facing difficulty as their documentation is not thorough.
I don't know how to "match" midi to the sampler. Do you have any suggestion for me.
Your assistance is very much appreciated. Thank you in advance.

OpenSebJ said...

Send me an email. Go to and use the contact form.