--- name: "midicsv" section: "5" platform: "linux" package: "midicsv" version: "1.1+dfsg.1-1+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/midicsv/5" --- # midicsv(5) MIDI Comma-Separated Value (CSV) file format ## 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 **Type**s 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)](/csvmidi/1.md), [**midicsv**(1)](/midicsv/1.md) ## 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.