sutb (StrikeUpTheBand) is a command line program to create a midi file from a text file. It will read a formatted text file of notes and commands and generate a multi-track synchronous midi song file.
The output is sent to stdout by default. From the command line you can redirect to file (sutb infile > outfile.mid) or pipe to synth (sutb infile | timidity -) for immediate playback.
c8 c8 d4 c4 f4 e2
c8 c8 d4 c4 g4 f2
c8 c8 cc4 a4 f16 g16 f16 e4 d4
White space characters are the space, tab and end-of-line. All notes within a line are seperated by space or tab. All lines within a block are seperated by the end-of-line character. All blocks are seperated from each other by blank lines.
This help file and also file table.h included with the source define the allowable spellings for notes and commands. If sutb does not understand something in your song file, the program will stop and attempt to write a meaningful message to stderr indicating the line number in your song file where the error has occured.
After the third line the format is flexible.
Initially you will set the key signature, instruments, volume levels, tempo, and startup text events.
Then appear the notes in lines and blocks.
A line consists of one or more notes/rest/tie/velocity/pan/mod each seperated by white space and the line ending with the new line character. The notes in a line are played consecutively from left to right.
A block consists of 1 or more lines of notes without any blank lines between. The number of lines in each block must match the qtyparts from line 3. Each line in a block corresponds to a different part. The top line of a block is the first part, the next line down in the block is the next part, and so forth.
All lines in the block are played synchronously. The total time count for the block is set by the first line and each subsequent line in the block must have the same line time count.
Blocks are seperated from other blocks by one or more blank lines. Blocks are played consecutively starting from the top of the file going down.
Instruments are defined on a seperate line by the command inst followed by an array of numbers representing either a sound bank or a sound patch. Instrument numbers range from 0-127.
A sound bank is set using the prefix letter 'b' followed by the bank number (example: b42). The default sound bank number is 0 so if no bank number precedes a patch number, bank zero is assumed.
A chromatic instrument sound patch is set using the number without prefix.
A percussion instrument sound patch is set using the number with the prefix letter 'd' (example: d35).
The inst numbers are read from left to right so first set the sound bank then the sound patches follow.
There must be one patch number for each part. The first patch number corresponds to the first part which is the top line of the block. The same patch number may be used repeatedly. You can change instruments between blocks.
The file /gm/inst contains a list of patch numbers which may be used in the instrument definition line if your sound patch set conforms to the General Midi standard. See also /jeux/inst for a description of the jeux soundfont patch numbers.
In this example there are two sound banks and 7 patch numbers for a 7 part song. Patch 0 and 12 are from bank 42, patch 55 and 127 are chromatic instruments from bank 0 and 35, 49 and 81 are percussion instruments from bank 0:
inst b42 0 12 b0 55 127 d35 d49 d81
Tempo is defined by the command tempo followed by a number defining the mspqn.
The mspqn is the number of microseconds per quarter note. A value of 1000000 (one million) means each quarter note is played once per second. A value of 100000 (hundred thousand) plays the song ten times faster or one quarter note each 1/10 second.
Normally tempo is referred to in beats per minute (bpm). The relation between bpm (assuming the quarter note gets the beat) and mspqn is giving by:
mspqn = { 1000000 * 60 } over bpm
The Tempo is defined on a seperate line between blocks, and may be redefined multiple times in the song file.
| bpm | mspqn |
| 60 | 1000000 |
| 120 | 500000 |
| 144 | 417000 |
| 200 | 300000 |
The key signature is defined with the command key followed by a number from -6 to 6 representing the number of sharps (+) or flats (-). The pitch of all notes shown in the table below, with octaves, will be raised or lowered one half step according to the key signature. The use of the key signature cuts down on the typing of accidentals.The key signature may be redefined throughout the song between blocks of notes.
| keynum | sharps/flats |
| 0 | key of c |
| 1 | f sharp |
| 2 | f,c sharp |
| 3 | f,c,g sharp |
| 4 | f,c,g,d sharp |
| 5 | f,c,g,d,a sharp |
| 6 | f,c,g,d,a,e sharp |
| -1 | b flat |
| -2 | b,e flat |
| -3 | b,e,a flat |
| -4 | b,e,a,d flat |
| -5 | b,e,a,d,g flat |
| -6 | b,e,a,d,g,c flat |
example to set a key signature with 2 flats:
key -2
Notes for chromatic instruments require [Pitch code][Time code].
Notes for drums/percussion require only [Time code].
Each line of notes within a block are either associated with a chromatic instrument or percussion instrument according to the previous inst definition.
All pitch codes are composed of the letters a,b,c,d,e,f,g and A,B,C,D,E,F,G. The pitch code for middle c on the keyboard is the letter [c]. The lowest pitch code is CCC and the highest pitch code is bbbb. The pitch codes span 7 octaves. See /docs/FIGURE1.pdf for a pictoral representation of the pitch codes.
| pitch code |
| cccc dddd eeee ffff gggg aaaa bbbb |
| ccc ddd eee fff ggg aaa bbb |
| cc dd ee ff gg aa bb |
| c d e f g a b |
| C D E F G A B |
| CC DD EE FF GG AA BB |
| CCC DDD EEE FFF GGG AAA BBB |
| + | sharp | raise 1/2 step |
| - | flat | lower 1/2 step |
| n | natural | override key sig |
The time code is required for all instruments. The time code is the number of beats the note is held for.
| time | code | MIDI ticks |
| whole | 1 | 1536 |
| dotted half | .2 | 1152 |
| half | 2 | 768 |
| dotted quarter | .4 | 576 |
| quarter | 4 | 384 |
| dotted eighth | .8 | 288 |
| triplet_2 | 6 | 256 |
| eighth | 8 | 192 |
| dotted sixteenth | .16 | 144 |
| triplet_4 | 12 | 128 |
| sixteenth | 16 | 96 |
| thirtysecond | 32 | 48 |
| sixtyfourth | 64 | 24 |
triplet_2 is three notes played over the duration of a half note. triplet_4 is three notes played over the duration of a quarter note. You will always find these in groups of 3.
Example of a valid sequence of chromatic notes:
CC8 n e1 a16 g4 EE-8 b-2 g+8 E-.4 c1
Example of a valid sequence of drum notes:
8 8 16 16 8 4 4 4 16 16 8
See also file "table.h" for a sorted listing of all notes this program uses. See also the /gm and /jeux samples directory.
In a song with more than 1 part, each line of notes in a block are played synchronously (they each start and end together, reading from left to right). In order to assure synchronization, the total time count for each line in a block must match the first line of the block.
example:
c4 c4 c4 c2
c4 g4 f8 f8 g1
a2 a2 a4
In this example the first line is equivalent to 5 quarter notes, the second line is equivalent to 7 quarter notes and the third line is equivalent to 5 quarter notes. The second line is in error because the total time count for the line does not match the first line of the block.
If you try to feed this block to sutb, you will get an error message similar to the following:
line 10: 1 too many half notes
The log file will display all the line time counts for each block in units of MIDI "ticks".
The rest is defined by [r][Time Code]. Put r by itself on any line but the first line of a block to force the part to rest for the entire line. Consecutive rests accumulate to delay the onset of the next chromatic or drum noteON.
| rest | time |
| r | entire line |
| r1 | whole |
| r2 | half |
| r4 | quarter |
| r8 | eighth |
| r16 | sixteenth |
| r32 | thirtysecond |
Tie is defined by [t][Time Code]. Tie extends the length of time a note is held beyond what the standard note allows. Place one or more tie codes before the note to be extended. Consecutive ties accumulate to delay the onset of the next chromatic or drum noteOFF.
| tie | time |
| t1 | whole |
| t2 | half |
| t4 | quarter |
| t8 | eighth |
| t16 | sixteenth |
| t32 | thirtysecond |
example:
t4 c4
//is the same as c2.
example:
t1 t1 c1
//ties 3 whole notes together as one.
The overall loudness of the song is controlled by velocity, volume, expression and duplication of parts. In general, velocity affects a single note, volume controls the line of notes, and expression controls the block.
The velocity is how hard a key is depressed on a MIDI keyboard. Velocity is defined by the commands v0 thru v127. v0 will produce no sound (mute) and v127 is the loudest. Velocity is initially set to 64 and affects only the note following the velocity command.
example to play the e4 note at full velocity:
c4 d4 v127 e4 f4
Volume is defined by the command volume followed by an array of volume level numbers, one for each part. Volume level may range from 0-127. Volume is initially set to 64. The volume is defined on a seperate line between blocks, and may appear multiple times in the song file. If only one volume level is specified, the level will be applied to all parts. If you are going to change both instrument and volume between blocks, change instrument first then volume.
example for a 4 part song where the first two parts are full volume and the last two are reduced:
volume 127 127 100 70
Expression is defined by the command expression followed the starting and ending expression values. Expression is used to create a crescendo or decrescendo affect by ramping the loudness of each note in each line of the block. Expression values may range from 0-127. If the starting and ending values are the same, the expression is reset to this constant value.
example to crescendo from mid to max:
expression 64 127
Pan is defined by the commands pan0 thru pan127. Pan directs the sound to one speaker or the other or any combination in between. Pan commands are inserted between notes and stay in effect until the next pan command.
Alternate command for pan0 is the left arrow <, for pan64 is the equal sign =, and for pan127 is the right arrow >.
Modulation is defined by the commands mod0 thru mod127. Modulation introduces a synth dependent vibrato affect. Modulation commands are inserted between notes and stay in affect until the next mod command. mod0 is no affect and mod127 is full vibrato.
Trill is defined by the command tr16 or tr32 followed by a note to be trilled. tr16 plays the note as an alternating sequence of 1/16 notes starting on pitch and raising one half step. tr32 plays as an alternating sequence of 1/32 notes. The note count of the note to be trilled must be an even multiple of 48 (1/32) or 96 (1/16) midi ticks.
example to trill the d2:
c4 g.8 tr32 d2 f1
Transpose is defined by the command transpose followed by the number of half steps to transpose. Transpose is defined on a line between blocks, and affects the pitch of all subsequent chromatic notes in all blocks. A positive number will transpose up and a negative will transpose down.
example to transpose up one half step:
transpose 1
The normal noteON noteOFF noteON noteOFF... sequence can be altered with the following special affects.
Hold is defined by the command hold followed by the line of notes. Hold suspends noteOFF until the end of line. Hold may be applied to one or more lines in the block, and stays in affect until the end of line.
example:
hold c4 d4 e4 f4
Staccato is defined by the command staccato followed by the line of notes. Staccato shortens the note time count slightly and delays noteON. Staccato may be applied to one or more lines in the block, and stays in affect until the end of the line.
example:
staccato c4 d4 e4 f4
Legato is defined by the command legato followed by the line of notes. Legato causes noteON to occur before the previous noteOFF. Legato may be applied to one or more lines in the block, and stays in affect until the end of the line.
example:
legato c4 d4 e4 f4
Roll is defined by the command roll followed by the amount of roll delay in midi ticks. Each note of the chord is played consecutively, starting from the bottom line of the block going up to the top. A larger delay amount rolls the chord slower. Put the command roll and the delay amount on a seperate line before the block to be rolled. Every line of the block contains only one note making up the chord.
example to roll a 7 note chord:
roll 48
a-1
e-1
c1
B-1
AA-1
EE-1
AAA-1
Pitch wheel is defined by the command wheel followed by a series of alternating chromatic and drum notes. The first note following the command is turned on (noteON) then the wheel is rolled uniformly to slide the pitch from chromatic note to chromatic note according to the time of the intermediate drum note. The first and last note in the line must be chromatic. Any number of alternating chromatic and drum notes are allowed. The wheel range is 12 steps. Inserting rest, tie, velocity, pan or some other affect will produce undefined behavior. The wheel may be applied to one or more lines in the block, and stays in affect until the end of the line.
example:
wheel c4 2 G1 2 B-4 4 c2
These text based meta-events are inserted into the midi file to aid in describing the song. How they are displayed is synth dependent. Each text event is defined on a seperate line between blocks.
example for a 4 part song:
trackname SUPRANO ALTO TENOR BASEORWHATEVER
example for a 4 part song:
instname SQUARE_WAVE TROMBONE BASS_DRUM CRASH_CYMBAL
example:
text This song requires the Jeux soundfont loaded in bank 42.
example:
copywrite (c) John Smith Productions 2006
example:
marker Begin verse-1
example:
lyric Happy birthday to you !
//Single line comments begin with a double forward slash.
//The entire line is ignored.
/*
Block comments appear on their own line and begin with slash asterisk and end with asterisk slash. All blocks bounded by these markers will be ignored. Single line comments may be nested within block comments.
*/
example to skip down to line 914:
skip 914
The following midi messages are supported:
| Message | Meaning |
| 9n xx yy | Note ON, xx=notenum, yy=velocity |
| 8n xx yy | Note OFF |
| Bn 00 xx | Bank Select xx=banknum |
| Bn 01 xx | Modulation xx=0-127 |
| Bn 06 xx | Pitch wheel range xx=steps |
| Bn 07 xx | Volume, xx=level |
| Bn 10 xx | Pan |
| Bn 11 xx | Expression |
| Cn xx | Program Change, n=channel, xx=instrumentID |
| En ll hh | Pitch wheel position, ll=low byte, hh=hi byte |
| FF 01 nn tt | Text nn=qty_bytes, tt=text |
| FF 02 nn tt | Copywrite |
| FF 03 nn tt | Sequence or Track name |
| FF 04 nn tt | Instrument Name |
| FF 05 nn tt | Lyric |
| FF 06 nn tt | Marker |
| FF 51 03 xxxxxx | Tempo, xxxxxx=microsec/qtrnote |
| FF 59 02 nn 00 | Key, nn=number of sharps/flats |
sutb does not generate sheet music (see lilypond), nor can it play a midi file (see timidity).
There are several fixed size arrays defined in file sutb.h You may increase these values and recompile if your hardware and midi synthesizer allow:
| Hex Bytes | Comment |
| 4d 54 68 64 00 00 00 06 | file header |
| 00 00 | file format (0 = single track) |
| 00 01 | qty tracks |
| 01 80 | ticks per qtr note |
| 4d 54 72 6b | track header |
| 00 00 00 16 | length of track 0x16=22 bytes |
| 00 ff 51 03 | setting tempo |
| 0e 15 c4 | microseconds per qtr note |
| 00 | delta time |
| c0 2a | channel 0 inst 2a |
| 00 | delta time |
| 90 35 7f | noteON notenum=37 vel=7f |
| 86 00 | delta time |
| 35 00 | noteOFF |
| 00 | delta time |
| ff 2f 00 | end of track |
| Subdirectory | Contents |
| /src | source code |
| /gm | general midi band/orchestra samples |
| /jeux | Jeux14.sf2 pipe organ soundfont samples |
| /table | generates lookup table.h |
| /docs | man page, README, CHANGELOG... |
| /gui | gtk pushbutton dialog |
Verbose output is written to file ./log
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation version 2.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.