Appendix 7: Midi File Parser Manual Page
MIDIFILE.3 (May 12, 1990 Misc. Reference Manual Page)
NAME
midifile - a MIDI file parser
SYNOPSIS
#include "midifile.h"
int midifile()
int (*Mf_getc)()
int (*Mf_error)(str)
char *str;
int (*Mf_header)(format,ntrks,division)
short format, ntrks, division;
int (*Mf_starttrack)()
int (*Mf_on)(chan,note,vol)
unsigned char chan, note, vol;
int (*Mf_off)(chan,note,vol)
unsigned char chan, note, vol;
int (*Mf_pressure)(chan,note,pressure)
unsigned char chan, note, pressure;
int (*Mf_controller)(chan,control,value)
unsigned char chan, control, value;
int (*Mf_pitchbend)(chan,lsb,msb)
unsigned char chan, lsb, msb;
int (*Mf_program)(chan,prog)
unsigned char chan, prog;
int (*Mf_chanpressure)(chan,pressure)
unsigned char chan, pressure;
int (*Mf_sysex)()
int (*Mf_metamisc)()
int (*Mf_sqspecific)(chan,length,data)
unsigned char chan;
long length;
char *data;
int (*Mf_seqnum)(seqnum)
short seqnum
int (*Mf_text)(msg_type,length,data)
int msg_type;
long length;
char *data;
int (*Mf_eot)()
int (*Mf_timesig)(numer,denom,clocks,qnotes)
int numer, denom, clocks, qnotes;
int (*Mf_smpte)(hour,min,sec,frame,fract)
int hour, min, sec, frame, fract;
int (*Mf_tempo)(tempo)
unsigned long tempo;
int (*Mf_keysig)(sharpflat,minor)
int sharpflat, minor;
int (*Mf_arbitrary)()
long Mf_currtime
long Mf_deltatime
DESCRIPTION
midifile is a routine that parses an arbitrary MIDI format
file. It contains hooks for every type of event, for the
user to add his own event-handling functions. Each time
midifile reads an event, it calls a user function (if one is
defined, i.e., if it is non-NULL) with a description of the
event.
Not all functions must be supplied at all times: midifile
always checks for the existence of a user function before
calling it. Thus, if you're only interested in the third
track, you can have Mf_starttrack assign values to the
appropriate functions at the beginning of the third track,
and Mf_eot reset them to NULL.
The only function which must be supplied is Mf_getc, which
should read a byte from the MIDI file and return it; it
should return -1 in case of end of file, and a negative
error code in case of error.
Mf_error is called in case of error. It is passed a string
describing the error. If Mf_error returns a negative value,
then midifile aborts and returns that value.
Actually, any user function can abort the execution of midi-
file: anytime a function returns a negative value, midifile
returns that value to the calling routine.
Mf_header is called when the file header has been read. Its
parameters are the file format (0, 1 or 2), the number of
tracks in the file, and the division of quarter-notes, as
described by the deltas in the file.
Mf_starttrack is called at the beginning of each track.
Mf_on and Mf_off are called each time midifile reads a MIDI
ON and MIDI OFF event, respectively. The parameters are the
MIDI channel, the note number, and the note-on (or off)
velocity.
Mf_pressure is called for polyphonic key pressure (after-
touch) events. It gives the channel, the note number, and
the pressure value. Similarly, Mf_chanpressure is called
for channel pressure events.
Mf_controller is called for controller changes. It gives the
MIDI channel, the controller number, and the controller
value.
Mf_pitchbend is called for pitch wheel events. It gives the
MIDI channel, the least-significant and most-significant
bytes of the pitch-bend value.
Mf_program is called for program (patch) changes. It gives
the MIDI channel and the program number.
Mf_sysex is called for system-exclusive messages. This func-
tion is not yet implemented.
midifile includes a series of functions designed to deal
with the various meta-events described by the MIDI 1.0 file
spec. In each case, the length parameter, when given,
includes the end-of-system-exclusive marker.
Mf_metamisc is called for miscellaneous meta-events, as
described in the MIDI 1.0 file spec. This function is not
yet implemented.
Mf_sqspecific is called for sequencer-specific meta-events.
It gives the MIDI channel number, the length of the event,
and a data string containing the data.
Mf_seqnum specifies the number of a sequence.
Mf_text covers the entire class of text meta-events. It
gives the message type (miscellaneous, copyright notice,
track name, etc.), the text length, and a string containing
the text.
Mf_eot is called for the end-of-track meta-event.
Mf_timesig gives the time signature of a piece. The time
signature, as given at the beginning of a piece is given by
numer/(2^-denom). clocks represents the number of MIDI
clocks per metronome click. qnotes gives the number of
notated 32nd-notes in a MIDI quarter-note.
Mf_smpte specifies a SMPTE offset for a track. It gives the
number of hours, minutes, seconds, frames and 100ths of a
frame.
Mf_tempo sets the tempo, in microseconds per MIDI quarter-
note.
Mf_keysig gives the key signature of the piece. sharpflat
gives the number of sharps or flats in the signature: 0
means the piece is in the key of C, -1 means there is one
flat in the signature, 1 means there is one sharp, and so
forth. minor is set to 0 if the piece is in a major key,
and 1 if it is in a minor key.
There are two user-accessible variables used by midifile:
Mf_currtime and Mf_deltatime Mf_currtime measures the time
elapsed between the beginning of the track and the current
event. Mf_deltatime is the event's delta, i.e., it measures
the time elapsed between the previous event and the current
event (or the beginning of the track, if the current event
is the first one).
FILES
midifile.h
BUGS
midifile does not handle system-exclusive messages, except
for the meta-events described in the MIDI 1.0 File Specifi-
cation.
AUTHOR
Original author: Tim Thompson. This version was rewritten
and enhanced by Andrew Arensburger.
SEE ALSO
MIDI 1.0 specification
MIDI 1.0 file specification