miditones/README.txt

/*********************************************************************************************
*
*  MIDITONES: Convert a MIDI file into a simple bytestream of notes
*
*
*  MIDITONES converts a MIDI music file into a much simplified stream of commands, so that
*  the music can easily be played on a small microcontroller-based synthesizer that has
*  only simple tone generators. This is on github at www.github.com/LenShustek/miditones.
*
*  Volume ("velocity") and instrument information in the MIDI file can either be
*  discarded or kept. All the tracks are processed and merged into a single time-ordered
*  stream of "note on", "note off", "change instrument" and "delay" commands.
*
*  This was written for the "Playtune" series of Arduino and Teensy microcontroller
*  synthesizers. See the separate documentation for the various Playtune.players at
*    www.github.com/LenShustek/arduino-playtune
*    www.github.com/LenShustek/ATtiny-playtune
*    www.github.com/LenShustek/Playtune_poll
*    www.github.com/LenShustek/Playtune_samp
*    www.github.com/LenShustek/Playtune_synth
*  MIDITONES may also prove useful for other simple music synthesizers..
*
*  The output can be either a C-language source code fragment that initializes an
*  array with the command bytestream, or a binary file with the bytestream itself.
*
*  MIDITONES is written in standard ANSI C and is meant to be executed from the
*  command line.  There is no GUI interface.
*
*  The MIDI file format is complicated, and this has not been tested on all of its
*  variations.  In particular we have tested only format type "1", which seems
*  to be what most of them are.  Let me know if you find MIDI files that it
*  won't digest and I'll see if I can fix it.
*
*  There is a companion program in the same repository called Miditones_scroll
*  that can convert the bytestream generated by MIDITONES into a piano-player
*  like listing for debugging or annotation. See the documentation in the
*  beginning of its source code.
*
*
*  *****  The MIDITONES command line  *****
*
*  To convert a MIDI file called "chopin.mid" into a command bytestream, execute
*
*     miditones chopin
*
*  It will create a file in the same directory called "chopin.c" which contains
*  the C-language statement to intiialize an array called "score" with the bytestream.
*
*
*  The general form for command line execution is this:
*
*     miditones  <options>  <basefilename>
*
*  The <basefilename> is the base name, without an extension, for the input and
*  output files. It can contain directory path information, or not.
*
*  The input file is <basefilename>.mid  The output filename(s)
*  are the base file name with .c, .bin, and/or .log extensions.
*
*
*  The following commonly-used command-line options can be specified:
*
*  -v   Add velocity (volume) information to the output bytestream
*
*  -i   Add instrument change commands to the output bytestream
*
*  -pt  Translate notes in the MIDI percussion track to note numbers 128..255
*       and assign them to a tone generator as usual.
*
*  -d   Generate a self-describing file header that says which optional bytestream
*       fields are present. This is highly recommended if you are using later
*       Playtune players that can check the header to know what data to expect.
*
*  -b   Generate a binary file with the name <basefilename>.bin, instead of a
*       C-language source file with the name <basefilename>.c.
*
*  -tn  Generate the bytestream so that at most "n" tone generators are used.
*       The default is 6 tone generators, and the maximum is 16. The program
*       will report how many notes had to be discarded because there weren't
*       enough tone generators.
*
*
* The best combination of options to use with the later Playtune music players is:
*        -v -i -pt -d
*
*
* The following are lesser-used command-line options:
*
*  -p   Only parse the MIDI file, and don't generate an output file.
*       Tracks are processed sequentially instead of being merged into chronological order.
*       This is mostly useful for debugging MIDI file parsing problems.
*
*  -lp  Log input file parsing information to the <basefilename>.log file
*
*  -lg  Log output bytestream generation information to the <basefilename>.log file
*
*  -nx  Put about "x" items on each line of the C file output
*
*  -sn  Use bytestream generation strategy "n".
*       Two strategies are currently implemented:
*          1:favor track 1 notes instead of all tracks equally
*          2:try to keep each track to its own tone generator
*
*  -cn  Only process the channel numbers whose bits are on in the number "n".
*       For example, -c3 means "only process channels 0 and 1". In addition to decimal,
*       "n" can be also specified in hex using a 0x prefix or octal with a 0 prefix.
*
*  -kn  Change the musical key of the output by n chromatic notes.
*       -k-12 goes one octave down, -k12 goes one octave up, etc.
*
*  -pi  Ignore notes in the MIDI percussion track 9 (also called 10 by some)
*
*  -dp  Generate IDE-dependent C code to define PROGMEM
*
*  -r   Terminate the output file with a "restart" command instead of a "stop" command.
*
*  -h   Give command-line help.
*
*
*  *****  The score bytestream  *****
*
*  The generated bytestream is a series of commands that turn notes on and off,
*  maybe change instruments, and begin delays until the next note change.
*  Here are the details, with numbers shown in hexadecimal.
*
*  If the high-order bit of the byte is 1, then it is one of the following commands:
*
*    9t nn [vv]
*           Start playing note nn on tone generator t, replacing any previous note.  
*           Generators are numbered starting with 0. The note numbers are the MIDI 
*           numbers for the chromatic scale, with decimal 69 being Middle A (440 Hz).
*           If the -v option was given, a second byte is added to indicate note volume.
*
*    8t     Stop playing the note on tone generator t.
*
*    Ct ii  Change tone generator t to play instrument ii from now on. This will only
*           be generated if the -i option was given.
*
*    F0     End of score; stop playing.
*
*    E0     End of score; start playing again from the beginning.
*
*  If the high-order bit of the byte is 0, it is a command to delay for a while until
*  the next note change.  The other 7 bits and the 8 bits of the following byte are
*  interpreted as a 15-bit big-endian integer that is the number of milliseconds to
*  wait before processing the next command.  For example,
*
*     07 D0
*
*  would cause a delay of 0x07d0 = 2000 decimal millisconds, or 2 seconds.  Any tones
*  that were playing before the delay command will continue to play.
*
*  If the -d option is specified, the bytestream begins with a little header that tells
*  what optional information will be in the data. This makes the file more self-describing,
*  and allows music players to adapt to different kinds of files. The later Playtune
*  players do that. The header looks like this:
*
*    'Pt'   Two ascii characters that signal the presence of the header
*     nn    The length (in one byte) of the entire header, 6..255
*     ff1   A byte of flag bits, three of which are currently defined:
*               80 velocity information is present
*               40 instrument change information is present
*               20 translated percussion notes are present
*     ff2    Another byte of flags, currently undefined
*     tt     The number (in one byte) of tone generators actually used in this music.
*
*     Any subsequent header bytes covered by the count, if present, are currently undefined
*     and should be ignored by players.
*
*  Len Shustek, 4 Feb 2011 and later
*