Provided by: midicsv_1.1+dfsg.1-1build1_amd64 bug

NAME

       midicsv - MIDI Comma-Separated Value (CSV) file format

DESCRIPTION

       The  midicsv  and  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 midicsv and read by csvmidi.  Readers are assumed to understand the structure,
       terminology, and contents of MIDI files-please refer to a MIDI file reference for details.

RECORD STRUCTURE

       Each record in the CSV representation of a MIDI contains at least three fields:

       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.

       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.

       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.  csvmidi ignores upper/lower case in the
                 Type  field;  the specifications ``Note_on_c'', ``Note_On_C'', and ``NOTE_ON_C''
                 are considered identical.

       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 csvmidi.  Following the three
       required fields are parameter fields which depend  upon  the  Type;  some  Types  take  no
       parameters.  Each Type and its parameter fields is discussed below.

       Any line with an initial nonblank character of ``#'' or ``;'' 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.

   File Structure Records
       0, 0, Header, format, nTracks, division
            The first record of a CSV MIDI file is always  the  Header  record.   Parameters  are
            format:  the  MIDI file type (0, 1, or 2), nTracks: the number of tracks in the file,
            and division: the number of clock pulses per quarter note.  The Track and Time fields
            are always zero.

       0, 0, End_of_file
            The  last  record  in a CSV MIDI file is always an End_of_file record.  Its Track and
            Time fields are always zero.

       Track, 0, Start_track
            A Start_track record marks the start of a new track, with the Track field giving  the
            track  number.  All records between the Start_track record and the matching End_track
            will have the same Track field.

       Track, Time, End_track
            An End_track marks the end of events for the specified Track.  The Time  field  gives
            the  total  duration  of  the  track, which will be identical to the Time in the last
            event before the End_track.

   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
       Time zero, but this is not a requirement.

       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  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 ``_t''.

       Track, Time, Title_t, "Text"
              The  Text specifies the title of the track or sequence.  The first 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 Title meta-events in other tracks give the names of those tracks.

       Track, Time, Copyright_t, "Text"
              The  Text specifies copyright information for the sequence.  This is usually placed
              at time 0 of the first track in the sequence.

       Track, Time, Instrument_name_t, "Text"
              The 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.

       Track, Time, Marker_t, "Text"
              The Text marks a point in the sequence which occurs at the given Time, for  example
              "Third Movement".

       Track, Time, Cue_point_t, "Text"
              The  Text  identifies synchronisation point which occurs at the specified Time, for
              example, "Door slams".

       Track, Time, Lyric_t, "Text"
              The Text gives a lyric intended to be sung at the given  Time.   Lyrics  are  often
              broken  down  into  separate  syllables  to time-align them more precisely with the
              sequence.

       Track, Time, Text_t, "Text"
              This meta-event supplies an arbitrary Text string tagged to the Track and Time.  It
              can  be  used  for  textual  information  which  doesn't  fall into one of the more
              specific categories given above.

       Track, 0, Sequence_number, Number
              This meta-event specifies a sequence 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  Sequence_number  meta-
              event should occur at Time zero, at the start of the track.

       Track, Time, MIDI_port, Number
              This  meta-event  specifies  that  subsequent events in the Track should be sent to
              MIDI port (bus) Number, between 0 and 255.  This meta-event usually appears at  the
              start  of  a  track  with  Time zero, but may appear within a track should the need
              arise to change the port while the track is being played.

       Track, Time, Channel_prefix, Number
              This  meta-event  specifies  the  MIDI  channel  that  subsequent  meta-events  and
              System_exclusive  events  pertain  to.  The channel Number specifies a MIDI channel
              from 0 to 15.  In fact, the Number may be as large as 255, but the consequences  of
              specifying a channel number greater than 15 are undefined.

       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.   Num  gives  the
              numerator  of  the time signature as specified on sheet music.  Denom specifies the
              denominator as a negative power of two, for example 2 for a quarter note, 3 for  an
              eighth  note,  etc.  Click gives the number of MIDI clocks per metronome click, and
              NotesQ the number of 32nd notes in the nominal MIDI quarter note time of 24  clocks
              (8 for the default MIDI quarter note definition).

       Track, Time, Key_signature, Key, Major/Minor
              The  key signature is specified by the numeric 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 Major/Minor field is a quoted string
              which will be "major" for a major key and "minor" for a minor key.

       Track, Time, Tempo, Number
              The tempo is specified as the 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  Tempo  value,  take  the  quotient  from
              dividing 60,000,000 by the beats per minute.

       Track, 0, SMPTE_offset, Hour, Minute, Second, Frame, FracFrame
              This  meta-event,  which  must  occur  with  a  zero  Time at the start of a track,
              specifies the SMPTE time code at which it  should  start  playing.   The  FracFrame
              field gives the fractional frame time (0 to 99).

       Track, Time, Sequencer_specific, Length, Data, ...
              The  Sequencer_specific  meta-event  is  used to store vendor-proprietary data in a
              MIDI file.  The Length can be any value  between  0  and  2**28-1,  specifying  the
              number  of Data bytes (between 0 and 255) which follow.  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.

       Track, Time, Unknown_meta_event, Type, Length, Data, ...
              If  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 Type gives the
              numeric  meta-event  type  code, Length the number of data bytes in the meta-event,
              which can be any value between 0 and 2**28-1, followed by the  Data  bytes.   Since
              meta-events  include  their  own length, it is possible to parse them even if their
              type and meaning are unknown.  csvmidi will reconstruct  unknown  meta-events  with
              the same type code and content as in the original MIDI file.

   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 ``_c''.

       Track, Time, Note_on_c, Channel, Note, Velocity
              Send  a  command to play the specified Note (Middle C is defined as Note number 60;
              all other notes are relative  in  the  MIDI  specification,  but  most  instruments
              conform  to the well-tempered scale) on the given Channel with Velocity (0 to 127).
              A Note_on_c event with Velocity zero is equivalent to a Note_off_c.

       Track, Time, Note_off_c, Channel, Note, Velocity
              Stop playing the specified Note on the given Channel.  The Velocity should be zero,
              but you never know what you'll find in a MIDI file.

       Track, Time, Pitch_bend_c, Channel, Value
              Send  a  pitch bend command of the specified Value to the given Channel.  The pitch
              bend Value is a 14 bit unsigned integer and hence must be in  the  inclusive  range
              from 0 to 16383.

       Track, Time, Control_c, Channel, Control_num, Value
              Set  the  controller  Control_num  on  the  given  Channel  to the specified Value.
              Control_num and Value must be in the inclusive range 0 to 127.  The  assignment  of
              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.

       Track, Time, Program_c, Channel, Program_num
              Switch  the specified Channel to program (patch) 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.

              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  Program_num  values,
              note  that  they  may  be  one less than the patch numbers given in an instrument's
              documentation.

       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
              Channel as a whole, not individual note numbers on  that  channel).   The  pressure
              Value  (0  to  127)  is  typically  taken  to  apply  to  the last note played, but
              instruments are not guaranteed to behave in this manner.

       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 Value (0 to 127) for the specified  Note  on  the
              given Channel.

   System Exclusive Events
       System  Exclusive  events  permit storing vendor-specific information to be transmitted to
       that vendor's products.

       Track, Time, System_exclusive, Length, Data, ...
              The Length bytes of Data (0 to 255) are sent at the  specified  Time  to  the  MIDI
              channel  defined  by the most recent Channel_prefix event on the Track, as a System
              Exclusive message.  Note that Length can  be  any  value  between  0  and  2**28-1.
              Programs  which  process MIDI CSV files should be careful to protect against buffer
              overflows and truncation of these records.

       Track, Time, System_exclusive_packet, Length, Data, ...
              The Length bytes of Data (0 to 255) are sent at the  specified  Time  to  the  MIDI
              channel  defined  by  the  most recent Channel_prefix event on the Track.  The 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  Length  can be any value between 0 and 2**28-1.  Programs which process
              MIDI CSV files should be careful to protect against buffer overflows and truncation
              of these records.

EXAMPLES

       The  following  CSV file defines the five-note motif from the film Close Encounters of the
       Third Kind using an organ patch from the General MIDI instrument set.  When  processed  by
       midicsv  and  sent  to  a synthesiser which conforms to General MIDI, the sequence will be
       played.

            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

BUGS

       The CSV representation of a MIDI file is simply a text-oriented encoding of its  contents.
       If the input to midicsv contains errors which violate the MIDI standard, the resulting CSV
       file will faithfully replicate these errors.  Similarly, the CSV input to 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 semantically correct MIDI file.  Programs which wish to  use  csvmidi
       to generate MIDI files from scratch should be careful to conform to the structure required
       of MIDI files.  When in doubt, use midicsv to dump a sequence comparable to the  one  your
       program will create and use its structure as a template for your own.

       Please report errors to bugs@fourmilab.ch.

SEE ALSO

       csvmidi(1), midicsv(1)

AUTHOR

                                              John Walker
                                        http://www.fourmilab.ch/

       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.