'\" t
.TH MIDICSV 5 "29 MAR 2004"
.UC 4
.SH NAME
midicsv \- MIDI Comma-Separated Value (CSV) file format
.SH DESCRIPTION
The
.B midicsv
and
.B csvmidi
programs permit you to intertranslate standard MIDI
files and comma-separated value (CSV) files.  These CSV files
preserve all information in the MIDI file, and
may be loaded into spreadsheet and database programs
or easily manipulated with text processing tools.
This document describes the CSV representation of
MIDI files written by
.B midicsv
and read by
.BR csvmidi .
Readers are assumed to understand the structure,
terminology, and contents of MIDI files\-please
refer to a MIDI file reference for details.
.SH "RECORD STRUCTURE"
Each record in the CSV representation of a MIDI contains
at least three fields:
.TP 10
.B Track
Numeric field identifying the track to which this
record belongs.  Tracks of MIDI data are numbered
starting at 1.  Track 0 is reserved for file header, information,
and end of file records.
.TP
.B Time
Absolute time, in terms of MIDI clocks, at which this
event occurs.  Meta-events for which time is not
meaningful (for example, song title, copyright information,
etc.) have an absolute time of 0.
.TP
.B Type
Name identifying the type of the record.  Record types
are text consisting of upper and lower case letters
and the underscore (``_''), contain no embedded spaces,
and are not enclosed in quotes.
.B csvmidi
ignores upper/lower case in the
.B Type
field; the specifications
.RB `` Note_on_c '',
.RB `` Note_On_C '',
and
.RB `` NOTE_ON_C ''
are considered identical.
.PP
Records in the CSV file are sorted first by the track
number, then by time.  Out of order records will be discarded
with an error message from
.BR csvmidi .
Following the three
required fields are parameter fields which depend upon
the
.BR Type ;
some
.BR Type s
take no parameters.  Each
.B Type
and its parameter fields is discussed below.
.PP
Any line with an initial nonblank
character of
.RB `` # ''
or
.RB `` ; ''
is ignored; either delimiter may be used to introduce
comments in a CSV file.  Only full-line comments
are permitted; you cannot use these delimiters to terminate
scanning of a regular data record.  Completely blank lines are
ignored.
.SS "File Structure Records"
.TP 5
.BI "0, 0, Header" ", format, nTracks, division"
The first record of a CSV MIDI file is always the
.B Header
record.  Parameters are
.IR format :
the MIDI file type
(0, 1, or 2),
.IR nTracks :
the number of tracks in the file,
and
.IR division :
the number of clock pulses per quarter note.
The
.B Track
and
.B Time
fields are always zero.
.TP
.B "0, 0, End_of_file"
The last record in a CSV MIDI file is always an
.B End_of_file
record.  Its
.B Track
and
.B Time
fields are always zero.
.TP
.IB "Track, " "0, Start_track"
A
.B Start_track
record marks the start of a new track, with the
.I Track
field giving the track number.  All records between
the
.B Start_track
record and the matching
.B End_track
will have the same
.I Track
field.
.TP
.IB "Track, Time, " "End_track"
An
.B End_track
marks the end of events for the specified
.IR Track .
The
.I Time
field gives the total duration of the track, which will be
identical to the
.I Time
in the last event before the
.BR End_track .
.SS "File Meta-Events"
The following events occur within MIDI tracks and specify various
kinds of information and actions.  They may appear at any time
within the track.  Those which provide general information for
which time is not relevant usually appear at the start of the
track with
.B Time
zero, but this is not a requirement.
.PP
Many of these meta-events include a text string argument.  Text
strings are output in CSV records enclosed in ASCII
double quote (") characters.  Quote characters embedded
within strings are represented by two consecutive quotes.
Non-graphic characters in the
ISO 8859/1 Latin 1 set are output as a backslash followed by their
three digit octal character code.  Two consecutive backslashes
denote a literal backslash in the string.
Strings in MIDI files can be
extremely long, theoretically as many as
.if t 2\s-2\v'-0.4m'28\v'0.4m'\s+2\-1
.if n 2**28-1
characters; programs which process
MIDI CSV files should take care to avoid buffer overflows or truncation
resulting from lines containing long string items.  All meta-events which
take a text argument are identified by a suffix of
.RB `` _t ''.
.TP
.IB "Track, Time, " "Title_t, """ Text """
The
.I Text
specifies the title of the track or sequence.  The first
.B Title
meta-event in a type 0 MIDI file, or in the first track of a
type 1 file gives the name of the work.  Subsequent
.B Title
meta-events in other tracks give the names of those
tracks.
.TP
.IB "Track, Time, " "Copyright_t, """ Text """
The
.I Text
specifies copyright information for the sequence.
This is usually placed at time 0 of the first track in the
sequence.
.TP
.IB "Track, Time, " "Instrument_name_t, """ Text """
The
.I Text
names the instrument intended to play the
contents of this track,
This is usually placed at time 0 of the track.  Note
that this meta-event is simply a description; MIDI synthesisers
are not required (and rarely if ever) respond to it.
This meta-event is particularly useful in sequences
prepared for synthesisers which do not conform to the
General MIDI patch set, as it documents the intended
instrument for the track when the sequence is
used on a synthesiser with a different patch
set.
.TP
.IB "Track, Time, " "Marker_t, """ Text """
The
.I Text
marks a point in the sequence which occurs at
the given
.IR Time ,
for example
"Third\ Movement".
.TP
.IB "Track, Time, " "Cue_point_t, """ Text """
The
.I Text
identifies synchronisation point which occurs at
the specified
.IR Time ,
for example,
"Door\ slams".
.TP
.IB "Track, Time, " "Lyric_t, """ Text """
The
.I Text
gives a lyric intended to be sung at the given
.IR Time .
Lyrics are often broken down into separate syllables
to time-align them more precisely with the sequence.
.TP
.IB "Track, Time, " "Text_t, """ Text """
This meta-event supplies an arbitrary
.I Text
string tagged to the
.I Track
and
.IR Time .
It can be used for textual information which doesn't fall into
one of the more specific categories given
above.
.TP
.IB "Track, " "0, Sequence_number, " Number
This meta-event specifies a sequence
.I Number
between 0 and 65535, used to arrange multiple tracks in
a type 2 MIDI file, or to identify the sequence in which
a collection of type 0 or 1 MIDI files should be played.
The
.B Sequence_number
meta-event should occur at
.B Time
zero, at the start of the track.
.TP
.IB "Track, Time, " "MIDI_port, " Number
This meta-event specifies that subsequent events in the
.B Track
should be sent to MIDI port (bus)
.IR Number ,
between 0 and 255.
This meta-event usually appears at the start of a track
with
.B Time
zero, but may appear within a track should the need
arise to change the port while the track is being played.
.TP
.IB "Track, Time, " "Channel_prefix, " Number
This meta-event specifies the MIDI channel that subsequent
meta-events and
.B System_exclusive
events pertain to.  The channel
.I Number
specifies a MIDI channel from 0 to 15.  In fact,
the
.I Number
may be as large as 255, but the consequences of
specifying a channel number greater than 15 are undefined.
.TP
.IB "Track, Time, " "Time_signature, " "Num, Denom, Click, NotesQ"
The time signature, metronome click rate, and number of 32nd
notes per MIDI quarter note (24 MIDI clock times) are
given by the numeric arguments.
.I Num
gives the numerator of the time signature as specified
on sheet music.
.I Denom
specifies the denominator as a negative power of two,
for example 2 for a quarter note, 3 for an eighth note,
etc.
.I Click
gives the number of MIDI clocks per metronome click, and
.I NotesQ
the number of 32nd notes in the nominal MIDI quarter
note time of 24 clocks (8 for the default MIDI quarter
note definition).
.TP
.IB "Track, Time, " "Key_signature, " "Key, Major/Minor"
The key signature is specified by the numeric
.I Key
value, which is 0 for the key of C, a positive value for
each sharp above C, or a negative value for each flat below
C, thus in the inclusive range \-7 to 7.  The
.I Major/Minor
field is a quoted string which will be
.B """major"""
for a major key and
.B """minor"""
for a minor key.
.TP
.IB "Track, Time, " "Tempo, " "Number"
The tempo is specified as the
.I Number
of microseconds per quarter note, between 1 and
16777215.  A value of 500000 corresponds to
120 quarter notes ("beats") per minute.  To convert
beats per minute to a
.B Tempo
.IR value ,
take the quotient from dividing 60,000,000
by the beats per minute.
.TP
.IB "Track, " "0, SMPTE_offset, " "Hour, Minute, Second, Frame, FracFrame"
This meta-event, which must occur with a zero
.B Time
at the start of a track, specifies the SMPTE time code at which
it should start playing.  The
.I FracFrame
field gives the fractional frame time (0 to 99).
.TP
.IB "Track, Time, " "Sequencer_specific, " "Length, Data, ..."
The
.B Sequencer_specific
meta-event is used to store vendor-proprietary data in
a MIDI file.  The
.I Length
can be any value between 0 and
.if t 2\s-2\v'-0.4m'28\v'0.4m'\s+2\-1,
.if n 2**28-1,
specifying the number of
.I Data
bytes (between 0 and 255) which follow.
.B Sequencer_specific
records may be very long; programs which process MIDI CSV
files should be careful to protect against buffer overflows
and truncation of these records.
.TP
.IB "Track, Time, " "Unknown_meta_event, " "Type, Length, Data, ..."
If
.B midicsv
encounters a meta-event with a code not defined by the standard
MIDI file specification, it outputs an unknown meta-event record
in which
.I Type
gives the numeric meta-event type code,
.I Length
the number of data bytes in the meta-event, which can be
any value between 0 and
.if t 2\s-2\v'-0.4m'28\v'0.4m'\s+2\-1,
.if n 2**28-1,
followed by the
.I Data
bytes.  Since meta-events include their own length, it
is possible to parse them even if their type and meaning
are unknown.
.B csvmidi
will reconstruct unknown meta-events with the same type code
and content as in the original MIDI file.
.SS "Channel Events"
These events are the ``meat and potatoes'' of MIDI files: the
actual notes and modifiers that command the instruments to play
the music.  Each has a MIDI channel number as its first argument,
followed by event-specific parameters.  To permit programs which process
CSV files to easily distinguish them from meta-events, names
of channel events all have a suffix of
.RB `` _c ''.
.TP
.IB "Track, Time, " "Note_on_c, " "Channel, Note, Velocity"
Send a command to play the specified
.I Note
(Middle C is defined as
.I Note
number 60; all other notes are relative in the MIDI specification,
but most instruments conform to the well-tempered scale) on the
given
.I Channel
with
.I Velocity
(0 to 127).  A
.B Note_on_c
event with
.I Velocity
zero is equivalent to a
.BR Note_off_c .
.TP
.IB "Track, Time, " "Note_off_c, " "Channel, Note, Velocity"
Stop playing the specified
.I Note
on the given
.IR Channel .
The
.I Velocity
should be zero, but you never know what you'll find in
a MIDI file.
.TP
.IB "Track, Time, " "Pitch_bend_c, " "Channel, Value"
Send a pitch bend command of the specified
.I Value
to the given
.IR Channel .
The pitch bend
.I Value
is a 14 bit unsigned integer and hence must be in the inclusive range
from 0 to 16383.
.TP
.IB "Track, Time, " "Control_c, " "Channel, Control_num, Value"
Set the controller
.I Control_num
on the given
.I Channel
to the specified
.IR Value .
.I Control_num
and
.I Value
must be in the inclusive range 0 to 127.  The assignment of
.I Control_num
values to effects differs from instrument to instrument.  The
General MIDI specification defines the meaning of controllers
1 (modulation), 7 (volume), 10 (pan), 11 (expression),
and 64 (sustain), but not all instruments and patches respond
to these controllers.  Instruments which support those
capabilities usually assign reverberation to controller 91
and chorus to controller 93.
.TP
.IB "Track, Time, " "Program_c, " "Channel, Program_num"
Switch the specified
.I Channel
to program (patch)
.IR Program_num ,
which must be between 0 and 127.  The program or patch selects which
instrument and associated settings that channel will emulate.
The General MIDI specification provides a standard set of
instruments, but synthesisers are free to implement other sets
of instruments and many permit the user to create custom patches
and assign them to program numbers.
.TP
\ 
Apparently due to instrument manufacturers' skepticism about
musicians' ability to cope with the number zero, many instruments
number patches from 1 to 128 rather than the 0 to 127 used within
MIDI files.  When interpreting
.I Program_num
values, note that they may be one less than the patch numbers
given in an instrument's documentation.
.TP
.IB "Track, Time, " "Channel_aftertouch_c, " "Channel, Value"
When a key is held down after being pressed, some synthesisers
send the pressure, repeatedly if it varies, until the key is
released, but do not distinguish pressure on different keys played
simultaneously and held down.  This is referred to as
``monophonic'' or ``channel'' aftertouch (the latter indicating
it applies to the
.I Channel
as a whole, not individual note numbers
on that channel).  The pressure
.I Value
(0 to 127) is typically taken to apply to the last note played,
but instruments are not guaranteed to behave in this
manner.
.TP
.IB "Track, Time, " "Poly_aftertouch_c, " "Channel, Note, Value"
Polyphonic synthesisers (those capable of playing multiple
notes simultaneously on a single channel), often provide
independent aftertouch for each note.  This event specifies
the aftertouch pressure
.I Value
(0 to 127) for the specified
.I Note
on the given
.IR Channel .
.SS "System Exclusive Events"
System Exclusive events permit storing vendor-specific
information to be transmitted to that vendor's products.
.TP
.IB "Track, Time, " "System_exclusive, " "Length, Data, ..."
The
.I Length
bytes of
.I Data
(0 to 255)
are sent at the specified
.I Time
to the MIDI channel defined by the most recent
.B Channel_prefix
event on the
.IR Track ,
as a
System Exclusive message.
Note that
.I Length
can be any value between 0 and
.if t 2\s-2\v'-0.4m'28\v'0.4m'\s+2\-1.
.if n 2**28-1.
Programs which process MIDI CSV
files should be careful to protect against buffer overflows
and truncation of these records.
.TP
.IB "Track, Time, " "System_exclusive_packet, " "Length, Data, ..."
The
.I Length
bytes of
.I Data
(0 to 255)
are sent at the specified
.I Time
to the MIDI channel defined by the most recent
.B Channel_prefix
event on the
.IR Track .
The
.I Data
bytes are simply blasted out to the MIDI bus without
any prefix.  This message is used by MIDI devices which
break up long system exclusive message into small
packets, spaced out in time to avoid overdriving their
modest microcontrollers.
Note that
.I Length
can be any value between 0 and
.if t 2\s-2\v'-0.4m'28\v'0.4m'\s+2\-1.
.if n 2**28-1.
Programs which process MIDI CSV
files should be careful to protect against buffer overflows
and truncation of these records.
.SH EXAMPLES
The following CSV file defines the five-note motif from the
film
.I "Close Encounters of the Third Kind"
using an organ patch from the General MIDI instrument
set.  When processed by
.B midicsv
and sent to a synthesiser which conforms to General
MIDI, the sequence will be played.
.PP
.RS 5
.nf 23
0, 0, Header, 1, 2, 480
1, 0, Start_track
1, 0, Title_t, "Close Encounters"
1, 0, Text_t, "Sample for MIDIcsv Distribution"
1, 0, Copyright_t, "This file is in the public domain"
1, 0, Time_signature, 4, 2, 24, 8
1, 0, Tempo, 500000
1, 0, End_track
2, 0, Start_track
2, 0, Instrument_name_t, "Church Organ"
2, 0, Program_c, 1, 19
2, 0, Note_on_c, 1, 79, 81
2, 960, Note_off_c, 1, 79, 0
2, 960, Note_on_c, 1, 81, 81
2, 1920, Note_off_c, 1, 81, 0
2, 1920, Note_on_c, 1, 77, 81
2, 2880, Note_off_c, 1, 77, 0
2, 2880, Note_on_c, 1, 65, 81
2, 3840, Note_off_c, 1, 65, 0
2, 3840, Note_on_c, 1, 72, 81
2, 4800, Note_off_c, 1, 72, 0
2, 4800, End_track
0, 0, End_of_file
.RE
.SH BUGS
.PP
The CSV representation of a MIDI file is simply a text-oriented
encoding of its contents.  If the input to
.B midicsv
contains errors which violate the MIDI standard, the
resulting CSV file will faithfully replicate these errors.
Similarly, the CSV input to
.B csvmidi
must not only consist of records which conform to the
syntax given in this document, the input as a whole
must also be a
.I semantically
correct MIDI file.  Programs which wish to use
.B csvmidi
to generate MIDI files from scratch should be careful to
conform to the structure required of MIDI files.  When in
doubt, use
.B midicsv
to dump a sequence comparable to the one your program will
create and use its structure as a template for your own.
.PP
Please report errors to
.BR bugs@fourmilab.ch .
.SH "SEE ALSO"
.PD
.BR csvmidi (1),
.BR midicsv (1)
.ne 10
.SH AUTHOR
.ce 2
John Walker
http://www.fourmilab.ch/
.PP
This software is in the public domain.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
without any conditions or restrictions.  This software is provided ``as
is'' without express or implied warranty.