fix "running status" bug; add volume, instruments, percussion, file h…

…eader, etc.

LICENSE.txt

@@ -1,14 +1,21 @@
-*   (C) Copyright 2011, 2013, 2015, Len Shustek
-*
-*   This program is free software: you can redistribute it and/or modify
-*   it under the terms of version 3 of the GNU General Public License as
-*   published by the Free Software Foundation at http://www.gnu.org/licenses,
-*   with Additional Permissions under term 7(b) that the original copyright
-*   notice and author attibution must be preserved and under term 7(c) that
-*   modified versions be marked as different from the original.
-*
-*   This program is distributed in the hope that it will be useful,
-*   but WITHOUT ANY WARRANTY; without even the implied warranty of
-*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-*   GNU General Public License for more details.
-*
+The MIT License (MIT)
+
+Copyright (c) 2016, Len Shustek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.txt

@@ -1,39 +1,42 @@
-/*--------------------------------------------------------------------------------
+/*********************************************************************************************
 *
+*  MIDITONES: Convert a MIDI file into a simple bytestream of notes
 *
-*                               About MIDITONES
 *
+*  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.
 *
-*  MIDITONES converts a MIDI music file into a much simplified stream of commands,
-*  so that a version of the music can be played on a synthesizer having only
-*  tone generators without any volume or tone controls.
+*  Volume ("velocity") and instrument information in the MIDI file can either be
+*  discarded or kept. All the tracks are prcoessed and merged into a single time-ordered
+*  stream of "note on", "note off", "change instrument" and "delay" commands.
 *
-*  Volume ("velocity") and instrument specifications in the MIDI files are generally
-*  discarded.  All the tracks are prcoessed and merged into a single time-ordered
-*  stream of "note on", "note off", and "delay" commands.
-*
-*  This was written for the "Playtune" Arduino library, which plays polyphonic music
-*  using up to 6 tone generators run by the timers on the processor.  See the separate
-*  documentation for Playtune.  But MIDITONES may prove useful for other tone
-*  generating systems.
+*  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
+*  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 (plus strlcpy and strlcat functions), and
-*  is meant to be executed from the command line.  There is no GUI interface.
+*  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.
 *
-*  The MIDI file format is complicated, and this has not been tested on a very
-*  wide variety of file types.  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.
-
-*  This has been tested only on a little-endian PC, but I think it should work on
-*  big-endian processors too.  Note that the MIDI file format is inherently
-*  big-endian.
+*  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 command line  *****
+*  *****  The MIDITONES command line  *****
 *
 *  To convert a MIDI file called "chopin.mid" into a command bytestream, execute
 *
@@ -45,73 +48,97 @@
 *
 *  The general form for command line execution is this:
 *
-*     miditones [-p] [-lg] [-lp] [-s1] [-tn] [-b] [-cn] [-kn] [-v] <basefilename>
+*     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.
+*  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 input file is the base name with the extension ".mid".  The output filename(s)
-*  are the base name with ".c", ".bin", and/or ".log" extensions.
 *
+* The best combination of options to use with the later Playtune music players is:
+*        -v -i -pt -d
 *
-*  The following command-line options can be specified:
 *
-*  -p   Only parse the MIDI file;  don't generate an output file.
+* 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 when generating a log to debug MIDI file parsing problems.
+*       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
-*
-*  -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.  Note that for the Arduino Playtunes
-*       library, it's ok to have the bytestream use more tone genreators than
-*       exist on your processor because any extra notes will be ignored, although
-*       it does make the file bigger than necessary . Of course, too many ignored
-*       notes will make the music sound really strange!
-*
-*  -b   Generate a binary file with the name <basefilename>.bin, instead of a
-*       C-language source file with the name <basefilename>.c.
+*          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"
 *
 *  -kn  Change the musical key of the output by n chromatic notes.
 *       -k-12 goes one octave down, -k12 goes one octave up, etc.
 *
-*  -v   Add velocity information to output
+*  -pi  Ignore notes in the MIDI percussion track 9 (also called 10 by some)
+*
+*  -dp  Generate IDE-dependent C code to define PROGMEM
+*
+*  -h   Give command-line help.
 *
 *
 *  *****  The score bytestream  *****
 *
-*  The generated bytestream is a series of commands that turn notes on and off, and
-*  start delays until the next note change.  Here are the details, with numbers
-*  shown in hexadecimal.
+*  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.  Generators are numbered
-*           starting with 0.  The notes numbers are the MIDI numbers for the chromatic
+*    9t nn [vv]
+*           Start playing note nn on tone generator t.  Generators are numbered
+*           starting with 0. The note numbers are the MIDI numbers for the chromatic
 *           scale, with decimal 60 being Middle C, and decimal 69 being Middle A (440 Hz).
-*           If the -v option is enabled, a second byte is added to indicate velocity.
+*           If the -v option was given, a second byte is added to indicate note volume.
 *
 *    8t     Stop playing the note on tone generator t.
 *
-*    F0     End of score: stop playing.
+*    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.
+*    E0     End of score; start playing again from the beginning.
 *           (Shown for completeness; MIDITONES won't generate this.)
 *
 *  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
+*  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,
 *
@@ -120,8 +147,22 @@
 *  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:
 *
-*  Len Shustek, 4 Feb 2011 and later
+*    '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
+*********************************************************************************************/