From ee76ad2d1fa997d09e26f0f217c7e43806dd69d4 Mon Sep 17 00:00:00 2001 From: Len Shustek Date: Tue, 15 Jan 2019 09:54:57 -0800 Subject: [PATCH] Major rewrite: queue out-of-order events to allow release/sustain note timing --- README.txt | 412 ++++++---- miditones.c | 2123 +++++++++++++++++++++++++++++-------------------- miditones.exe | Bin 60416 -> 72192 bytes 3 files changed, 1485 insertions(+), 1050 deletions(-) diff --git a/README.txt b/README.txt index f5f29dd..48ffd8c 100644 --- a/README.txt +++ b/README.txt @@ -1,171 +1,241 @@ -/********************************************************************************************* -* -* 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 -* -* The 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 .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 .bin, instead of a -* C-language source file with the name .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 .log file -* -* -lg Log output bytestream generation information to the .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 -* \ No newline at end of file + + MIDITONES: Convert a MIDI file into a simple bytestream of notes + + + MIDITONES compiles a MIDI music file into a much simplified compact time-ordered 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. + + MIDITONES was written for the "Playtune" series of Arduino and Teensy + microcontroller software synthesizers: + + www.github.com/LenShustek/arduino-playtune + This original version of Playtune, first released in 2011, uses a separate hardware timer + for each note to generate a square wave on an output pin. All the pins are then combined + with a simple resistor network connected to a speaker and/or amplifier. It can only play + as many simutaneous notes as there are timers. There is no volume modulation. + + www.github.com/LenShustek/Playtune_poll + This second vesion uses only one hardware timer that interrupts periodically at a fast + rate, and toggles square waves onto any number of digital output pins. It also implements + primitive volume modulation by changing the duty cycle of the square wave. The number of + simultaneous notes is limited only by the number of output pins and the speed of the processor. + + www.github.com/LenShustek/Playtune_samp + The third version also uses only one hardware timer interrupting frequently, but + uses the hardware digital-to-analog converter on high-performance microntrollers like + the Teensy to generate an analog wave that is the sum of stored samples of sounds for + many different instruments. The samples are scaled to the right frequency and volume, + and any number of instrument samples can be used and mapped to MIDI patches. The sound + quality is much better, although not in league with real synthesizers. It currently + only supports Teensy boards. + + www.github.com/LenShustek/Playtune_synth + The fourth version is an audio object for the PJRC Audio Library. + https://www.pjrc.com/teensy/td_libs_Audio.html + It allows up to 16 simultaneous sound generators that are internally mixed, at + the appropriate volume, to produce one monophonic audio stream. + Sounds are created from sampled one-cycle waveforms for any number of instruments, + each with its own attack-hold-decay-sustain-release envelope. Percussion sounds + (from MIDI channel 10) are generated from longer sampled waveforms of a complete + instrument strike. Each generator's volume is independently adjusted according to + the MIDI velocity of the note being played before all channels are mixed. + + www.github.com/LenShustek/ATtiny-playtune + This is a much simplified version that fits, with a small song, into an ATtiny + processor with only 4K of flash memory. It also using polling with only one timer, + and avoids multiplication or division at runtime for speed. It was written + for the Evil Mad Scientist menorah kit: + https://www.evilmadscientist.com/2009/new-led-hanukkah-menorah-kit/ + https://forum.evilmadscientist.com/discussion/263/making-the-menorah-play-music + (Imagine what you can do with the $1 8-pin ATtiny85 with a whopping 8K!) + + MIDITONES may also prove useful for other simple music synthesizers. There are + various forks of the code, and the Playtune players, on Githib. + + *** THE PROGRAM + + MIDITONES is written in standard ANSI C and is meant to be executed from the + command line. There is no GUI interface. + + 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. + + 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 near the + top of its source code. + + +*** THE 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 + + The 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 .mid, and the output filename(s) + are the base file name with .c, .h, .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 .bin, instead of a + C-language source file with the name .c. + + -t=n 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: + + -c=n 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. + + -dp Generate Arduino IDE-dependent C code that uses PROGMEM for the bytestream. + + -k=n Change the musical key of the output by n chromatic notes. + -k=-12 goes one octave down, -k=12 goes one octave up, etc. + + -lp Log input file parsing information to the .log file + + -lg Log output bytestream generation information to the .log file + + -n=x Put about "x" items on each line of the C file output + + -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. + + -pi Ignore notes in the MIDI percussion track 9 (also called 10 by some) + + -r Terminate the output file with a "restart" command instead of a "stop" command. + + -sn Use bytestream generation strategy "n". Two are currently implemented: + 1:favor track 1 notes instead of all tracks equally + 2:try to keep each track to its own tone generator + + -h Give command-line help. + + -delaymin=x Don't generate delays less than x milliseconds long, to reduce the number + of "delay" commands and thus make the bytestream smaller, at the expense of + moving notes slightly. The deficits are accumulated and eventually used, + so that there is no loss of synchronization in the long term. + The default is 0, which means timing is exact to the millisecond. + + -releasetime=x Stop each note x milliseconds before it is supposed to end. This results + in better sound separation between notes. It might also allow more notes to + be played with fewer tone generators, since there could be fewer + simultaneous notes playing. + + -notemin=x The releasetime notwithstanding, don't let the resulting note be reduced + to smaller than x milliseconds. Making releasetime very large and notemin + small results in staccato sounds. + + -attacktime=x The high-volume attack phase of a note lasts x milliseconds, after which + the lower-volume sustain phase begins, unless the release time makes it + too short. (Only valid with -v.) + + -attacknotemax=x Notes larger than x milliseconds won't have the attack/sustain profile + applied. That allows sustained organ-like pedaling. + + -sustainlevel=p The volume level during the sustain phase is p percent of the starting + note volume. (Only valid with -v.) + + -scorename Use as the name of the score in the generated C code + instead of "score", and name the file .h instead of + .c. That allows multiple scores to be directly #included + into an Arduino .ino file without modification. + + Note that for backwards compatibility and easier batch-file processing, the equal sign + for specifying an option's numeric value may be omitted. Also, numeric values may be + specified in hex as 0xhhhh. + +*** THE SCORE BYTESTREAM + + The generated bytestream is a series of commands to turn notes on and off, + change instruments, and request a delay until the next event time. + 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, + where the two characters are a hex representation of one byte: + + 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, the third byte specifies the 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, but start playing again from the beginning. This is + generated by the -r option. + + 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 volume 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, 2011 to 2019; see the change log. diff --git a/miditones.c b/miditones.c index 2dd74cd..5f45234 100644 --- a/miditones.c +++ b/miditones.c @@ -1,178 +1,250 @@ /********************************************************************************************* -* -* 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 -* -* The 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 .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 .bin, instead of a -* C-language source file with the name .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 .log file -* -* -lg Log output bytestream generation information to the .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 -* + + MIDITONES: Convert a MIDI file into a simple bytestream of notes + + + MIDITONES compiles a MIDI music file into a much simplified compact time-ordered 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. + + MIDITONES was written for the "Playtune" series of Arduino and Teensy + microcontroller software synthesizers: + + www.github.com/LenShustek/arduino-playtune + This original version of Playtune, first released in 2011, uses a separate hardware timer + for each note to generate a square wave on an output pin. All the pins are then combined + with a simple resistor network connected to a speaker and/or amplifier. It can only play + as many simutaneous notes as there are timers. There is no volume modulation. + + www.github.com/LenShustek/Playtune_poll + This second vesion uses only one hardware timer that interrupts periodically at a fast + rate, and toggles square waves onto any number of digital output pins. It also implements + primitive volume modulation by changing the duty cycle of the square wave. The number of + simultaneous notes is limited only by the number of output pins and the speed of the processor. + + www.github.com/LenShustek/Playtune_samp + The third version also uses only one hardware timer interrupting frequently, but + uses the hardware digital-to-analog converter on high-performance microntrollers like + the Teensy to generate an analog wave that is the sum of stored samples of sounds for + many different instruments. The samples are scaled to the right frequency and volume, + and any number of instrument samples can be used and mapped to MIDI patches. The sound + quality is much better, although not in league with real synthesizers. It currently + only supports Teensy boards. + + www.github.com/LenShustek/Playtune_synth + The fourth version is an audio object for the PJRC Audio Library. + https://www.pjrc.com/teensy/td_libs_Audio.html + It allows up to 16 simultaneous sound generators that are internally mixed, at + the appropriate volume, to produce one monophonic audio stream. + Sounds are created from sampled one-cycle waveforms for any number of instruments, + each with its own attack-hold-decay-sustain-release envelope. Percussion sounds + (from MIDI channel 10) are generated from longer sampled waveforms of a complete + instrument strike. Each generator's volume is independently adjusted according to + the MIDI velocity of the note being played before all channels are mixed. + + www.github.com/LenShustek/ATtiny-playtune + This is a much simplified version that fits, with a small song, into an ATtiny + processor with only 4K of flash memory. It also using polling with only one timer, + and avoids multiplication or division at runtime for speed. It was written + for the Evil Mad Scientist menorah kit: + https://www.evilmadscientist.com/2009/new-led-hanukkah-menorah-kit/ + https://forum.evilmadscientist.com/discussion/263/making-the-menorah-play-music + (Imagine what you can do with the $1 8-pin ATtiny85 with a whopping 8K!) + + MIDITONES may also prove useful for other simple music synthesizers. There are + various forks of the code, and the Playtune players, on Githib. + + *** THE PROGRAM + + MIDITONES is written in standard ANSI C and is meant to be executed from the + command line. There is no GUI interface. + + 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. + + 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 near the + top of its source code. + + +*** THE 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 + + The 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 .mid, and the output filename(s) + are the base file name with .c, .h, .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 .bin, instead of a + C-language source file with the name .c. + + -t=n 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: + + -c=n 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. + + -dp Generate Arduino IDE-dependent C code that uses PROGMEM for the bytestream. + + -k=n Change the musical key of the output by n chromatic notes. + -k=-12 goes one octave down, -k=12 goes one octave up, etc. + + -lp Log input file parsing information to the .log file + + -lg Log output bytestream generation information to the .log file + + -n=x Put about "x" items on each line of the C file output + + -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. + + -pi Ignore notes in the MIDI percussion track 9 (also called 10 by some) + + -r Terminate the output file with a "restart" command instead of a "stop" command. + + -sn Use bytestream generation strategy "n". Two are currently implemented: + 1:favor track 1 notes instead of all tracks equally + 2:try to keep each track to its own tone generator + + -h Give command-line help. + + -delaymin=x Don't generate delays less than x milliseconds long, to reduce the number + of "delay" commands and thus make the bytestream smaller, at the expense of + moving notes slightly. The deficits are accumulated and eventually used, + so that there is no loss of synchronization in the long term. + The default is 0, which means timing is exact to the millisecond. + + -releasetime=x Stop each note x milliseconds before it is supposed to end. This results + in better sound separation between notes. It might also allow more notes to + be played with fewer tone generators, since there could be fewer + simultaneous notes playing. + + -notemin=x The releasetime notwithstanding, don't let the resulting note be reduced + to smaller than x milliseconds. Making releasetime very large and notemin + small results in staccato sounds. + + -attacktime=x The high-volume attack phase of a note lasts x milliseconds, after which + the lower-volume sustain phase begins, unless the release time makes it + too short. (Only valid with -v.) + + -attacknotemax=x Notes larger than x milliseconds won't have the attack/sustain profile + applied. That allows sustained organ-like pedaling. + + -sustainlevel=p The volume level during the sustain phase is p percent of the starting + note volume. (Only valid with -v.) + + -scorename Use as the name of the score in the generated C code + instead of "score", and name the file .h instead of + .c. That allows multiple scores to be directly #included + into an Arduino .ino file without modification. + + Note that for backwards compatibility and easier batch-file processing, the equal sign + for specifying an option's numeric value may be omitted. Also, numeric values may be + specified in hex as 0xhhhh. + +*** THE SCORE BYTESTREAM + + The generated bytestream is a series of commands to turn notes on and off, + change instruments, and request a delay until the next event time. + 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, + where the two characters are a hex representation of one byte: + + 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, the third byte specifies the 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, but start playing again from the beginning. This is + generated by the -r option. + + 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 volume 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, 2011 to 2019; see the change log. + *---------------------------------------------------------------------------------------- * The MIT License (MIT) -* Copyright (c) 2011,2013,2015,2016, Len Shustek +* Copyright (c) 2011,2013,2015,2016,2019 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 @@ -193,85 +265,117 @@ *********************************************************************************************/ // formatted with: Astyle -style=lisp -indent=spaces=3 -mode=c -/* -* Change log -* 19 January 2011, L.Shustek, V1.0 -* -Initial release. -* 26 February 2011, L. Shustek, V1.1 -* -Expand the documentation generated in the output file. -* -End the binary output file with an "end of score" command. -* -Fix bug: Some "stop note" commands were generated too early. -* 04 March 2011, L. Shustek, V1.2 -* -Minor error message rewording. -* 13 June 2011, L. Shustek, V1.3 -* -Add -s2 strategy to try to keep each track on its own tone generator -* for when there are separate speakers. This obviously works only when -* each track is monophonic. (Suggested by Michal Pustejovsky) -* 20 November 2011, L. Shustek, V1.4 -* -Add -cn option to mask which channels (tracks) to process -* -Add -kn option to change key -* Both of these are in support of music-playing on my Tesla Coil. -* 05 December 2011, L. Shustek, V1.5 -* -Fix command line parsing error for option -s1 -* -Display the commandline in the C file output -* -Change to decimal instead of hex for note numbers in the C file output -* 06 August 2013, L. Shustek, V1.6 -* -Changed to allow compilation and execution in 64-bit environments -* by using C99 standard intN_t and uintN_t types for MIDI structures, -* and formatting specifications like "PRId32" instead of "ld". -* 04 April 2015, L. Shustek, V1.7 -* -Made friendlier to other compilers: import source of strlcpy and strlcat, -* fixed various type mismatches that the LCC compiler didn't fret about. -* Generate "const" for data initialization for compatibility with Arduino IDE v1.6.x. -* 23 January 2016, D. Blackketter, V1.8 -* -Fix warnings and errors building on Mac OS X via "gcc miditones.c" -* 25 January 2016, D. Blackketter, Paul Stoffregen, V1.9 -* -Merge in velocity output option from Arduino/Teensy Audio Library -* 26 June 2016, L. Shustek, V1.10 -* -Fix overflow problem in calculating long delays. (Thanks go to Tiago Rocha.) -* In the process I discover and work around an LCC 32-bit compiler bug. -* 14 August 2016: L. Shustek, V1.11 -* -Fix our interpretation of MIDI "running status": it applies only to MIDI events -* (8x through Ex), not, as we thought, also to Sysex (Fx) or Meta (FF) events. -* -Improve parsing of text events for the log. -* -Change log file note and patch numbers, etc., to decimal. -* -Document a summary of the MIDI file format so I don't have to keep looking it up. -* -Add -pi and -pt options to ignore or translate the MIDI percussion track 9. -* -Remove string.h for more portability; add strlength(). -* -Add -i option for recording instrument types in the bytestream. -* -Add -d option for generating a file description header. -* -Add -dp option to make generating the PROGMEM definition optional -* -Add -n option to specify number of items per output line -* -Do better error checking on options -* -Reformat option help -* 26 September 2016, Scott Allen, V1.12 -* - Fix spelling and minor formatting errors -* - Fix -p option parsing and handling, which broke when -pi and -pt were added -* - Fix handling of the -nx option to count more accurately -* - Give a proper error message for missing base name -* - Include the header and terminator in the score byte count -* 30 September 2016, Scott Allen, V1.13 -* - Allow -c channel numbers to be specified as hex or octal -* - Add -r to end the file with "repeat" instead of "score end" -* 30 September 2016, Len Shustek, V1.14 -* - Prevent unnecessary "note off" commands from being generated by delaying -* them until we see if a "note on" is generated before the next wait. -* Thanks to Scott Allen for inspiring me to do this. In the best case we've -* seen, this makes the bytestream 21% smaller! -* 13 November 2017, Earle Philhower, V1.15 -* - Allow META fields to be larger than 127 bytes. -* 2 January 2018, Kodest, V1.16 -* - Don't generate zero-length delays -* 13 September 2018, Paul Stoffregen, V1.17 - - Fix compile errors on Linux with gcc run in default mode -* 1 January 2019, Len Shustek, V1.18 - - Fix the bug found by Chris van Marle (thanks!) that caused delays not to be - generated until the tempo was set. (The default is 500,000 usec/beat, not 0.) - - Abandon LCC and compile under Microsoft Visual Studio 2017. - - Reformat to condense the source code, so you see more protein and less - syntactic sugar on each screen. +/* Change log + + 19 January 2011, L.Shustek, V1.0 + -Initial release. + 26 February 2011, L. Shustek, V1.1 + -Expand the documentation generated in the output file. + -End the binary output file with an "end of score" command. + -Fix bug: Some "stop note" commands were generated too early. + 04 March 2011, L. Shustek, V1.2 + -Minor error message rewording. + 13 June 2011, L. Shustek, V1.3 + -Add -s2 strategy to try to keep each track on its own tone generator + for when there are separate speakers. This obviously works only when + each track is monophonic. (Suggested by Michal Pustejovsky) + 20 November 2011, L. Shustek, V1.4 + -Add -cn option to mask which channels (tracks) to process + -Add -kn option to change key + Both of these are in support of music-playing on my Tesla Coil. + 05 December 2011, L. Shustek, V1.5 + -Fix command line parsing error for option -s1 + -Display the commandline in the C file output + -Change to decimal instead of hex for note numbers in the C file output + 06 August 2013, L. Shustek, V1.6 + -Changed to allow compilation and execution in 64-bit environments + by using C99 standard intN_t and uintN_t types for MIDI structures, + and formatting specifications like "PRId32" instead of "ld". + 04 April 2015, L. Shustek, V1.7 + -Made friendlier to other compilers: import source of strlcpy and strlcat, + fixed various type mismatches that the LCC compiler didn't fret about. + Generate "const" for data initialization for compatibility with Arduino IDE v1.6.x. + 23 January 2016, D. Blackketter, V1.8 + -Fix warnings and errors building on Mac OS X via "gcc miditones.c" + 25 January 2016, D. Blackketter, Paul Stoffregen, V1.9 + -Merge in velocity output option from Arduino/Teensy Audio Library + 26 June 2016, L. Shustek, V1.10 + -Fix overflow problem in calculating long delays. (Thanks go to Tiago Rocha.) + In the process I discover and work around an LCC 32-bit compiler bug. + 14 August 2016: L. Shustek, V1.11 + -Fix our interpretation of MIDI "running status": it applies only to MIDI events + (8x through Ex), not, as we thought, also to Sysex (Fx) or Meta (FF) events. + -Improve parsing of text events for the log. + -Change log file note and patch numbers, etc., to decimal. + -Document a summary of the MIDI file format so I don't have to keep looking it up. + -Add -pi and -pt options to ignore or translate the MIDI percussion track 9. + -Remove string.h for more portability; add strlength(). + -Add -i option for recording instrument types in the bytestream. + -Add -d option for generating a file description header. + -Add -dp option to make generating the PROGMEM definition optional + -Add -n option to specify number of items per output line + -Do better error checking on options + -Reformat option help + 26 September 2016, Scott Allen, V1.12 + -Fix spelling and minor formatting errors + -Fix -p option parsing and handling, which broke when -pi and -pt were added + -Fix handling of the -nx option to count more accurately + -Give a proper error message for missing base name + -Include the header and terminator in the score byte count + 30 September 2016, Scott Allen, V1.13 + -Allow -c channel numbers to be specified as hex or octal + -Add -r to end the file with "repeat" instead of "score end" + 30 September 2016, Len Shustek, V1.14 + -Prevent unnecessary "note off" commands from being generated by delaying + them until we see if a "note on" is generated before the next wait. + Thanks to Scott Allen for inspiring me to do this. In the best case we've + seen, this makes the bytestream 21% smaller! + 13 November 2017, Earle Philhower, V1.15 + -Allow META fields to be larger than 127 bytes. + 2 January 2018, Kodest, V1 + -Don't generate zero-length delays + 13 September 2018, Paul Stoffregen, V1.17 + -Fix compile errors on Linux with gcc run in default mode + 1 January 2019, Len Shustek, V1.18 + -Fix the bug found by Chris van Marle (thanks!) that caused delays not to be + generated until the tempo was set. (The default is 500,000 usec/beat, not 0.) + -Abandon LCC and compile under Microsoft Visual Studio 2017. + -Reformat to condense the source code, so you see more protein and less + syntactic sugar on each screen. + 4 January 2019, Len Shustek, V1.19 + -As suggested by Chris van Marle, add the "-mx" parameter to allow timing to be + flexible in order to avoid small delays and thus save space in the bytestream. + -Don't discard fractions of a millisecond in the delay timing, to avoid gradual + drift of the music. This has been a minor problem since V1.0 in 2011. + 4 January 2019, Len Shustek, V2.00 + -Major revision: completely rewrite score processing to allow out-of-order event + queuing. That lets us implement "release" time that ends notes early, and + "sustain" time at reduced volume, if we are encoding volume. You can sometimes + take advantage of release time to play more notes with the same number of tone + generators. It also can improve the sounds for repeated notes, although it + might be at the expense of increased bytestream size. + -Change the treatment of tracks and channels to more faithfully reproduce the + synthesizer model: each channel is an instrument, and can play multiple notes, + but only one at each frequency. It doesn't matter which tracks they come from. + -Simplify and generalize option parsing, and rename some of the newer ones. + -Add -scorename so multiple scores can be directly #included into .ino files + without manually editing the names. + +future version ideas + + -Perhaps elide "note off/note on" event sequences for the same note that + become adjacent because of -delaymin. Does that happen much, or at all? + + -Allow the flexibility to specify note timing on a track-by-track or + channel-by-channel basis, by using a .cfg file which has + commands like these: + options + track 1 // melody + options -attacktime=100 -sustainlevel=50% -releasetime=10000 -notemin=200 + channel 8 // organ + options -attacktime=1000 -sustainlevel=80% -releasetime=100 -notemin=200 */ -#define VERSION "1.18" +#define VERSION "2.00" /*-------------------------------------------------------------------------------------------- @@ -279,6 +383,7 @@ A CONCISE SUMMARY OF MIDI FILE FORMAT L. Shustek, 16 July 2016. Gleaned from http://www.music.mcgill.ca/~ich/classes/mumt306/StandardMIDIfileformat.html +but also check out http://midi.teragonaudio.com/tech/miditech.htm Notation: is 1-4 bytes of 7-bit data, concatenated into one 7- to 28-bit number. The high bit of the last byte is 0. @@ -291,9 +396,16 @@ a MIDI file is: a header_chunk is: "MThd" 00000006 ffff nnnn dddd + 00000006 is the number of bytes in the rest of the header + ffff is the format type (we have only seen type 1) + nnnn is the number of tracks + dddd is the number of ticks per beat (ie, per quarter note) + (it is often 480 or 240) a track_chunk is: "MTrk" llllllll { track_event}... + llllllll is the length of the track data, in bytes + is the number of ticks to delay before the track_event a running status track_event is: 0x to 7x: assume a missing 8n to En event code which is the same as the last MIDI-event track_event @@ -331,14 +443,90 @@ a meta event track_event is: FF 06 "xx"... name of marked point in the score FF 07 "xx"... description of cue point in the score FF 20 01 0c default channel for subsequent events without a channel is c + FF 21 01 pp MIDI port is pp FF 2F 00 end of track - FF 51 03 tttttt set tempo in microseconds per quarter-note + FF 51 03 tttttt set tempo in microseconds per quarter-note, for all tracks FF 54 05 hhmmssfrff set SMPTE time to start the track FF 58 04 nnddccbb set time signature FF 59 02 sfmi set key signature FF 7F data sequencer-specific data ---------------------------------------------------------------------------------------------*/ +Note that "set tempo" events are supposed to occur in only one track (generally the first), +which may or may not also contain MIDI note events. +See https://stackoverflow.com/questions/1080297/how-does-midi-tempo-message-apply-to-other-tracks + --------------------------------------------------------------------------------------------*/ + +/*--------------- processing outline ----------------------------------- +Lots of details are omitted. Note that MIDI track parsing is based +on counting "ticks", but our queueing is based on real-time seconds. +The number of ticks per second changes with the tempo. + +noteinfo + time (of start or end), track, channel, note, instrument, volume +track status + time in ticks, cmd, chan, note, volume +tgen status + playing? stopnote_pending? + noteinfo +channel status + instrument, {note_playing?, noteinfo}[slots] +queue entry: + {PLAY|STOP}, noteinfo + + process track data + forall trks: find next note + do // whole song + earliest_track time in ticks = min(trk->time) + accumuulate running absolute time (for queuing) based on the current tempo + if CMD_TEMPO, + set global tempo + find next note + else if CMD_PLAYNOTE + find a !note_playing[] channel slot to use + queue CMD_PLAYNOTE at time, noteinfo + find next note + else if CMD_STOPNOTE + find the note's slot among the channel's notes_playing + compute Sustain and Release times based on ADSR profile and note length + if(Sustain) queue CMD_PLAYNOTE at Sustain time, noteinfo with adjusted volume + queue CMD_STOPNOTE at Release time (or now), noteinfo + remove from channel's notes_playing + find next note + while not all CMD_TRACKDONE + +find next note + do forever + t->time += varlen + if "note off", CMD_STOPNOTE, return + if "note on", CMD_PLAYNOTE, return + if "tempo", CMD_TEMPO, return + if "program patch", change channel's instrument + else log a comment about the MIDI event + if end of track, CMD_TRACKDONE, return + +queue command + if queue has no room, output queue entries + insertion-sort the new item into the queue based on the time + +output queue entries at the oldest time + static output time, time deficit + if time has advanced + output DELAY + for all entries at the same oldest time + if STOP + find tgen matching channel and note + tgen: stopnote pending, not playing + else PLAY + find a tgen not playing (best: same, good: same instrument, ok: any free) + tgen "not stopnote pending", "playing" + if instrument change, output "set instrument" + output PLAY tgen + remove from queue + for all tgen + if stopnote pending + output STOP tgen + tgen: stopnote not pending +-----------------------------------------------------------------------------*/ #include #include @@ -346,7 +534,8 @@ a meta event track_event is: #include #include #include - +typedef unsigned char byte; +typedef uint32_t timestamp; // see note about this in the queuing routines /*********** MIDI file header formats *****************/ @@ -361,18 +550,20 @@ struct track_header { int8_t MTrk[4]; uint32_t track_size; }; - /*********** Global variables ******************/ -#define MAX_TONEGENS 16 /* max tone generators: tones we can play simultaneously */ -#define DEFAULT_TONEGENS 6 /* default number of tone generators */ -#define MAX_TRACKS 24 /* max number of MIDI tracks we will process */ -#define PERCUSSION_TRACK 9 /* the track MIDI uses for percussion sounds */ -#define DEFAULT_TEMPO 500000L /* the MIDI-specified default tempo in usec/beat */ +#define MAX_TONEGENS 16 // max tone generators: tones we can play simultaneously +#define DEFAULT_TONEGENS 6 // default number of tone generators +#define MAX_TRACKS 24 // max number of MIDI tracks we will process +#define PERCUSSION_TRACK 9 // the track MIDI uses for percussion sounds +#define NUM_CHANNELS 16 // MIDI-specified number of channels +#define MAX_CHANNELNOTES 16 // max number of notes playing simultaneously on a channel +#define DEFAULT_TEMPO 500000L // the MIDI-specified default tempo in usec/beat +#define DEFAULT_BEATTIME 240 // the MIDI-specified default ticks per beat bool loggen, logparse, parseonly, strategy1, strategy2, binaryoutput, define_progmem, - velocityoutput, instrumentoutput, percussion_ignore, percussion_translate, do_header, - gen_restart; + volume_output, instrumentoutput, percussion_ignore, percussion_translate, do_header, + gen_restart, scorename; FILE *infile, *outfile, *logfile; uint8_t *buffer, *hdrptr; unsigned long buflen; @@ -384,240 +575,213 @@ int num_tonegens = DEFAULT_TONEGENS; int num_tonegens_used = 0; int instrument_changes = 0; int note_on_commands = 0; -unsigned channel_mask = 0xffff; // bit mask of channels to process -int keyshift = 0; // optional chromatic note shift for output file +int notes_skipped = 0; +int events_delayed = 0; +int stopnotes_without_playnotes = 0; +int playnotes_without_stopnotes = 0; +int sustainphases_skipped = 0; +int sustainphases_done = 0; +int consecutive_delays = 0; +bool last_output_was_delay = false; +int noteinfo_overflow = 0, noteinfo_notfound = 0; +unsigned channel_mask = 0xffff; // bit mask of channels to process +int keyshift = 0; // optional chromatic note shift for output file +unsigned long delaymin_usec = 0; // events this close get merged together to save bytestream space +unsigned long releasetime_usec = 0; // release time in usec for silence at the end of notes +unsigned long notemin_usec = 250; // minimum note time in usec after the release is deducted +unsigned long attacktime_usec = 0; // the high volume attack phase lasts this time, if not 0 (only for -v) +unsigned long attacknotemax_usec = ULONG_MAX; // the longest note to which the attack/sustain profile is used (only for -v) +int sustainlevel_pct = 50; // the percent of attack volume for the sustain phase (only for -v) long int outfile_bytecount = 0; -unsigned int ticks_per_beat = 240; -unsigned long timenow = 0; -unsigned long tempo; /* current tempo in usec/qnote */ - -struct tonegen_status { /* current status of a tone generator */ - bool playing; /* is it playing? */ - bool stopnote_pending; /* do we need to stop this generator before the next wait? */ - int track; /* if so, which track is the note from? */ - int note; /* what note is playing? */ - int instrument; /* what instrument? */ -} tonegen[MAX_TONEGENS] = { - { - 0 } }; - -struct track_status { /* current processing point of a MIDI track */ - uint8_t *trkptr; /* ptr to the next note change */ - uint8_t *trkend; /* ptr past the end of the track */ - unsigned long time; /* what time we're at in the score */ - unsigned long tempo; /* the tempo last set, in usec per qnote */ - unsigned int preferred_tonegen; /* for strategy2, try to use this generator */ - unsigned char cmd; /* CMD_xxxx next to do */ - unsigned char note; /* for which note */ - unsigned char chan; /* from which channel it was */ - unsigned char velocity; /* the current volume */ - unsigned char last_event; /* the last event, for MIDI's "running status" */ - bool tonegens[MAX_TONEGENS]; /* which tone generators our notes are playing on */ -} track[MAX_TRACKS] = { - { - 0 } }; - -int midi_chan_instrument[16] = { - 0 }; /* which instrument is currently being played on each channel */ +unsigned int ticks_per_beat = DEFAULT_BEATTIME; -/* output bytestream commands, which are also stored in track_status.cmd */ +unsigned long timenow_ticks = 0; // the current processing time in ticks +timestamp timenow_usec = 0; // the current processing time in usec +unsigned long timenow_usec_updated = 0; // when, in ticks, we last updated timenow_usec using the current tempo +timestamp output_usec = 0; // the time we last output, in usec +unsigned int output_deficit_usec = 0; // the leftover usec < 1000 still to be used for a "delay" +unsigned long tempo; // current global tempo in usec/beat + +int tempo_changes = 0; // how many times we changed the global tempo +long int delays_saved = 0; // how many delays were saved because of non-zero merge time + +/* output bytestream commands, which are also stored in track_status.cmd */ #define CMD_PLAYNOTE 0x90 /* play a note: low nibble is generator #, note is next byte */ #define CMD_STOPNOTE 0x80 /* stop a note: low nibble is generator # */ #define CMD_INSTRUMENT 0xc0 /* change instrument; low nibble is generator #, instrument is next byte */ #define CMD_RESTART 0xe0 /* restart the score from the beginning */ #define CMD_STOP 0xf0 /* stop playing */ -/* if CMD < 0x80, then the other 7 bits and the next byte are a 15-bit number of msec to delay */ - -/* these other commands stored in the track_status.com */ +/* the following other commands are stored in the track_status.com */ #define CMD_TEMPO 0xFE /* tempo in usec per quarter note ("beat") */ #define CMD_TRACKDONE 0xFF /* no more data left in this track */ -struct file_hdr_t { /* what the optional file header looks like */ - char id1; // 'P' - char id2; // 't' - unsigned char hdr_length; // length of whole file header - unsigned char f1; // flag byte 1 - unsigned char f2; // flag byte 2 - unsigned char num_tgens; // how many tone generators are used by this score -} file_header = { - 'P', 't', sizeof (struct file_hdr_t), 0, 0, MAX_TONEGENS }; - +struct file_hdr_t { // what our optional file header looks like + char id1; // 'P' + char id2; // 't' + byte hdr_length; // length of whole file header + byte f1; // flag byte 1 #define HDR_F1_VOLUME_PRESENT 0x80 #define HDR_F1_INSTRUMENTS_PRESENT 0x40 #define HDR_F1_PERCUSSION_PRESENT 0x20 - + byte f2; // flag byte 2 + byte num_tgens; // how many tone generators are used by this score +} file_header = { + 'P', 't', sizeof (struct file_hdr_t), 0, 0, MAX_TONEGENS }; long int file_header_num_tgens_position; /************** command-line processing *******************/ -void SayUsage (char *programName) { +void check_option(bool condition, char *msg) { + if (!condition) { + fprintf(stderr, "*** %s\n", msg); + exit(8); } } + +bool opt_key(const char* arg, const char* keyword) { + do { // check for a keyword option and nothing after it + if (tolower(*arg++) != *keyword++) return false; } + while (*keyword); + return *arg == '\0'; } + +bool opt_int(const char* arg, const char* keyword, int *pval, int min, int max) { + do { // check for a "keyword=integer" option and nothing after it + if (tolower(*arg++) != *keyword++) + return false; } + while (*keyword); + if (*arg == '=') ++arg; // = is optional, actually + int num, nch; + if (sscanf(arg, *arg == '0' && *(arg + 1) == 'x' ? "%x%n" : "%d%n", &num, &nch) != 1) return false; + if (num < min || num > max || arg[nch] != '\0') return false; + *pval = num; + return true; } + +bool opt_str(const char* arg, const char* keyword, const char** str) { + do { // check for a "keyword=string" option + if (tolower(*arg++) != *keyword++) return false; } + while (*keyword); + *str = arg; // ptr to "string" part, which could be null + return true; } + +void SayUsage(char *programName) { static char *usage[] = { "Convert MIDI files to an Arduino PLAYTUNE bytestream", "", "Use: miditones ", " input file will be .mid", - " output file will be .bin or .c", + " output file will be .bin or .c or .h", " log file will be .log", "", "Commonly-used options:", - " -v include velocity data", - " -i include instrument change commands", - " -pt translate notes in the percussion track to notes 129 to 255", - " -d include a self-describing file header", - " -b generate binary file output instead of C source text", - " -tn use at most n tone generators (default is 6, max is 16)", + " -v include volume data", + " -i include instrument change commands", + " -pt translate notes in the percussion track to notes 129 to 255", + " -d include a self-describing file header", + " -b generate a binary file output instead of C source code", + " -t=n use at most n tone generators (default is 6, max is 16)", "", " The best options for later Playtune music players are: -v -i -pt -d", "", "Lesser-used command-line options:", - " -p parse only, don't generate bytestream", - " -lp log input parsing", - " -lg log output generation", - " -nx put about x items on each line of the C file output", - " -s1 strategy 1: favor track 1", - " -s2 strategy 2: try to assign tracks to specific tone generators", - " -cn mask for which tracks to process, e.g. -c3 for only 0 and 1", - " -kn key shift in chromatic notes, positive or negative", - " -pi ignore notes in the percussion track (9)", - " -dp define PROGMEM in output C code", - " -r terminate output file with \"restart\" instead of \"stop\" command", + " -c=n mask for which tracks to process, e.g. -c3 for only 0 and 1", + " -dp define PROGMEM in output C code", + " -k=n key shift in chromatic notes, positive or negative", + " -lp log input parsing", + " -lg log output generation", + " -n=n put about n items on each line of the C file output", + " -p parse only, don't generate bytestream", + " -pi ignore notes in the percussion track, 9", + " -r terminate output file with \"restart\" instead of \"stop\" command", + " -s1 strategy 1: favor track 1", + " -s2 strategy 2: try to assign tracks to specific tone generators", + " -delaymin=x minimum delay is x msec, to save bytestream space", + " -attacktime=x the high volume attack phase lasts x msec", + " -attacknotemax=x notes over x msec don't use the attack/sustain profile", + " -sustainlevel=p the sustain level is p percent of maximum volume", + " -releasetime=x release each note x msec before it ends", + " -notemin=x don't let release shorten the note to less than x msec", + " -scorename use as the score name in a .h file", NULL }; - int i = 0; - while (usage[i] != NULL) - fprintf (stderr, "%s\n", usage[i++]); } - + for (int i=0; usage[i] != NULL; ++i) + fprintf(stderr, "%s\n", usage[i]); } int HandleOptions (int argc, char *argv[]) { - /* returns the index of the first argument that is not an option; i.e. - does not start with a dash or a slash*/ - - int i, nch, firstnonoption = 0; - - /* --- The following skeleton comes from C:\lcc\lib\wizard\textmode.tpl. */ - for (i = 1; i < argc; i++) { + /* returns the index of the first argument that is not an option, + i.e. does not start with a dash or a slash */ + int i, firstnonoption = 0; for (i = 1; i < argc; i++) { if (argv[i][0] == '/' || argv[i][0] == '-') { - switch (toupper (argv[i][1])) { - case 'H': - case '?': - SayUsage (argv[0]); - exit (1); - case 'L': - if (toupper (argv[i][2]) == 'G') - loggen = true; - else if (toupper (argv[i][2]) == 'P') - logparse = true; - else - goto opterror; - if (argv[i][3] != '\0') - goto opterror; - break; - case 'P': - if (argv[i][2] == '\0') { - parseonly = true; - break; } - else if (toupper (argv[i][2]) == 'I') - percussion_ignore = true; - else if (toupper (argv[i][2]) == 'T') - percussion_translate = true; - else - goto opterror; - if (argv[i][3] != '\0') - goto opterror; - break; - case 'B': - binaryoutput = true; - if (argv[i][2] != '\0') - goto opterror; - break; - case 'V': - velocityoutput = true; - if (argv[i][2] != '\0') - goto opterror; - break; - case 'I': - instrumentoutput = true; - if (argv[i][2] != '\0') - goto opterror; - break; - case 'S': - if (argv[i][2] == '1') - strategy1 = true; - else if (argv[i][2] == '2') - strategy2 = true; - else - goto opterror; - if (argv[i][3] != '\0') - goto opterror; - break; - case 'T': - if (sscanf (&argv[i][2], "%d%n", &num_tonegens, &nch) != 1 - || num_tonegens < 1 || num_tonegens > MAX_TONEGENS) - goto opterror; - printf ("Using %d tone generators.\n", num_tonegens); - if (argv[i][2 + nch] != '\0') - goto opterror; - break; - case 'N': - if (sscanf (&argv[i][2], "%d%n", &outfile_maxitems, &nch) != 1 || outfile_maxitems < 1) - goto opterror; - if (argv[i][2 + nch] != '\0') - goto opterror; - break; - case 'C': - if (sscanf (&argv[i][2], "%i%n", &channel_mask, &nch) != 1 || channel_mask > 0xffff) - goto opterror; - printf ("Channel (track) mask is %04X.\n", channel_mask); - if (argv[i][2 + nch] != '\0') - goto opterror; - break; - case 'K': - if (sscanf (&argv[i][2], "%d%n", &keyshift, &nch) != 1 || keyshift < -100 - || keyshift > 100) - goto opterror; - printf ("Using keyshift %d.\n", keyshift); - if (argv[i][2 + nch] != '\0') - goto opterror; - break; - case 'D': - if (argv[i][2] == '\0') { - do_header = true; - break; } - if (toupper (argv[i][2]) == 'P') - define_progmem = true; - else - goto opterror; - if (argv[i][3] != '\0') - goto opterror; - break; - case 'R': - gen_restart = true; - if (argv[i][2] != '\0') - goto opterror; - break; - /* add more option switches here */ -opterror: - default: - fprintf (stderr, "\n*** unknown option: %s\n\n", argv[i]); - SayUsage (argv[0]); - exit (4); } } + int tempint; + char *arg = argv[i] + 1; + if (opt_key(arg, "h") || opt_key(arg, "?")) { + SayUsage(argv[0]); exit(1); } + else if (opt_key(arg, "b")) binaryoutput = true; + else if (opt_int(arg, "c", &channel_mask, 1, 0xffff)) + printf("Channel (track) mask is %04X\n", channel_mask); + else if (opt_key(arg, "d")) do_header = true; + else if (opt_key(arg, "dp")) define_progmem = true; + else if (opt_key(arg, "lg")) loggen = true; + else if (opt_key(arg, "i")) instrumentoutput = true; + else if (opt_int(arg, "k", &keyshift, -100, 100)) + printf("Using keyshift %d\n", keyshift); + else if (opt_key(arg, "lp")) logparse = true; + else if (opt_int(arg, "n", &outfile_maxitems, 1, INT_MAX)); + else if (opt_key(arg, "p")) parseonly = true; + else if (opt_key(arg, "pi")) percussion_ignore = true; + else if (opt_key(arg, "pt")) percussion_translate = true; + else if (opt_key(arg, "r")) gen_restart = true; + else if (opt_int(arg, "delaymin", &tempint, 1, 1000)) delaymin_usec = tempint * 1000; + else if (opt_int(arg, "releasetime", &tempint, 0, INT_MAX)) releasetime_usec = tempint * 1000; + else if (opt_int(arg, "notemin", &tempint, 0, INT_MAX)) notemin_usec = tempint * 1000; + else if (opt_int(arg, "attacktime", &tempint, 0, INT_MAX)) { + attacktime_usec = tempint * 1000; + check_option(volume_output, "-attacktime only works with -v"); } + else if (opt_int(arg, "attacknotemax", &tempint, 0, INT_MAX)) { + attacknotemax_usec = tempint * 1000; + check_option(volume_output, "-attacknotemax only works with -v"); } + else if (opt_int(arg, "sustainlevel", &sustainlevel_pct, 1, 100)) + check_option(volume_output, "-sustainlevel only works with -v"); + else if (opt_key(arg, "s1")) strategy1 = true; + else if (opt_key(arg, "s2")) strategy2 = true; + else if (opt_key(arg, "scorename")) scorename = true; + else if (opt_int(arg, "t", &num_tonegens, 1, MAX_TONEGENS)) + printf("Using %d tone generators\n", num_tonegens); + else if (opt_key(arg, "v")) volume_output = true; + /* add more option switches here */ + else { + fprintf(stderr, "\n*** bad option: %s\n\n", argv[i]); + SayUsage(argv[0]); + exit(4); } } else { firstnonoption = i; break; } } return firstnonoption; } -void print_command_line (int argc, char *argv[]) { - int i; - fprintf (outfile, "// command line: "); - for (i = 0; i < argc; i++) - fprintf (outfile, "%s ", argv[i]); - fprintf (outfile, "\n"); } +void print_command_line (FILE *file, int argc, char *argv[]) { + fprintf (file, "// command line: "); + for (int i = 0; i < argc; i++) fprintf (file, "%s ", argv[i]); + fprintf (file, "\n"); } /**************** utility routines **********************/ +void assert(bool condition, char *msg) { + if (!condition) { + fprintf(stderr, "*** internal assertion error: %s\n", msg); + if (logfile) fprintf(logfile, "*** internal assertion error: %s\n", msg); + exit(8); } } + +/* announce a fatal MIDI file format error */ +void midi_error(char *msg, byte *bufptr) { + fprintf(stderr, "---> MIDI file error at position %04X (%d): %s\n", + (uint16_t)(bufptr - buffer), (uint16_t)(bufptr - buffer), msg); + byte *ptr = bufptr - 16; // print some bytes surrounding the error + if (ptr < buffer) ptr = buffer; + for (; ptr <= bufptr + 16 && ptr < buffer + buflen; ++ptr) + fprintf(stderr, ptr == bufptr ? " [%02X] " : "%02X ", *ptr); + fprintf(stderr, "\n"); + exit(8); } + /* portable string length */ int strlength (const char *str) { int i; @@ -629,33 +793,26 @@ size_t miditones_strlcpy (char *dst, const char *src, size_t siz) { char *d = dst; const char *s = src; size_t n = siz; - /* Copy as many bytes as will fit */ - if (n != 0) { + if (n != 0) { /* Copy as many bytes as will fit */ while (--n != 0) { - if ((*d++ = *s++) == '\0') - break; } } - /* Not enough room in dst, add NUL and traverse rest of src */ - if (n == 0) { - if (siz != 0) - *d = '\0'; /* NUL-terminate dst */ - while (*s++); } + if ((*d++ = *s++) == '\0') break; } } + if (n == 0) { /* Not enough room in dst, add NUL and traverse rest of src */ + if (siz != 0) *d = '\0'; /* NUL-terminate dst */ + while (*s++) ; } return (s - src - 1); /* count does not include NUL */ } /* safe string concatenation */ - size_t miditones_strlcat (char *dst, const char *src, size_t siz) { char *d = dst; const char *s = src; size_t n = siz; size_t dlen; /* Find the end of dst and adjust bytes left but don't go past end */ - while (n-- != 0 && *d != '\0') - d++; + while (n-- != 0 && *d != '\0') d++; dlen = d - dst; n = siz - dlen; - if (n == 0) - return (dlen + strlength (s)); + if (n == 0) return (dlen + strlength (s)); while (*s != '\0') { if (n != 1) { *d++ = *s; @@ -666,38 +823,19 @@ size_t miditones_strlcat (char *dst, const char *src, size_t siz) { } /* match a constant character sequence */ - int charcmp (const char *buf, const char *match) { int len, i; len = strlength (match); for (i = 0; i < len; ++i) - if (buf[i] != match[i]) - return 0; + if (buf[i] != match[i]) return 0; return 1; } -/* announce a fatal MIDI file format error */ - -void midi_error (char *msg, unsigned char *bufptr) { - unsigned char *ptr; - fprintf (stderr, "---> MIDI file error at position %04X (%d): %s\n", - (uint16_t) (bufptr - buffer), (uint16_t) (bufptr - buffer), msg); - /* print some bytes surrounding the error */ - ptr = bufptr - 16; - if (ptr < buffer) - ptr = buffer; - for (; ptr <= bufptr + 16 && ptr < buffer + buflen; ++ptr) - fprintf (stderr, ptr == bufptr ? " [%02X] " : "%02X ", *ptr); - fprintf (stderr, "\n"); - exit (8); } - /* check that we have a specified number of bytes left in the buffer */ - -void chk_bufdata (unsigned char *ptr, unsigned long int len) { +void chk_bufdata (byte *ptr, unsigned long int len) { if ((unsigned) (ptr + len - buffer) > buflen) midi_error ("data missing", ptr); } /* fetch big-endian numbers */ - uint16_t rev_short (uint16_t val) { return ((val & 0xff) << 8) | ((val >> 8) & 0xff); } @@ -707,7 +845,6 @@ uint32_t rev_long (uint32_t val) { /* account for new items in the non-binary output file and generate a newline every so often. */ - void outfile_items (int n) { outfile_bytecount += n; outfile_itemcount += n; @@ -715,9 +852,319 @@ void outfile_items (int n) { fprintf (outfile, "\n"); outfile_itemcount = 0; } } +//******* structures for recording track, channel, and tone generator status + +// Note that the tempo can change as notes are played, maybe many times. +// In order to keep track of how long notes are to play, we have to incrementally +// accumulate the duration of all playing notes every time the tempo changes, and +// then one final time when the "stop note" event occurs. + +struct noteinfo { // everything we might care about as a note plays + timestamp time_usec; // when it starts or stops, in absolute usec since song start + int track, channel, note, instrument, volume; // all the nitty-gritty about it +}; + +struct tonegen_status { // current status of a tone generator + bool playing; // is it playing? + bool stopnote_pending; // are we due to issue a stop note command? + struct noteinfo note; // if so, the details of the note being played +} tonegen[MAX_TONEGENS] = { 0 }; + +struct track_status { // current status of a MIDI track + uint8_t *trkptr; // ptr to the next event we care about + uint8_t *trkend; // ptr just past the end of the track + unsigned long time; // what time we're at in the score, in ticks + unsigned long tempo; // the last tempo set on this track + int preferred_tonegen; // for strategy2: try to use this generator + byte cmd; // next CMD_xxxx event coming up + byte chan, note, volume; // if it is CMD_PLAYNOTE or CMD_STOPNOTE, the note info + byte last_event; // the last event, for MIDI's "running status" +} track[MAX_TRACKS] = { 0 }; + +struct channel_status { // current status of a channel + int instrument; // which instrument this channel currently plays + bool note_playing[MAX_CHANNELNOTES]; // slots for notes that are playing on this channel + struct noteinfo notes_playing[MAX_CHANNELNOTES]; // information about them +} channel[NUM_CHANNELS] = { 0 }; + +char *describe(struct noteinfo *np) { // create a description of a note + // WARNING: returns a pointer to a static string, so only call once per line, in a printf! + static char notedescription[100]; + sprintf(notedescription, "at %lu.%03lu msec, note %d (0x%02X) track %d channel %d volume %d instrument %d", + np->time_usec / 1000, np->time_usec % 1000, np->note, np->note, + np->track, np->channel, np->volume, np->instrument); + return notedescription; } + +/************** output reorder queue routines ****************** + +We queue commands to be issued at arbitrary times and sort them in time order. We flush +them out, allocating tone generators and creating the output bytestream, only as needed +to get more space in the queue. As we do that, we generate the "delay" commands required. + +All the queuing must be done with a microsecond time base, not ticks, because the tempo, +which controls the duration of ticks, may (and does!) change while notes are being played. + +We currently define "timestamps" by typedef as uint32_t, which is enough for songs as long +as 71 minutes. If longer songs are required, change it to uint64_t. + +We assume that "unsigned long" variables are big enough to track the total number of ticks +in a song. If they are 32 bits, the typical 480 ticks/beat and 500,000 usec/tick imply +960 ticks/second, for a song length of 51 days. Even if the song plays much faster, it's +still plenty long. +*/ + +#define QUEUE_SIZE 100 // maximum number of note play/stop commands we queue + +struct queue_entry { // the format of each queue entry + byte cmd; // CMD_PLAY or CMD_STOP + struct noteinfo note; // info about the note, including the action time +} queue[QUEUE_SIZE]; + +int queue_numitems = 0; +int queue_oldest_ndx = 0, queue_newest_ndx = 0; +int debugcount = 0; + +void show_queue(void) { // for debugging: dump the whole event queue + FILE *fid = logfile; + if (!logfile) fid = stdout; + fprintf(fid, "***at output time %lu.%03lu queue has %d items; oldest at %d, newest at %d\n", + output_usec / 1000, output_usec % 1000, queue_numitems, queue_oldest_ndx, queue_newest_ndx); + int ndx = queue_oldest_ndx; + if (queue_numitems > 0) while (1) { + struct queue_entry *q = &queue[ndx]; + fprintf(fid, "%2d: %s %s\n", ndx, q->cmd == CMD_PLAYNOTE ? "PLAY" : "STOP", describe(&q->note)); + if (ndx == queue_newest_ndx) break; + if (++ndx >= QUEUE_SIZE) ndx = 0; } } + +void show_tonegens(void) { // for debugging: dump tone generator status + FILE *fid = logfile; + if (!logfile) fid = stdout; + fprintf(fid, "*** tone generator status at output time %lu.%03lu\n", output_usec / 1000, output_usec % 1000); + for (int tgnum = 0; tgnum < num_tonegens; ++tgnum) { + struct tonegen_status *tg = &tonegen[tgnum]; + if (tg->playing) + fprintf(fid, "#%d: playing note %d (%02X), instrument %d, track %d channel %d%s\n", + tgnum, tg->note.note, tg->note.note, tg->note.instrument, tg->note.track, tg->note.channel, + tg->stopnote_pending ? ", stopnote pending\n" : ""); + else fprintf(fid, "#%d: idle\n", tgnum); } } + +// find an idle tone generator we can use +int find_idle_tgen(struct noteinfo *np) { // returns -1 if there isn't one + struct tonegen_status *tg; + int tgnum; + bool foundgen = false; + for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { // first, is this note already playing on this channel? + tg = &tonegen[tgnum]; + if (tg->playing + && tg->note.note == np->note && tg->note.channel == np->channel) { + // this must be the start of the sustain phase of a playing note + ++playnotes_without_stopnotes; + if (loggen) fprintf(logfile, " *** playnote without stopnote, tgen %d, %s\n", + tgnum, describe(np)); + foundgen = true; + break; } } + if (!foundgen && strategy2) { // try to use the same tone generator that this track used last time + struct track_status *trk = &track[np->track]; + tg = &tonegen[trk->preferred_tonegen]; + if (!tg->playing) { + tgnum = trk->preferred_tonegen; + foundgen = true; } } + if (!foundgen) // if not, then try for a free tone generator that had been playing the same instrument we need + for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { + tg = &tonegen[tgnum]; + if (!tg->playing && tg->note.instrument == np->instrument) { + foundgen = true; + break; } } + if (!foundgen) // if not, then try for any free tone generator + for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { + tg = &tonegen[tgnum]; + if (!tg->playing) { + foundgen = true; + break; } } + if (foundgen) return tgnum; + return -1; } + +void remove_queue_entry(int ndx) { // remove the oldest queue entry + struct queue_entry *q = &queue[ndx]; + + if (q->cmd == CMD_STOPNOTE) { + // find the tone generator playing this note, and record a pending stop + int tgnum; + for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { + struct tonegen_status *tg = &tonegen[tgnum]; + if (tg->playing + && tg->note.note == q->note.note + && tg->note.channel == q->note.channel) { // found the note + tg->stopnote_pending = true; // "stop note needed unless another start note follows" + tg->playing = false; // free the tg to be reallocated, but note the stop time in case + tg->note.time_usec = q->note.time_usec; // the tg doesn't get used and we generate it + if (loggen) fprintf(logfile, " pending stop tgen %d %s\n", tgnum, describe(&q->note)); + break; } } + if (tgnum >= num_tonegens) { + // If we exited the loop without finding the generator playing this note, presumably it never started + // because there weren't any free tone generators. Is there some assertion we can use to verify that? + ++stopnotes_without_playnotes; + if (loggen) fprintf(logfile, " *** stopnote without playnote, %s\n", describe(&q->note)); } } + + else { // CMD_PLAYNOTE + assert(q->cmd == CMD_PLAYNOTE, "bad cmd in remove_queue_entry"); + int tgnum = find_idle_tgen(&q->note); + struct tonegen_status *tg = &tonegen[tgnum]; + if (tgnum >= 0) { // we found a tone generator we can use + if (tgnum + 1 > num_tonegens_used) num_tonegens_used = tgnum + 1; + if (tg->note.instrument != q->note.instrument) { // it's a new instrument for this generator + tg->note.instrument = q->note.instrument; + ++instrument_changes; + if (loggen) fprintf(logfile, " tgen %d changed to instrument %d\n", tgnum, tg->note.instrument); + if (instrumentoutput) { // output a "change instrument" command + if (binaryoutput) { + putc(CMD_INSTRUMENT | tgnum, outfile); + putc(tg->note.instrument, outfile); + outfile_bytecount += 2; } + else { + fprintf(outfile, "0x%02X,%d, ", CMD_INSTRUMENT | tgnum, tg->note.instrument); + outfile_items(2); } } } + if (loggen) fprintf(logfile, " play tgen %d %s\n", tgnum, describe(&q->note)); + tg->playing = true; + tg->stopnote_pending = false; // don't bother to issue "stop note" + tg->note = q->note; // structure copy of note info + track[tg->note.track].preferred_tonegen = tgnum; + ++note_on_commands; + last_output_was_delay = false; + if (binaryoutput) { + putc(CMD_PLAYNOTE | tgnum, outfile); + putc(tg->note.note, outfile); + outfile_bytecount += 2; + if (volume_output) { + putc(tg->note.volume, outfile); + outfile_bytecount +=1; } } + else { + if (volume_output == 0) { + fprintf(outfile, "0x%02X,%d, ", CMD_PLAYNOTE | tgnum, tg->note.note); + outfile_items(2); } + else { + fprintf(outfile, "0x%02X,%d,%d, ", CMD_PLAYNOTE | tgnum, tg->note.note, tg->note.volume); + outfile_items(3); } } } + else { + if (loggen) fprintf(logfile, " *** at %lu.%03lu msec no free generator; skipping %s\n", + output_usec / 1000, output_usec % 1000, describe(&q->note)); + ++notes_skipped; } } } + +void generate_delay(unsigned long delta_msec) { // output a delay command + if (delta_msec > 0) { + assert(delta_msec <= 0x7fff, "time delta too big"); + if (last_output_was_delay) { + ++consecutive_delays; + if (loggen) fprintf(logfile, " *** this is a consecutive delay, of %d msec\n", delta_msec); } + last_output_was_delay = true; + if (binaryoutput) { // output a 15-bit delay in big-endian format + putc((byte)(delta_msec >> 8), outfile); + putc((byte)(delta_msec & 0xff), outfile); + outfile_bytecount += 2; } + else { + fprintf(outfile, "%ld,%ld, ", delta_msec >> 8, delta_msec & 0xff); + outfile_items(2); } } } + +// output all queue elements which are at the oldest time or at most "delaymin" later +void pull_queue(void) { + if (loggen) fprintf(logfile, " <-pull from queue at %lu.%03lu msec\n", output_usec / 1000, output_usec % 1000); + timestamp oldtime = queue[queue_oldest_ndx].note.time_usec; // the oldest time + assert(oldtime >= output_usec, "oldest queue entry goes backward in pull_queue"); + unsigned long delta_usec = (oldtime - output_usec) + output_deficit_usec; + unsigned long delta_msec = delta_usec / 1000; + output_deficit_usec = delta_usec % 1000; + if (delta_usec > (unsigned long)delaymin_usec) { // if time has advanced beyond the merge threshold, output a delay + if (delta_msec > 0) { + generate_delay(delta_msec); + if (loggen) fprintf(logfile, " at %lu.%03lu msec, delay for %ld msec to %lu.%03lu msec; deficit is %lu usec\n", + output_usec / 1000, output_usec % 1000, delta_msec, + oldtime / 1000, oldtime % 1000, output_deficit_usec); } + else if (loggen) fprintf(logfile, " at %lu.%03lu msec, a delay of only %lu usec was skipped, and the deficit is now %lu usec\n", + output_usec / 1000, output_usec % 1000, oldtime-output_usec, output_deficit_usec); + output_usec = oldtime; } + else if (delta_msec > 0) ++delays_saved; + + do { // output and remove all entries at the same (oldest) time in the queue + // or which are only delaymin newer + remove_queue_entry(queue_oldest_ndx); + if (++queue_oldest_ndx >= QUEUE_SIZE) queue_oldest_ndx = 0; + --queue_numitems; } + while (queue_numitems > 0 && queue[queue_oldest_ndx].note.time_usec <= oldtime + (timestamp)delaymin_usec); + + // do any "stop notes" still needed to be generated? + for (int tgnum = 0; tgnum < num_tonegens; ++tgnum) { + struct tonegen_status *tg = &tonegen[tgnum]; + if (tg->stopnote_pending) { // got one + last_output_was_delay = false; + if (binaryoutput) { + putc(CMD_STOPNOTE | tgnum, outfile); + outfile_bytecount += 1; } + else { + fprintf(outfile, "0x%02X, ", CMD_STOPNOTE | tgnum); + outfile_items(1); } + if (loggen) fprintf(logfile, " stop tgen %d %s\n", tgnum, describe(&tg->note)); + tg->stopnote_pending = false; + tg->playing = false; } } } + +void flush_queue(void) { // empty the queue + while (queue_numitems > 0) pull_queue(); } + +// queue a "note on" or "note off" command +void queue_cmd(byte cmd, struct noteinfo *np) { + if (loggen) fprintf(logfile, " queue %s %s\n", + cmd == CMD_PLAYNOTE ? "PLAY" : cmd == CMD_STOPNOTE ? "STOP" : "????", + describe(np)); + if (queue_numitems == QUEUE_SIZE) pull_queue(); + assert(queue_numitems < QUEUE_SIZE, "no room in queue"); + timestamp horizon = output_usec + output_deficit_usec; + if (np->time_usec < horizon) { // don't allow revisionist history + if (loggen) fprintf(logfile, " event delayed by %lu usec because queue is too small\n", + horizon - np->time_usec); + np->time_usec = horizon; + ++events_delayed; } + int ndx; + if (queue_numitems == 0) { // queue is empty; restart it + ndx = queue_oldest_ndx = queue_newest_ndx = queue_numitems = 0; } + else { // find a place to insert the new entry in time order + // this is a stable incremental insertion sort + ndx = queue_newest_ndx; // start with newest, since we are most often newer + while (queue[ndx].note.time_usec > np->time_usec) { // search backwards for something as new or older + if (ndx == queue_oldest_ndx) { // none: we are oldest; add to the start + if (--queue_oldest_ndx < 0) queue_oldest_ndx = QUEUE_SIZE - 1; + ndx = queue_oldest_ndx; + goto insert; } + if (--ndx < 0) ndx = QUEUE_SIZE - 1; } + // we are to insert the new item after "ndx", so shift all later entries down, if any + int from_ndx, to_ndx; + if (++queue_newest_ndx >= QUEUE_SIZE) queue_newest_ndx = 0; + to_ndx = queue_newest_ndx; + while (1) { + if ((from_ndx = to_ndx - 1) < 0) from_ndx = QUEUE_SIZE - 1; + if (from_ndx == ndx) break; + queue[to_ndx] = queue[from_ndx]; // structure copy + to_ndx = from_ndx; } + if (++ndx >= QUEUE_SIZE) ndx = 0; } +insert: // store the item at ndx + ++queue_numitems; + queue[ndx].cmd = cmd; // fille in the queue entry + queue[ndx].note = *np; // structure copy of the note +} + +void show_queue_cmd(timestamp time_usec, byte cmd, int note) { + printf("debug queue %s note %02X at %6ld\n", cmd == CMD_PLAYNOTE ? "PLAY" : "STOP", note, time_usec); + struct noteinfo notedata; + notedata.time_usec = time_usec; + notedata.track = 0; + notedata.channel = 0; + notedata.note = note; + notedata.instrument = 1; + notedata.volume = 100; + queue_cmd(cmd, ¬edata); + show_queue(); } + /************** process the MIDI file header *****************/ -void process_header (void) { +void process_file_header (void) { struct midi_header *hdr; unsigned int time_division; @@ -740,10 +1187,7 @@ void process_header (void) { hdrptr += rev_long (hdr->header_size) + 8; /* point past header to track header, presumably. */ return; } - -/**************** Process a MIDI track header *******************/ - -void start_track (int tracknum) { +void process_track_header (int tracknum) { struct track_header *hdr; unsigned long tracklen; @@ -752,8 +1196,7 @@ void start_track (int tracknum) { if (!charcmp ((char *) (hdr->MTrk), "MTrk")) midi_error ("Missing 'MTrk'", hdrptr); tracklen = rev_long (hdr->track_size); - if (logparse) - fprintf (logfile, "\nTrack %d length %ld\n", tracknum, tracklen); + if (logparse) fprintf (logfile, "\nTrack %d length %ld\n", tracknum, tracklen); hdrptr += sizeof (struct track_header); /* point past header */ chk_bufdata (hdrptr, tracklen); track[tracknum].trkptr = hdrptr; @@ -761,233 +1204,326 @@ void start_track (int tracknum) { track[tracknum].trkend = hdrptr; /* the point past the end of the track */ } - -/* Get a MIDI-style variable-length integer */ - -unsigned long get_varlen (uint8_t ** ptr) { +unsigned long get_varlen (uint8_t ** ptr) { // get a MIDI-style integer /* Get a 1-4 byte variable-length value and adjust the pointer past it. These are a succession of 7-bit values with a MSB bit of zero marking the end */ - - unsigned long val; - int i, byte; - - val = 0; - for (i = 0; i < 4; ++i) { - byte = *(*ptr)++; - val = (val << 7) | (byte & 0x7f); - if (!(byte & 0x80)) + unsigned long val = 0; + for (int i = 0; i < 4; ++i) { + byte b = *(*ptr)++; + val = (val << 7) | (b & 0x7f); + if (!(b & 0x80)) return val; } return val; } - /*************** Process the MIDI track data ***************************/ -/* Skip in the track for the next "note on", "note off" or "set tempo" command, -then record that information in the track status block and return. */ +// Skip in the track for the next "note on", "note off" or "set tempo" command and return. -void find_note (int tracknum) { - unsigned long int delta_time; +void find_next_note (int tracknum) { + unsigned long int delta_ticks; int event, chan; - int i; int note, velocity, controller, pressure, pitchbend, instrument; int meta_cmd, meta_length; unsigned long int sysex_length; - struct track_status *t; char *tag; - /* process events */ - - t = &track[tracknum]; /* our track status structure */ + struct track_status *t = &track[tracknum]; // our track status structure while (t->trkptr < t->trkend) { - - delta_time = get_varlen (&t->trkptr); + delta_ticks = get_varlen (&t->trkptr); + t->time += delta_ticks; if (logparse) { - fprintf (logfile, "trk %d ", tracknum); - if (delta_time) { - fprintf (logfile, "delta time %4ld, ", delta_time); } + fprintf(logfile, "# trk %d ", tracknum); + if (loggen) fprintf(logfile, "at ticks+%lu=%lu: ", delta_ticks, t->time); else { - fprintf (logfile, " "); } } - t->time += delta_time; - if (*t->trkptr < 0x80) - event = t->last_event; /* using "running status": same event as before */ - else { /* otherwise get new "status" (event type) */ - event = *t->trkptr++; } - if (event == 0xff) { /* meta-event */ + if (delta_ticks > 0) fprintf(logfile, "ticks+%-5lu%7lu ", delta_ticks, t->time); + else fprintf(logfile, " "); } } + + if (*t->trkptr < 0x80) event = t->last_event; // using "running status": same event as before + else event = *t->trkptr++; // otherwise get new "status" (event type) */ + + if (event == 0xff) { // meta-event meta_cmd = *t->trkptr++; meta_length = get_varlen (&t->trkptr); switch (meta_cmd) { case 0x00: - if (logparse) - fprintf (logfile, "sequence number %d\n", rev_short (*(unsigned short *) t->trkptr)); + if (logparse) fprintf (logfile, "sequence number %d\n", rev_short (*(unsigned short *) t->trkptr)); break; case 0x01: - tag = "description"; - goto show_text; + tag = "description"; goto show_text; case 0x02: - tag = "copyright"; - goto show_text; + tag = "copyright"; goto show_text; case 0x03: tag = "track name"; if (tracknum == 0 && !parseonly && !binaryoutput) { /* Incredibly, MIDI has no standard for recording the name of the piece! Track 0's "trackname" is often used for that so we output it to the C file as documentation. */ fprintf (outfile, "// "); - for (i = 0; i < meta_length; ++i) { + for (int i = 0; i < meta_length; ++i) { int ch = t->trkptr[i]; fprintf (outfile, "%c", isprint (ch) ? ch : '?'); } fprintf (outfile, "\n"); } goto show_text; case 0x04: - tag = "instrument name"; - goto show_text; + tag = "instrument name"; goto show_text; case 0x05: - tag = "lyric"; - goto show_text; + tag = "lyric"; goto show_text; case 0x06: - tag = "marked point"; - goto show_text; + tag = "marked point"; goto show_text; case 0x07: - tag = "cue point"; + tag = "cue point"; goto show_text; + case 0x08: + tag = "program name"; goto show_text; + case 0x09: + tag = "device (port) name"; show_text: if (logparse) { fprintf (logfile, "meta cmd %02X, length %d, %s: \"", meta_cmd, meta_length, tag); - for (i = 0; i < meta_length; ++i) { + for (int i = 0; i < meta_length; ++i) { int ch = t->trkptr[i]; fprintf (logfile, "%c", isprint (ch) ? ch : '?'); } fprintf (logfile, "\"\n"); } break; case 0x20: - if (logparse) - fprintf (logfile, "channel prefix %d\n", *t->trkptr); + if (logparse) fprintf (logfile, "channel prefix %d\n", *t->trkptr); + break; + case 0x21: + if (logparse) fprintf(logfile, "MIDI port %d\n", *t->trkptr); break; case 0x2f: - if (logparse) - fprintf (logfile, "end of track\n"); + if (logparse) fprintf (logfile, "end of track\n"); break; - case 0x51: /* tempo: 3 byte big-endian integer! */ + case 0x51: // tempo: 3 byte big-endian integer, not a varlen integer! t->cmd = CMD_TEMPO; - t->tempo = rev_long (*(unsigned long *) (t->trkptr - 1)) & 0xffffffL; - if (logparse) - fprintf (logfile, "set tempo %ld usec/qnote\n", t->tempo); + t->tempo = rev_long (*(uint32_t *) (t->trkptr - 1)) & 0xffffffL; + if (logparse) fprintf (logfile, "set tempo %ld usec/qnote\n", t->tempo); t->trkptr += meta_length; return; case 0x54: - if (logparse) - fprintf (logfile, "SMPTE offset %08" PRIx32 "\n", - rev_long (*(unsigned long *) t->trkptr)); + if (logparse) fprintf (logfile, "SMPTE offset %08" PRIx32 "\n", + rev_long (*(uint32_t *) t->trkptr)); break; case 0x58: - if (logparse) - fprintf (logfile, "time signature %08" PRIx32 "\n", - rev_long (*(unsigned long *) t->trkptr)); + if (logparse) fprintf (logfile, "time signature %08" PRIx32 "\n", + rev_long (*(uint32_t *) t->trkptr)); break; case 0x59: - if (logparse) - fprintf (logfile, "key signature %04X\n", rev_short (*(unsigned short *) t->trkptr)); + if (logparse) fprintf (logfile, "key signature %04X\n", rev_short (*(unsigned short *) t->trkptr)); break; case 0x7f: - tag = "sequencer data"; - goto show_hex; + tag = "sequencer data"; goto show_hex; default: /* unknown meta command */ tag = "???"; show_hex: if (logparse) { fprintf (logfile, "meta cmd %02X, length %d, %s: ", meta_cmd, meta_length, tag); - for (i = 0; i < meta_length; ++i) + for (int i = 0; i < meta_length; ++i) fprintf (logfile, "%02X ", t->trkptr[i]); fprintf (logfile, "\n"); } - break; } t->trkptr += meta_length; } - else if (event < 0x80) - midi_error ("Unknown MIDI event type", t->trkptr); + else if (event < 0x80) midi_error ("Unknown MIDI event type", t->trkptr); else { if (event < 0xf0) t->last_event = event; // remember "running status" if not meta or sysex event - chan = event & 0xf; - t->chan = chan; + t->chan = chan = event & 0xf; switch (event >> 4) { - case 0x8: + case 0x8: // note off t->note = *t->trkptr++; - velocity = *t->trkptr++; -note_off: - if (logparse) - fprintf (logfile, "note %d off, chan %d, velocity %d\n", t->note, chan, velocity); - if ((1 << chan) & channel_mask) { /* if we're processing this channel */ - t->cmd = CMD_STOPNOTE; - return; /* stop processing and return */ - } - break; // else keep looking - case 0x9: + t->volume = *t->trkptr++; +note_off: if (logparse) fprintf(logfile, "note %d (0x%02X) off, channel %d, volume %d\n", t->note, t->note, chan, t->volume); + if ((1 << chan) & channel_mask // we're processing this channel + && (!percussion_ignore || chan != PERCUSSION_TRACK)) { // and not ignoring percussion + if (!instrumentoutput) t->chan = 0; // if no insruments, force all notes to channel 0 + t->cmd = CMD_STOPNOTE; /* stop processing and return */ + return; } + break; + case 0x9: // note on t->note = *t->trkptr++; - velocity = *t->trkptr++; - if (velocity == 0) /* some scores use note-on with zero velocity for off! */ + t->volume = *t->trkptr++; + if (t->volume == 0) // some scores use note-on with zero velocity for off! goto note_off; - t->velocity = velocity; - if (logparse) - fprintf (logfile, "note %d on, chan %d, velocity %d\n", t->note, chan, velocity); - if ((1 << chan) & channel_mask) { /* if we're processing this channel */ - t->cmd = CMD_PLAYNOTE; - return; /* stop processing and return */ - } - break; // else keep looking - case 0xa: + if (logparse) fprintf(logfile, "note %d (0x%02X) on, channel %d, volume %d\n", t->note, t->note, chan, t->volume); + if ((1 << chan) & channel_mask // we're processing this channel + && (!percussion_ignore || chan != PERCUSSION_TRACK)) { // and not ignoring percussion + if (!instrumentoutput) t->chan = 0; // if no insruments, force all notes to channel 0 + t->cmd = CMD_PLAYNOTE; /* stop processing and return */ + return; } + break; + case 0xa: // key pressure note = *t->trkptr++; velocity = *t->trkptr++; - if (logparse) - fprintf (logfile, "after-touch %d, %d\n", note, velocity); + if (logparse) fprintf (logfile, "channel %d: note %d (0x%02X) has key pressure %d\n", chan, note, note, velocity); break; - case 0xb: + case 0xb: // control value change controller = *t->trkptr++; velocity = *t->trkptr++; - if (logparse) - fprintf (logfile, "control change %d, %d\n", controller, velocity); + if (logparse) fprintf (logfile, "channel %d: change control value of controller %d to %d\n", chan, controller, velocity); break; - case 0xc: + case 0xc: // program patch, ie which instrument instrument = *t->trkptr++; - midi_chan_instrument[chan] = instrument; // record new instrument for this channel - if (logparse) - fprintf (logfile, "program patch %d\n", instrument); + channel[chan].instrument = instrument; // record new instrument for this channel + if (logparse) fprintf (logfile, "channel %d: program patch to instrument %d\n", chan, instrument); break; - case 0xd: + case 0xd: // channel pressure pressure = *t->trkptr++; - if (logparse) - fprintf (logfile, "channel after-touch %d\n", pressure); + if (logparse) fprintf (logfile, "channel %d: after-touch pressure is %d\n", chan, pressure); break; - case 0xe: + case 0xe: // pitch wheel change pitchbend = *t->trkptr++ | (*t->trkptr++ << 7); - if (logparse) - fprintf (logfile, "pitch wheel change %d\n", pitchbend); + if (logparse) fprintf (logfile, "pitch wheel change to %d\n", pitchbend); break; - case 0xf: + case 0xf: // sysex event sysex_length = get_varlen (&t->trkptr); - if (logparse) - fprintf (logfile, "SysEx event %d, %ld bytes\n", event, sysex_length); + if (logparse) fprintf (logfile, "SysEx event %d with %ld bytes\n", event, sysex_length); t->trkptr += sysex_length; break; default: midi_error ("Unknown MIDI command", t->trkptr); } } } - t->cmd = CMD_TRACKDONE; /* no more notes to process */ + t->cmd = CMD_TRACKDONE; //no more events to process on this track ++tracks_done; } +void show_noteinfo_slots(int channum) { + struct channel_status *cp = &channel[channum]; + if (loggen) { + fprintf(logfile, "notes playing for channel %d:\n", channum); + for (int ndx = 0; ndx < MAX_CHANNELNOTES; ++ndx) + if (cp->note_playing[ndx]) { + struct noteinfo *np = &cp->notes_playing[ndx]; + fprintf(logfile, " %2d: %s\n", ndx, describe(np)); } } } + +void process_track_data(void) { + unsigned long last_earliest_time = 0; + + do { // while there are still track notes to process + + /* Find the track with the earliest event time, and process it's event. + + A potential improvement: If there are multiple tracks with the same time, + first do the ones with STOPNOTE as the next command, if any. That would + help avoid running out of tone generators. In practice, though, most MIDI + files do all the STOPNOTEs first anyway, so it won't have much effect. + + Usually we start with the track after the one we did last time (tracknum), + so that if we run out of tone generators, we have been fair to all the tracks. + The alternate "strategy1" says we always start with track 0, which means + that we favor early tracks over later ones when there aren't enough tone generators. */ + + struct track_status *trk; + int count_tracks = num_tracks; + unsigned long earliest_time = 0x7fffffff; // in ticks, of course + int tracknum = 0; + int earliest_tracknum; + if (strategy1) + tracknum = num_tracks; /* beyond the end, so we start with track 0 */ + do { + if (++tracknum >= num_tracks) tracknum = 0; + trk = &track[tracknum]; + if (trk->cmd != CMD_TRACKDONE && trk->time < earliest_time) { + earliest_time = trk->time; + earliest_tracknum = tracknum; } } + while (--count_tracks); + tracknum = earliest_tracknum; /* the track we picked */ + trk = &track[tracknum]; + assert(earliest_time >= timenow_ticks, "time went backwards in process_track_data"); + timenow_ticks = earliest_time; // we make it the global time + timenow_usec += (uint64_t)(timenow_ticks - timenow_usec_updated) * tempo / ticks_per_beat; + timenow_usec_updated = timenow_ticks; // usec version is updated based on the current tempo + if (loggen) { + if (earliest_time != last_earliest_time) { + fprintf(logfile, "->process trk %d at time %lu.%03lu msec (%lu ticks)\n", + tracknum, timenow_usec / 1000, timenow_usec % 1000, timenow_ticks); + last_earliest_time = earliest_time; } } + struct channel_status *cp = &channel[trk->chan]; // the channel info, if play or stop + + if (trk->cmd == CMD_TEMPO) { // change the global tempo, which affects future usec computations + if (tempo != trk->tempo) { + ++tempo_changes; + tempo = trk->tempo; } + if (loggen) fprintf(logfile, " tempo set to %ld usec/qnote\n", tempo); + find_next_note(tracknum); } + + else { // should be PLAYNOTE or STOPNOTE + if (percussion_translate && trk->chan == PERCUSSION_TRACK) + trk->note += 128; // maybe move percussion notes up to 128..255 + else { // shift notes as requested + trk->note += keyshift; + if (trk->note < 0) trk->note = 0; + if (trk->note > 127) trk->note = 127; } + + if (trk->cmd == CMD_STOPNOTE) { + int ndx; // find the noteinfo for this note -- which better be playing -- in the channel status + for (ndx = 0; ndx < MAX_CHANNELNOTES; ++ndx) { + if (cp->note_playing[ndx] + && cp->notes_playing[ndx].note == trk->note + && cp->notes_playing[ndx].track == tracknum) + break; } + if (ndx >= MAX_CHANNELNOTES) { + ++noteinfo_notfound; // presumably the array overflowed on input + if (loggen) fprintf(logfile, " *** noteinfo slot not found to stop track %d note %d (%02X) channel %d\n", + tracknum, trk->note, trk->note, trk->chan); } + else { + // Analyze the sustain and release parameters. We might generate another "note on" + // command with reduced volume, and/or move the stopnote command earlier than now. + struct noteinfo *np = &cp->notes_playing[ndx]; + unsigned long duration_usec = timenow_usec - np->time_usec; // it has the start time in it + unsigned long truncation; + if (duration_usec <= notemin_usec) truncation = 0; + else if (duration_usec < releasetime_usec + notemin_usec) truncation = duration_usec - notemin_usec; + else truncation = releasetime_usec; + if (attacktime_usec > 0 && duration_usec < attacknotemax_usec) { + if (duration_usec - truncation > attacktime_usec) { // do a sustain phase + if ((np->volume = np->volume * sustainlevel_pct / 100) <= 0) np->volume = 1; + np->time_usec += attacktime_usec; // adjust time to be when sustain phase starts + queue_cmd(CMD_PLAYNOTE, np); + ++sustainphases_done; } + else ++sustainphases_skipped; } + np->time_usec = timenow_usec - truncation; // adjust time to be when the note stops + queue_cmd(CMD_STOPNOTE, np); + cp->note_playing[ndx] = false; } + find_next_note(tracknum); } + + else if (trk->cmd == CMD_PLAYNOTE) { // Process only one "start note", so other tracks get a chance at tone generators + int ndx; // find an unused noteinfo slot to use + for (ndx = 0; ndx < MAX_CHANNELNOTES; ++ndx) { + if (!cp->note_playing[ndx]) break; } + if (ndx >= MAX_CHANNELNOTES) { + ++noteinfo_overflow; // too many simultaneous notes + if (loggen) fprintf(logfile, " *** no noteinfo slot to queue track %d note %d (%02X) channel %d\n", + tracknum, trk->note, trk->note, trk->chan); + show_noteinfo_slots(tracknum); } + else { + cp->note_playing[ndx] = true; // assign it to us + struct noteinfo *pn = &cp->notes_playing[ndx]; + pn->time_usec = timenow_usec; // fill it in + pn->track = tracknum; + pn->channel = trk->chan; + pn->note = trk->note; + pn->instrument = cp->instrument; + pn->volume = trk->volume; + queue_cmd(CMD_PLAYNOTE, pn); } + find_next_note(tracknum); } // use up the note + + else assert(false, "bad cmd in process_track_data"); } } + + while (tracks_done < num_tracks); + + // empty the output queue and generate the end-of-score command + flush_queue(); + if (loggen) { + fprintf(logfile, "ending timenow_usec: %lu.%03lu\n", timenow_usec / 1000, timenow_usec % 1000); + fprintf(logfile, "ending output_usec: %lu.%03lu\n", output_usec / 1000, output_usec % 1000); } + assert(timenow_usec >= output_usec, "time deficit at end of song"); + generate_delay((timenow_usec - output_usec) / 1000); + if (binaryoutput) { + putc(gen_restart ? CMD_RESTART : CMD_STOP, outfile); + outfile_bytecount +=1; } + else { + fprintf(outfile, "0x%02X};", gen_restart ? CMD_RESTART : CMD_STOP); + outfile_items(1); + fprintf(outfile, "\n"); } } -/* generate "stop note" commands for any channels that have them pending */ - -void gen_stopnotes(void) { - struct tonegen_status *tg; - int tgnum; - for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { - tg = &tonegen[tgnum]; - if (tg->stopnote_pending) { - if (binaryoutput) { - putc (CMD_STOPNOTE | tgnum, outfile); - outfile_bytecount += 1; } - else { - fprintf (outfile, "0x%02X, ", CMD_STOPNOTE | tgnum); - outfile_items (1); } - tg->stopnote_pending = false; } } } /********************* main ****************************/ @@ -996,38 +1532,35 @@ int main (int argc, char *argv[]) { char *filebasename; #define MAXPATH 120 char filename[MAXPATH]; - int tracknum; - int earliest_tracknum; - unsigned long earliest_time; - int notes_skipped = 0; - printf ("MIDITONES V%s, (C) 2011-2016 Len Shustek\n", VERSION); - if (argc == 1) { /* no arguments */ + printf ("MIDITONES V%s, (C) 2011-2019 Len Shustek\n", VERSION); + if (argc == 1) { // no arguments SayUsage (argv[0]); return 1; } - /* process options */ - - argno = HandleOptions (argc, argv); + argno = HandleOptions (argc, argv); // process options if (argno == 0) { fprintf (stderr, "\n*** No basefilename given\n\n"); SayUsage (argv[0]); exit (4); } filebasename = argv[argno]; - /* Open the log file */ - - if (logparse || loggen) { + if (logparse || loggen) { // open the log file miditones_strlcpy (filename, filebasename, MAXPATH); miditones_strlcat (filename, ".log", MAXPATH); logfile = fopen (filename, "w"); if (!logfile) { fprintf (stderr, "Unable to open log file %s\n", filename); return 1; } - fprintf (logfile, "MIDITONES V%s log file\n", VERSION); } - - /* Open the input file */ - + fprintf (logfile, "MIDITONES V%s log file\n", VERSION); + print_command_line(logfile, argc, argv); } + if (loggen) { + fprintf(logfile, "\nThere are %d independent time-ordered streams in this log file:\n", logparse ? 3 : 2); + if (logparse) fprintf(logfile, " - the parsed MIDI events, marked with #\n"); + fprintf(logfile, " - the MIDI play/stop events being queued, announced with ->\n" + " - the generated bytestream commands pulled from the queue, announced with <-\n\n"); } + + // open the input file miditones_strlcpy (filename, filebasename, MAXPATH); miditones_strlcat (filename, ".mid", MAXPATH); infile = fopen (filename, "rb"); @@ -1035,34 +1568,30 @@ int main (int argc, char *argv[]) { fprintf (stderr, "Unable to open input file %s\n", filename); return 1; } - /* Read the whole input file into memory */ - - fseek (infile, 0, SEEK_END); /* find file size */ + // Read the whole input file into memory + fseek (infile, 0, SEEK_END); // find its size buflen = ftell (infile); fseek (infile, 0, SEEK_SET); - buffer = (unsigned char *) malloc (buflen + 1); + buffer = (byte *) malloc (buflen + 1); if (!buffer) { fprintf (stderr, "Unable to allocate %ld bytes for the file\n", buflen); return 1; } fread (buffer, buflen, 1, infile); fclose (infile); - if (logparse) - fprintf (logfile, "Processing %s, %ld bytes\n", filename, buflen); - - /* Create the output file */ + if (logparse) fprintf (logfile, "Processing %s, %ld bytes\n", filename, buflen); - if (!parseonly) { + if (!parseonly) { // create the output file miditones_strlcpy (filename, filebasename, MAXPATH); if (binaryoutput) { miditones_strlcat (filename, ".bin", MAXPATH); outfile = fopen (filename, "wb"); } else { - miditones_strlcat (filename, ".c", MAXPATH); + miditones_strlcat (filename, scorename ? ".h" : ".c", MAXPATH); outfile = fopen (filename, "w"); } if (!outfile) { fprintf (stderr, "Unable to open output file %s\n", filename); return 1; } - file_header.f1 = (velocityoutput ? HDR_F1_VOLUME_PRESENT : 0) + file_header.f1 = (volume_output ? HDR_F1_VOLUME_PRESENT : 0) | (instrumentoutput ? HDR_F1_INSTRUMENTS_PRESENT : 0) | (percussion_translate ? HDR_F1_PERCUSSION_PRESENT : 0); file_header.num_tgens = num_tonegens; @@ -1072,7 +1601,7 @@ int main (int argc, char *argv[]) { fprintf (outfile, "// Playtune bytestream for file \"%s.mid\" ", filebasename); fprintf (outfile, "created by MIDITONES V%s on %s", VERSION, asctime (localtime (&rawtime))); - print_command_line (argc, argv); + print_command_line (outfile, argc, argv); if (channel_mask != 0xffff) fprintf (outfile, "// Only the masked channels were processed: %04X\n", channel_mask); if (keyshift != 0) @@ -1083,7 +1612,8 @@ int main (int argc, char *argv[]) { fprintf (outfile, "#else\n"); fprintf (outfile, "#define PROGMEM\n"); fprintf (outfile, "#endif\n"); } - fprintf (outfile, "const unsigned char PROGMEM score [] = {\n"); + fprintf (outfile, "const unsigned char PROGMEM %s [] = {\n", + scorename ? filebasename : "score"); if (do_header) { // write the C initialization for the file header fprintf (outfile, "'P','t', 6, 0x%02X, 0x%02X, ", file_header.f1, file_header.f2); fflush (outfile); @@ -1093,252 +1623,87 @@ int main (int argc, char *argv[]) { else if (do_header) { // write the binary file header int i; for (i = 0; i < sizeof (file_header); ++i) - fputc (((unsigned char *) &file_header)[i], outfile); + fputc (((byte *) &file_header)[i], outfile); file_header_num_tgens_position = (char *) &file_header.num_tgens - (char *) &file_header; outfile_bytecount += sizeof (file_header); } } - /* process the MIDI file header */ - - hdrptr = buffer; /* pointer to file and track headers */ - process_header (); + // process the MIDI file header + hdrptr = buffer; // point to the file and track headers + process_file_header (); printf (" Processing %d tracks.\n", num_tracks); - if (num_tracks > MAX_TRACKS) - midi_error ("Too many tracks", buffer); - - /* initialize processing of all the tracks */ + if (num_tracks > MAX_TRACKS) midi_error ("Too many tracks", buffer); + // initialize for processing of all the tracks tempo = DEFAULT_TEMPO; - for (tracknum = 0; tracknum < num_tracks; ++tracknum) { + for (int tracknum = 0; tracknum < num_tracks; ++tracknum) { track[tracknum].tempo = DEFAULT_TEMPO; - start_track (tracknum); /* process the track header */ - find_note (tracknum); /* position to the first note on/off */ + process_track_header (tracknum); + find_next_note (tracknum); /* position to the first note on/off */ /* if we are in "parse only" mode, do the whole track, so we do them one at a time instead of time-synchronized. */ if (parseonly) while (track[tracknum].cmd != CMD_TRACKDONE) - find_note (tracknum); } + find_next_note (tracknum); } +#if 0 + // TEMP test queuing routines + show_queue_cmd(12, CMD_PLAYNOTE, 100); + show_queue_cmd(12, CMD_PLAYNOTE, 101); + show_queue_cmd(12, CMD_PLAYNOTE, 103); + show_queue_cmd(20, CMD_STOPNOTE, 101); + show_queue_cmd(15, CMD_STOPNOTE, 103); + show_queue_cmd(21, CMD_PLAYNOTE, 104); + show_queue_cmd(20, CMD_STOPNOTE, 100); + show_queue_cmd(20, CMD_STOPNOTE, 104); + show_queue_cmd(22, CMD_PLAYNOTE, 109); + flush_queue(); +#endif + if (!parseonly) { - /* Continue processing all tracks, in an order based on the simulated time. - This is not unlike multiway merging used for tape sorting algoritms in the 50's! */ + process_track_data(); // do all the tracks interleaved, like a 1950's multiway merge - tracknum = 0; - if (!parseonly) { - do { /* while there are still track notes to process */ - struct track_status *trk; - struct tonegen_status *tg; - int tgnum; - int count_tracks; - unsigned long delta_time, delta_msec; - - /* Find the track with the earliest event time, - and output a delay command if time has advanced. - - A potential improvement: If there are multiple tracks with the same time, - first do the ones with STOPNOTE as the next command, if any. That would - help avoid running out of tone generators. In practice, though, most MIDI - files do all the STOPNOTEs first anyway, so it won't have much effect. - */ - - earliest_time = 0x7fffffff; - - /* Usually we start with the track after the one we did last time (tracknum), - so that if we run out of tone generators, we have been fair to all the tracks. - The alternate "strategy1" says we always start with track 0, which means - that we favor early tracks over later ones when there aren't enough tone generators. - */ - - count_tracks = num_tracks; - if (strategy1) - tracknum = num_tracks; /* beyond the end, so we start with track 0 */ - do { - if (++tracknum >= num_tracks) - tracknum = 0; - trk = &track[tracknum]; - if (trk->cmd != CMD_TRACKDONE && trk->time < earliest_time) { - earliest_time = trk->time; - earliest_tracknum = tracknum; } } - while (--count_tracks); - - tracknum = earliest_tracknum; /* the track we picked */ - trk = &track[tracknum]; - if (loggen) - fprintf (logfile, "Earliest time is trk %d, time %ld\n", tracknum, earliest_time); - if (earliest_time < timenow) - midi_error ("INTERNAL: time went backwards", trk->trkptr); - - /* If time has advanced, output a "delay" command */ - - delta_time = earliest_time - timenow; - if (delta_time) { - /* Convert ticks to milliseconds based on the current tempo */ - delta_msec = ((unsigned long long) delta_time * tempo) / ticks_per_beat / 1000; - if (delta_msec) { // if time delay didn't round down to zero msec - gen_stopnotes(); /* first check if any tone generators have "stop note" commands pending */ - if (loggen) - fprintf (logfile, "->Delay %ld msec (%ld ticks)\n", delta_msec, delta_time); - if (delta_msec > 0x7fff) - midi_error ("INTERNAL: time delta too big", trk->trkptr); - /* output a 15-bit delay in big-endian format */ - if (binaryoutput) { - putc ((unsigned char) (delta_msec >> 8), outfile); - putc ((unsigned char) (delta_msec & 0xff), outfile); - outfile_bytecount += 2; } - else { - fprintf (outfile, "%ld,%ld, ", delta_msec >> 8, delta_msec & 0xff); - outfile_items (2); } } } - timenow = earliest_time; - - /* If this track event is "set tempo", just change the global tempo. - That affects how we generate "delay" commands. */ - - if (trk->cmd == CMD_TEMPO) { - tempo = trk->tempo; - if (loggen) - fprintf (logfile, "Tempo changed to %ld usec/qnote\n", tempo); - find_note (tracknum); } - - /* If this track event is "stop note", process it and all subsequent "stop notes" for this track - that are happening at the same time. Doing so frees up as many tone generators as possible. */ - - else if (trk->cmd == CMD_STOPNOTE) - do { - // stop a note - if (!percussion_ignore || trk->chan != PERCUSSION_TRACK) /* if we didn't ignore it as percussion */ - for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { /* find which generator is playing it */ - tg = &tonegen[tgnum]; - if (tg->playing && tg->track == tracknum && tg->note == trk->note) { - if (loggen) - fprintf (logfile, - "->Stop note %d, generator %d, track %d\n", - tg->note, tgnum, tracknum); - tg->stopnote_pending = true; /* must stop the current note if another doesn't start first */ - tg->playing = false; - trk->tonegens[tgnum] = false; } } - find_note (tracknum); // use up the note - } - while (trk->cmd == CMD_STOPNOTE && trk->time == timenow); - - /* If this track event is "start note", process only it. - Don't do more than one, so we allow other tracks their chance at grabbing tone generators. */ - - else if (trk->cmd == CMD_PLAYNOTE) { - if (!percussion_ignore || trk->chan != PERCUSSION_TRACK) { /* ignore percussion track notes if asked to */ - bool foundgen = false; - /* maybe try to use the same tone generator that this track used last time */ - if (strategy2) { - tg = &tonegen[trk->preferred_tonegen]; - if (!tg->playing) { - tgnum = trk->preferred_tonegen; - foundgen = true; } } - /* if not, then try for a free tone generator that had been playing the same instrument we need */ - if (!foundgen) - for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { - tg = &tonegen[tgnum]; - if (!tg->playing && tg->instrument == midi_chan_instrument[trk->chan]) { - foundgen = true; - break; } } - /* if not, then try for any free tone generator */ - if (!foundgen) - for (tgnum = 0; tgnum < num_tonegens; ++tgnum) { - tg = &tonegen[tgnum]; - if (!tg->playing) { - foundgen = true; - break; } } - if (foundgen) { - int shifted_note; - if (tgnum + 1 > num_tonegens_used) - num_tonegens_used = tgnum + 1; - tg->playing = true; - tg->track = tracknum; - tg->note = trk->note; - tg->stopnote_pending = false; - trk->tonegens[tgnum] = true; - trk->preferred_tonegen = tgnum; - ++note_on_commands; - if (tg->instrument != midi_chan_instrument[trk->chan]) { /* new instrument for this generator */ - tg->instrument = midi_chan_instrument[trk->chan]; - ++instrument_changes; - if (loggen) - fprintf (logfile, - "gen %d changed to instrument %d\n", tgnum, tg->instrument); - if (instrumentoutput) { /* output a "change instrument" command */ - if (binaryoutput) { - putc (CMD_INSTRUMENT | tgnum, outfile); - putc (tg->instrument, outfile); } - else { - fprintf (outfile, "0x%02X,%d, ", CMD_INSTRUMENT | tgnum, tg->instrument); - outfile_items (2); } } } - if (loggen) - fprintf (logfile, - "->Start note %d, generator %d, instrument %d, track %d\n", - trk->note, tgnum, tg->instrument, tracknum); - if (percussion_translate && trk->chan == PERCUSSION_TRACK) { /* if requested, */ - shifted_note = trk->note + 128; // shift percussion notes up to 128..255 - } - else { /* shift notes as requested */ - shifted_note = trk->note + keyshift; - if (shifted_note < 0) - shifted_note = 0; - if (shifted_note > 127) - shifted_note = 127; } - if (binaryoutput) { - putc (CMD_PLAYNOTE | tgnum, outfile); - putc (shifted_note, outfile); - outfile_bytecount += 2; - if (velocityoutput) { - putc (trk->velocity, outfile); - outfile_bytecount++; } } - else { - if (velocityoutput == 0) { - fprintf (outfile, "0x%02X,%d, ", CMD_PLAYNOTE | tgnum, shifted_note); - outfile_items (2); } - else { - fprintf (outfile, "0x%02X,%d,%d, ", - CMD_PLAYNOTE | tgnum, shifted_note, trk->velocity); - outfile_items (3); } } } - else { - if (loggen) - fprintf (logfile, - "----> No free generator, skipping note %d, track %d\n", - trk->note, tracknum); - ++notes_skipped; } } - find_note (tracknum); // use up the note - } - - } /* !parseonly do */ - while (tracks_done < num_tracks); - - // generate the end-of-score command and some commentary - gen_stopnotes(); /* flush out any pending "stop note" commands */ - outfile_bytecount++; - if (binaryoutput) - putc (gen_restart ? CMD_RESTART : CMD_STOP, outfile); - else { - fprintf (outfile, - "0x%02x};\n// This score contains %ld bytes, and %d tone generator%s used.\n", - gen_restart ? CMD_RESTART : CMD_STOP, outfile_bytecount, num_tonegens_used, - num_tonegens_used == 1 ? " is" : "s are"); + // generate the ending commentary + if (!binaryoutput) { + fprintf(outfile, "\n// This score contains %ld bytes, and %d tone generator%s used.\n", + outfile_bytecount, num_tonegens_used, + num_tonegens_used == 1 ? " is" : "s are"); if (notes_skipped) - fprintf (outfile, "// %d notes had to be skipped.\n", notes_skipped); } - printf (" %s %d tone generators were used.\n", - num_tonegens_used < num_tonegens ? "Only" : "All", num_tonegens_used); + fprintf(outfile, "// %d notes had to be skipped.\n", notes_skipped); } + printf(" %s %d tone generators were used.\n", + num_tonegens_used < num_tonegens ? "Only" : "All", num_tonegens_used); if (notes_skipped) - printf - (" %d notes were skipped because there weren't enough tone generators.\n", - notes_skipped); - printf (" %ld bytes of score data were generated.\n", outfile_bytecount); - if (loggen) - fprintf (logfile, "%d note-on commands, %d instrument changes.\n", - note_on_commands, instrument_changes); - if (do_header) { // rewrite the file header with the actual number of tone generators used - if (fseek (outfile, file_header_num_tgens_position, SEEK_SET) != 0) - fprintf (stderr, "Can't seek to number of tone generators in the header\n"); + printf(" %d notes were skipped because there weren't enough tone generators.\n", + notes_skipped); + if (consecutive_delays) + printf(" %d consecutive delays could be eliminated\n", consecutive_delays); + if (events_delayed) + printf(" %d \"stop note\" commands were delayed because the %d-element output queue is too small\n", + events_delayed, QUEUE_SIZE); + if (noteinfo_overflow + noteinfo_notfound > 0) + printf(" %d notes couldn't be recorded in the track status, so then %d notes couldn't be found\n" + " (Consider recompiling with MAX_TRACKNOTES bigger than %d, to allow more simultaneous notes.)\n", + noteinfo_overflow, noteinfo_notfound, MAX_CHANNELNOTES); + printf(" %ld bytes of score data were generated, ", outfile_bytecount); + printf("representing %u.%03u seconds of music with %d tempo changes\n", + (unsigned)(timenow_usec / 1000000), (unsigned)(timenow_usec / 1000 % 1000), tempo_changes); + if (delaymin_usec) + printf(" %ld delays were removed because the minimum delay of %u msec caused events to be merged\n", + delays_saved, (unsigned)(delaymin_usec / 1000)); + if (loggen) { + fprintf(logfile, "%d note-on commands, %d instrument changes.\n", + note_on_commands, instrument_changes); + fprintf(logfile, "%d stop-notes without start-notes, %d start-notes without stop-notes\n", + stopnotes_without_playnotes, playnotes_without_stopnotes); + if (attacktime_usec > 0) fprintf(logfile, "%d sustain phases done, and %d skipped because the notes were too short\n", + sustainphases_done, sustainphases_skipped); } + if (0 && do_header) { // rewrite the file header with the actual number of tone generators used + if (fseek(outfile, file_header_num_tgens_position, SEEK_SET) != 0) + fprintf(stderr, "Can't seek to number of tone generators in the header\n"); else { if (binaryoutput) - putc (num_tonegens_used, outfile); + putc(num_tonegens_used, outfile); else - fprintf (outfile, "%2d", num_tonegens_used); } } - fclose (outfile); } /* if (!parseonly) */ + fprintf(outfile, "%2d", num_tonegens_used); } } + fclose(outfile); } if (loggen || logparse) fclose (logfile); diff --git a/miditones.exe b/miditones.exe index 025533366f14bab624d1a9614d5c7ee6a290a8cd..6ae421a426098b7ef522fe752e5fbd9d09059bb1 100644 GIT binary patch literal 72192 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