.TH MIDGE 1 "17 July 2006" .SH NAME midge - generate midi file from text description of music .SH SYNOPSIS \fBmidge\fR [options] [filename] .SH DESCRIPTION \fBmidge\fR generates a type 1 midi file from a text description of music. \fBmidge\fR takes it's input from stdin unless \fBfilename\fR is specified. .SH OPTIONS .HP \fB-h or --help\fR .IP Show help text. .HP \fB--version\fR or \fB--warranty\fR or --\fBabout\fR .IP Show version and license info. .HP \fB-v\fR or \fB--verbose\fR .IP Print verbose output to stdout. .HP \fB-d\fR or \fB--debug\fR .IP Print debugging output to stdout (sets verbose mode automatically). .HP \fB-q\fR or \fB--quiet\fR .IP Quiet. no stdout. .HP \fB-o file\fR or \fB--outfile file\fR .IP Midi output to \fBfile\fR. Otherwise to a.out.mid .HP \fB-c\fR or \fB--check\fR .IP Check input only; No midi output. .HP \fB-u\fR or \fB--unroll-loops\fR .IP Unroll all the repeat blocks before parsing and save the unrolled source code to a new file (*.long.mg). Should be set automatically if needed. .HP \fB-U\fR or \fB--no-unroll-save\fR .IP Don't save unrolled source to file. .HP \fB-R\fR or \fB--no-reset\fR .IP Don't insert `reset all controllers' event at start of tracks. .HP \fB-t bpm\fR or \fB--tempo bpm\fR .IP Set tempo to \fBbpm\fR beats per minute, overriding value set in input file. .HP \fB-b steps\fR or \fB--bend-steps steps\fR .IP Set the number of steps per quarter note for the simple bend syntax. .HP \fB--unsafe\fR .IP Do not use Safe.pm to run Perl code from \fB%eval\fR blocks. .HP \fB-s number\fR or \fB--seed number\fR .IP Use \fBnumber\fR as the seed for the random number generator. .HP \fB-S [scale [root]]\fR or \fB--show-scale [scale [root]]\fR .IP List notes in \fBscale\fR starting from \fBroot\fR. If \fBroot\fR is omitted c4 is used. If \fBscale\fR is omitted, a list of suported scales is shown. .HP \fB-I path\fR or \fB--include path\fR .IP Add \fBpath\fR to include paths. Can be specified multiple times or \fBpath\fP can be a list separated by colons or commas. .SH INPUT LANGUAGE Sample source file to play a scale of E. ================start file====================== # this line is a comment \fB@head\fR { # there must be exactly 1 @head section # set time signature \fB$time_sig\fR 4/4 # set tempo in BPM \fB$tempo\fR 120 } # end of @head section \fB@body\fR { # there must be exactly 1 @body section # start a music track on channel 1 # multiple tracks can use the same channel \fB@channel\fR 1 { # set patch to electric bass \fB$patch\fR 34 # notes. see below for explanation. /l4/e3 # quarter note e in third octave f\fB+\fR # f sharp same octave same length # use `\fB-\fR' for flat g+ a b # rest of notes c+\fB4\fR d+ e # octave changes at c } # end of track } # end of @body section ========================end file==================== More examples are included in the examples/ directory of the archive. In the following, is a required parameter and [name] is an optional parameter. Notes. The format of a note is: [\fB/options/\fR]<\fBname\fR>[\fB+\fR|\fB-\fR][\fBoctave\fR] The \fB/options/\fR section can contain the following: \fBl\fR[numerator:] Sets the length of the note to (\fBnumerator\fR or one) divided by \fBdenominator\fR. ie. l4 = quarter note, l1 = whole note, l3:4 = 3/4 note (3 quarter notes tied). An uppercase `\fBL\fR' may be used instead to distinguish it from a `1'. \fBr\fR Sets the number of times to repeat the note. For example /\fBl\fR8\fBr\fR16/ makes the note duration 1/8 and repeats the note 16 times. \fBa\fR Sets the note's note on velocity (attack) \fBd\fR Sets the note's note off velocity (decay) \fBz\fR[+|-][%] Offsets the note by \fBnumber\fR midi clicks. Positive values play the note late and negative values play it early. If \fBnumber\fR is followed by a \`\fB%\fR\' character it is taken as a percentage of the current note length. Offset values are \fBnot\fR inherited by subsequent notes. \fBZ\fR[+|-][%] As the above \`\fBz\fR\' option but a random value is used. If \fBnumber\fR is negative or positive (plus sign \fBrequired\fR), a value between zero and \fBnumber\fR is used. If there is no sign, a value between plus and minus \fBnumber\fR is used. The offset option will not work with the \fBr\fRepeat note option, but the same effect can be achieved using a \fB%repeat\fR block. Notes cannot be offset backwards (ie played early) unless they are preceded by a rest. To work around this I have added the \fB$shorten\fR keyword, described below. See also \fB$unquantise\fR. \fBname\fR is the name of the note ie. [a-g] \fBrequired\fR. \fB+\fR sharp. \fB-\fR flat. \fBoctave\fR is the midi octave ie. [1-11]. Although most midi software uses 0 for the lowest octave, I have used 1 for consistency with the midi channels and instrument names which both count from 1. If not specified, the length, octave, attack and decay are inherited from the previous note. In a drum track, instead of the note names, aliases can be used. For example, to get an open hi hat, instead of `\fBf+3\fR' you can use `\fBhh_o\fR'. See README.drums for a full list of aliases. Rests. Rests are written as note `\fBr\fR', with \fB/options/\fR the same as for notes, but with only the length and repeat options used. The length value is inherited from note to rest and vice versa. Bars. The pipe symbol (`|') can be used to denote bars. The lengths of bars are not checked -- this is only to allow more readable source files. Bars can be numbered by appending a number to the pipe symbol. They may be separated by an underscore but not by spaces. Simple bar example: | c d e f | g a b c Numbered bar examples: |1 c d e f |2 g a b c |_1 c d e f |_2 g a b c The consistency of bars can be checked by using the \fB$bar_strict\fR keyword in the \fB@head\fR section. This gives an error or warning unless all tracks have the same number of bars and numbered bars appear at the same time in each track: $bar_strict \fBwarn\fR # Print a warning message for inconsistent bars. $bar_strict \fBerror\fR # Exit with an error message for inconsistent bars. Top level keywords. \fB@head\fR { content } There must be exactly one \fB@head\fR section. See below for description of \fBcontent\fR. \fB@body\fR { content } There must be exactly one \fB@body\fR section. See below for description of \fBcontent\fR. Keywords in the \fB@head\fR section. \fB$time_sig\fR The \fBb\fR value must be one of 4, 8, 16, 32, 64. \fB$tempo\fR \fBt\fR is the tempo in BPM. Both \fB$time_sig\fR and \fB$tempo\fR are also allowed within an @channel block (described below). \fB$title\fR Sets the title of the song to \fBtitle\fR. If \fBtitle\fR contains spaces it must be inside double quotes. \fB$resolution\fR <n> Sets the number of midi clicks per quarter note to \fBn\fR. The default is 96. Keywords in the \fB@body\fR section. \fB%define\fR <name> { notes } Define a sequence of \fBnotes\fR, assigning it to \fBname\fR to be recalled in a music track. Defined sequences are used by including: \fB~\fR<name>[/transpose/] within a track to include the sequence \fBname\fR, transposed by \fBtranspose\fR semitones. Previously defined sequences can be used in subsequent \fB%define\fR blocks. for instance: \fB%define\fR a_riff { a3 a c4 d } \fB%define\fR d_riff { d4 d f g } \fB%define\fR main_riff { \fB~\fRa_riff \fB~\fRd_riff } Although we could achieve the same result by transposing the first riff to make the second: \fB%define\fR a_riff { a3 a c4 d } \fB%define\fR main_riff { \fB~\fRa_riff \fB~\fRa_riff\fB/5/\fR } \fBdefine\fR blocks may also contain repeat blocks, bend blocks and $volume/patch/reverb etc. \fB@channel\fR <number> [name] { content } Begin a midi track on channel \fBnumber\fR, optionally setting the instrument name to \fBname\fR. If \fBname\fR contains spaces it must be inside double quotes. \fBcontent\fR can include notes, rests, previously defined sequences, and the following keywords: \fB$time_sig\fR <a/b> Changes the time signature for the song (affects all tracks). The \fBb\fR value must be one of 4, 8, 16, 32, 64. \fB$tempo\fR <t> Changes the song tempo (affects all tracks). \fBt\fR is in BPM. \fB$patch\fR [[bank_LSB,]bank_MSB,]<number|name> Set patch number for this channel to \fBnumber\fR or \fBname\fR. Where \fBnumber\fR is from 1 to 128 and \fBname\fR is an alias as defined in README.patches. Optionally select bank number \fBbank_MSB\fR. Optionally select bank LSB number \fBbank_LSB\fR (used for external midi keyboards). Each value must be in the range 1-128. \fB$bank\fR [LSB,]<MSB> Select bank number \fBMSB\fR. Optionally setting the LSB value (used for external midi keyboards) to \fBLSB\fR. Both values must be in the range 1-128. \fB$length\fR [n:]<d> Set default note length. The value is specified in the same format as in the note options. \fB$shorten\fR <number> Shorten each note by \fBnumber\fR midi clicks, to allow space for notes to be offset backwards. \fB$unquantise\fR [+|-]<number>[%] Apply a random offset to each note. \fBnumber\fR has the same meaning as for the \fBZ\fR note option above. \fB$octave\fR <number> Set default octave to \fBnumber\fR \fB$volume\fR <number> Set the track volume to \fBnumber\fR \fB$attack\fR <number> Set the note's attack to \fBnumber\fR \fB$decay\fR <number> Set the note's decay to \fBnumber\fR \fB$reverb\fR <number> Set the reverb depth to \fBnumber\fR on the current channel. \fB$chorus\fR <number> Set the chorus depth to \fBnumber\fR on the current channel. \fB$pan\fR <number> Set the pan value to \fBnumber\fR. 0 is left 127 is right. The volume, attack, decay, reverb, chorus and pan values must be integers from 0 to 127. They can also be specified as a range (eg `\fB8-64\fR'), in which case a random value within the range is used. \fB%pan_all\fR { note value ... } Sets the pan value for each subsequent instance of \fBnote\fR in the current track. This is mainly intended for panning a drum kit, but could be used on another track. \fBvalue\fR can be an integer or a range (eg `\fB8-64\fR'). Multiple \fBnote value\fR pairs are allowed. If two notes with different pan_all values are played at the same time anything could happen. To affect every note in the channel with a range, use `\fB*\fR' or `\fBany\fR' for \fBnote\fR. The \fB/r4/\fR<note> method of repeating notes will not work with this option, but the same effect can be achieved using a repeat block. \fB$marker\fR <text> Adds a marker event with \fBtext\fR as it's content. If \fBtext\fR contains spaces it must be quoted using double-quote characters. \fB%repeat\fR <number> { notes } Repeat \fBnotes number\fR times. \fBnotes\fR can include notes, rests, predefined sequences and other \fB%repeat\fR blocks. \fB%bend\fR <note> { event ... } Play \fBnote\fR and move the pitch wheel in the manner described by multiple \fBevent\fRs, which have the following format: [n:]<d><+|-><value> where \fBn\fR and \fBd\fR specify the time from the start of the note or from the previous event, in the same format as the note lengths, and \fBvalue\fR is the amount to bend the note by (the plus or minus sign is required). With the default pitch wheel range of +/- 2 semitones a value of 32 equates to one semitone. Note that the bend amount is relative. The maximum \fBcumulative\fR bend amount is plus or minus 64. For example the following: %bend a3 { 4+32 4-32 2+0 } Plays the note a3 for 1/4 note, bends up a whole tone for 1/4 then returns down to a3 and holds for 1/2 note. \fB$bend_range\fR <number> Changes the pitch wheel range to +/- \fBnumber\fR. This sets the maximum bend up and down, so if it is set to 4, a bend value of 64 will bend up 4 semitones and -64 will bend down 4 semitones. The default range for most midi devices is 2 semitones. \fB$pitch\fR <val> Set the pitch wheel value to \fBval\fR. This can be used in conjunction with separate note on and note off events (see below under `simultaneous notes') to create complex bending effects. Unlike the \fB%bend\fR syntax above, this does \fBnot\fR reset the pitch wheel to the neutral position (64) Simpler pitch bends can be created with this syntax: /l8/e4\fB=>\fRg4\fB=>\fRe4 This bends from e4 up to g4 and back down to e4 in linear steps over the duration of an eighth note. By default there are 16 steps per quarter note duration (8 steps in this example), but a different value can be set using the `-b' command line switch. Any number of notes can be used, but the first one must have a length value and each of them must have an octave value. \fB%choose\fR [time] { weighting item ... } where time is a length value in the format [n:]<d> the same as used in the length options, with the `l' omitted. If \fBtime\fR is not specified: Choose one \fBitem\fR from a list, where each \fBitem\fR can be a note, rest, or predefined riff, and each item has a \fBweighting\fR which defines how likely it is to be chosen. For example: %choose { 2 a3 4 c5 3 e4 1 g3 } gives a3 a 20% chance, c5 - 40% ; e4 - 30% and g3 - 10% Each item \fBmust\fR have a weighting. See also scales below. if \fBtime\fR is specified: Choose multiple \fBitem\fRs from the list up to a length of \fBtime\fR. If all the \fBitem\fRs are too long to end the riff exactly at \fBtime\fR, the remainder is filled with a rest. When choose is used in this way each note or rest must have a length value and any predefined riffs used must have a fixed length (ie the first note must have a length value), and the length of the whole riff must be specified in the choose block in the same format as for notes. for example: %define riff_1 { /l2/a3 /l4/b c4 } # riff is 1 bar long %choose \fB4:1\fR { # choose 4 bars 1 /l8/d4 3 /l8/e4 2 /l4/g4 1 \fB/l1/~riff_1\fR } If \fBtime\fR is \fB0\fR or \fB-\fR then midge looks for a block of the form: \fBrhythm\fR { n[:d] ... } which is taken as a series of note length values for which the pitches are chosen from the list. Other tokens are passed through, so you can insert specific notes, predefined riffs or rests. Any token in the block begining with an underscore will be passed through, with the underscore removed. See examples/tutorial/choose_scale.mg for an example. Another way to specify the list of notes/weightings is with the \fBscale\fR keyword: \fBscale\fR minor /l8/g4-6 [ weight ... ] This selects a G Minor scale from the 4th to 6th octaves (ie g4 to g6). The length value is unnecesary if you are using a rhythm block. If the \fB-6\fR is omitted a single octave is used. The weight block specifies the note weightings in order. If omitted all weightings are equal. To ingore a note use a weighting of 0, but there \fBmust\fR be a weighting for each note if the block is present at all. The \fB-S\fR switch can be used to show the notes in a scale or a list of supported scales. \fB%chain\fR <time> { start <note> note1 [ weight note ... ] ... rhythm [ weight length ... ] \fBor\fR rhythm { length ... } } Define a `chain' structure where for each note there is a weighted list of notes which may follow it. A starting point is picked randomly from all the notes used, or specified with the \fBstart\fR keyword, and then subsequent notes are chosen from the appropriate list up to a total length of \fBtime\fR. The \fBrhythm\fR keyword has two forms: Using square brackets `[]', a weighted list of note lengths can be defined, which will be chosen from randomly. Using braces `{}', a list of length values can be defined which will be used in sequence (repeating as neccessary). To play through the rhythm block just once, set the \fBtime\fR to \fB0\fR or \fB-\fR. In this case the rhythm block is parsed in the same way as described above for \fB%choose\fR with time set to zero. The keyword \fBtimes\fR can be used as a synonym for \fBrhythm\fR. The \fBstart\fR keyword specifies the note to start from when using the chain. If \fBstart\fR is omitted, the start note is chosen randomly. Another way define the notes in a \fBchain\fR block is to use one of the built in scales. Then the weightings are specified in the form of a matrix, with a row for each "from" note (one for each note of the scale) and a column for each "to" note. An example of this form can be found in the file examples/tutorial/chain_scale.mg To use the choose or chain blocks, the file must be compiled with the unroll-loops option (it is set automatically when a choose or chain block is found). This option saves the unrolled source code in a new file, so if it produces particularly good output you have an exact copy which you can make other changes to without losing the generated track. Note that a choose and chain blocks cannot be inside a %define or inside another choose or chain block. \fB%eval\fR { Perl code } Run a block of Perl code and replace the %eval block with the value returned from the Perl code. \fB%eval -\fR { Perl Code } Run a block of Perl code without reading the return value. Perl code is run using the Safe module if it is present, with :base_core, :base_math and :base_mem allowed. If Safe.pm is not available or more permissions are needed the --unsafe option causes midge to run the %eval blocks in it's own perl process. Keywords allowed at any point in the source. \fB%include\fR <file> Includes the contents of \fBfile\fR as if they had been written at that point in the source file. \fBMust\fR be on a line of it's own in the source file. Simultaneous Notes. The most flexible way to play simultaneous notes is by using separate tracks (you can use the same channel/patch), or by using separate note on and note off events (see below). However, there is a simpler way with some limitations. For example: \fB( c e g )\fR will play the notes c, e and g simultaneously, making a C chord. The length of all the simultaneous notes is the same as the first one (determined by it's own length value or the one inherited from the previous note, rest, or $length declaration. One way to use this to make chords is as follows: \fB%define minor { ( c e- g ) }\fR # define minor to be a c-minor \fB%define major { ( c e g ) }\fR # define major to be a c-major \fB%define 7th { ( c e g b- ) }\fR # define 7th to be a c-7th Then you can use the in your music tracks: $length 4 $octave 4 # set default length and octave \fB~major\fR # play a c-major \fB~minor/9/\fR # play an a-minor \fB~7th/5/\fR # play an f-7th To make chords sound strummed, the \fBstrum\fR keyword can be used: \fB$strum\fR 5 This sets the interval between each note in subsequent chords to 5 midi clicks. To create complex patterns of simultaneous notes on one track, separate note on and note off events can be used. These are specified in the same way as normal notes, but with a \fB+\fR prepended for note on and a \fB-\fR prepended for note off. The length and repeat options cannot be used. The length of notes entered this way is controlled by putting rests or other notes between the note on and note off events. eg: \fB+\fRc4 /l4/r \fB+\fRe r \fB+\fRg /l2/r \fB-\fRc \fB-\fRe \fB-\fRg plays and holds c4, after a 1/4 note plays and holds e4 and after another 1/4 note plays and holds g4, releasing all three after a further 1/2 note. Tuplets. While it is possible to create tuplets by choosing a suitable note length, they can also be written in a more conventional way using the \fB%tuplet\fR keyword: \fB%tuplet\fR n:d { notes... } plays \fBn\fR notes in the space of \fBd\fR. \fBnotes\fR can contain anything allowed in a @channel block. The note values are then automatically altered to create the tuplet. For example: %tuplet 5:3 { /l8/e4 f g f e } plays five eigth notes in the space of three. Tuplets can be nested to any depth. See examples/tutorial/tuplet.mg for an example. Midge does \fBnot\fR check that the length of music inside the tuplet block is correct. Keys. If you want to import your midi file into a notation editor you will want to set the key. This is done with: \fB$key\fR <name>[+|-][m] Where \fBname\fR is a-g, +|- are sharp and flat, and m is minor. If the whole piece stays in the same key you can set it in the @head section, otherwise it can appear anywhere in a @channel section, and will affect all tracks. If you are used to regular music notation and want notes to be sharp or flat automatically depending on the key, use the \fB$key_strict\fP keyword instead. To get a natural note use the \fB=\fP sign, eg in G, \fBf=\fP plays an f natural. The \fB$key_strict\fP keyword can only be used in the @head section. The key can still be changed using the regular \fB$key\fP keyword. \fB$ctrl\fR <num,val> Set controller number \fBnum\fR to \fBval\fR. \fB$rpn\fR [num-msb,]<num-lsb,val-msb>[,val-lsb] Set the rpn controller \fBnum\fR to \fBval\fR \fB$nrpn\fR [num-msb,]<num-lsb,val-msb>[,val-lsb] Set the nrpn controller \fBnum\fR to \fBval\fR \fB%verbatim\fR { byteval... } Insert a string of bytes into the midi file. Each \fBbyteval\fR can be in either decimal (0-255) or hex (0x00-0xFF). The keyword \fBbytes\fR can be used instead of \fBverbatim\fR. \fB$print\fR <text> Print \fBtext\fR to stdout. If \fBtext\fR contains spaces it must be quoted using double quotes (\fB"\fR). .SH BUGS When building scales, although the pitches are correct, the note names may be technically wrong, eg `a sharp' instead of `b flat'. If there is an error in a %repeat or %define block the error message only gives the line number of the %repeat or %define keyword. No commercial potential. If you find any other bugs, please let me know. .SH "SEE ALSO" midi2mg(1), emacs(1), playmidi(1), drvmidi(1), timidity(1). .SH AUTHOR David Riley <dave@dmriley.demon.co.uk>