| MIDGE(1) | General Commands Manual | MIDGE(1) |
midge - generate midi file from text description of music
midge [options] [filename]
midge generates a type 1 midi file from a text description of music. midge takes it's input from stdin unless filename is specified.
-h or --help
--version or --warranty or --about
-v or --verbose
-d or --debug
-q or --quiet
-o file or --outfile file
-c or --check
-u or --unroll-loops
-U or --no-unroll-save
-R or --no-reset
-t bpm or --tempo bpm
-b steps or --bend-steps steps
--unsafe
-s number or --seed number
-S [scale [root]] or --show-scale [scale [root]]
-I path or --include path
Sample source file to play a scale of E.
================start file======================
# this line is a comment
@head { # there must be exactly 1 @head section
# set time signature
$time_sig 4/4
# set tempo in BPM
$tempo 120
} # end of @head section
@body { # there must be exactly 1 @body section
# start a music track on channel 1
# multiple tracks can use the same channel
@channel 1 {
# set patch to electric bass
$patch 34
# notes. see below for explanation.
/l4/e3 # quarter note e in third octave
f+ # f sharp same octave same length
# use `-' for flat
g+ a b # rest of notes
c+4 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, <name> is a required parameter and [name] is an optional parameter.
Notes.
The format of a note is: [/options/]<name>[+|-][octave]
The /options/ section can contain the following:
l[numerator:]<denominator>
Sets the length of the note to (numerator or one) divided by denominator. ie. l4 = quarter note, l1 = whole note, l3:4 = 3/4 note (3 quarter notes tied). An uppercase `L' may be used instead to distinguish it from a `1'.
r<number>
Sets the number of times to repeat the note. For example
/l8r16/
makes the note duration 1/8 and repeats the note 16 times.
a<number>
Sets the note's note on velocity (attack)
d<number>
Sets the note's note off velocity (decay)
z[+|-]<number>[%]
Offsets the note by number midi clicks. Positive values play the note late and negative values play it early. If number is followed by a `%´ character it is taken as a percentage of the current note length. Offset values are not inherited by subsequent notes.
Z[+|-]<number>[%]
As the above `z´ option but a random value is used. If number is negative or positive (plus sign required), a value between zero and number is used. If there is no sign, a value between plus and minus number is used.
The offset option will not work with the repeat note option, but the same effect can be achieved using a %repeat block.
Notes cannot be offset backwards (ie played early) unless they are preceded by a rest. To work around this I have added the $shorten keyword, described below. See also $unquantise.
name is the name of the note ie. [a-g] required.
+ sharp.
- flat.
octave 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 `f+3' you can use `hh_o'. See README.drums for a full list of aliases.
Rests.
Rests are written as note `r', with /options/ 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 $bar_strict keyword in the @head 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 warn # Print a warning message for inconsistent bars.
$bar_strict error # Exit with an error message for inconsistent bars.
Top level keywords.
@head { content }
There must be exactly one @head section. See below for description of content.
@body { content }
There must be exactly one @body section. See below for description of content.
Keywords in the @head section.
$time_sig <a/b>
The b value must be one of 4, 8, 16, 32, 64.
$tempo <t>
t is the tempo in BPM.
Both $time_sig and $tempo are also allowed within an @channel block (described below).
$title <title>
Sets the title of the song to title. If title contains spaces it must be inside double quotes.
$resolution <n>
Sets the number of midi clicks per quarter note to n. The default is 96.
Keywords in the @body section.
%define <name> { notes }
Define a sequence of notes, assigning it to name to be recalled in a music track. Defined sequences are used by including:
~<name>[/transpose/]
within a track to include the sequence name, transposed by transpose semitones. Previously defined sequences can be used in subsequent %define blocks. for instance:
%define a_riff { a3 a c4 d }
%define d_riff { d4 d f g }
%define main_riff { ~a_riff ~d_riff }
Although we could achieve the same result by transposing the first riff to make the second:
%define a_riff { a3 a c4 d }
%define main_riff { ~a_riff ~a_riff/5/ }
define blocks may also contain repeat blocks, bend blocks and $volume/patch/reverb etc.
@channel <number> [name] { content }
Begin a midi track on channel number, optionally setting the instrument name to name. If name contains spaces it must be inside double quotes.
content can include notes, rests, previously defined sequences, and the following keywords:
$time_sig <a/b>
Changes the time signature for the song (affects all tracks). The b value must be one of 4, 8, 16, 32, 64.
$tempo <t>
Changes the song tempo (affects all tracks). t is in BPM.
$patch [[bank_LSB,]bank_MSB,]<number|name>
Set patch number for this channel to number or name. Where number is from 1 to 128 and name is an alias as defined in README.patches. Optionally select bank number bank_MSB. Optionally select bank LSB number bank_LSB (used for external midi keyboards). Each value must be in the range 1-128.
$bank [LSB,]<MSB>
Select bank number MSB. Optionally setting the LSB value (used for external midi keyboards) to LSB. Both values must be in the range 1-128.
$length [n:]<d>
Set default note length. The value is specified in the same format as in the note options.
$shorten <number>
Shorten each note by number midi clicks, to allow space for notes to be offset backwards.
$unquantise [+|-]<number>[%]
Apply a random offset to each note. number has the same meaning as for the Z note option above.
$octave <number>
Set default octave to number
$volume <number>
Set the track volume to number
$attack <number>
Set the note's attack to number
$decay <number>
Set the note's decay to number
$reverb <number>
Set the reverb depth to number on the current channel.
$chorus <number>
Set the chorus depth to number on the current channel.
$pan <number>
Set the pan value to number. 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 `8-64'), in which case a random value within the range is used.
%pan_all { note value ... }
Sets the pan value for each subsequent instance of note in the current track. This is mainly intended for panning a drum kit, but could be used on another track. value can be an integer or a range (eg `8-64'). Multiple note value 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 `*' or `any' for note. The /r4/<note> method of repeating notes will not work with this option, but the same effect can be achieved using a repeat block.
$marker <text>
Adds a marker event with text as it's content. If text contains spaces it must be quoted using double-quote characters.
%repeat <number> { notes }
Repeat notes number times. notes can include notes, rests, predefined sequences and other %repeat blocks.
%bend <note> { event ... }
Play note and move the pitch wheel in the manner described by multiple events, which have the following format:
[n:]<d><+|-><value>
where n and d specify the time from the start of the note or from the previous event, in the same format as the note lengths, and value 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 cumulative 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.
$bend_range <number>
Changes the pitch wheel range to +/- number. 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.
$pitch <val>
Set the pitch wheel value to val. 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 %bend syntax above, this does not reset the pitch wheel to the neutral position (64)
Simpler pitch bends can be created with this syntax:
/l8/e4=>g4=>e4
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.
%choose [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 time is not specified:
Choose one item from a list, where each item can be a note, rest, or predefined riff, and each item has a weighting 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 must have a weighting. See also scales below.
if time is specified:
Choose multiple items from the list up to a length of time. If all the items are too long to end the riff exactly at time, 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 4:1 { # choose 4 bars
1 /l8/d4 3 /l8/e4 2 /l4/g4 1 /l1/~riff_1
}
If time is 0 or - then midge looks for a block of the form:
rhythm { 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 scale keyword:
scale 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 -6 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 must be a weighting for each note if the block is present at all.
The -S switch can be used to show the notes in a scale or a list of supported scales.
%chain <time> {
start <note>
note1 [ weight note ... ]
...
rhythm [ weight length ... ] or 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 start keyword, and then subsequent notes are chosen from the appropriate list up to a total length of time.
The rhythm 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 time to 0 or -. In this case the rhythm block is parsed in the same way as described above for %choose with time set to zero. The keyword times can be used as a synonym for rhythm.
The start keyword specifies the note to start from when using the chain. If start is omitted, the start note is chosen randomly.
Another way define the notes in a chain 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.
%eval { Perl code }
Run a block of Perl code and replace the %eval block with the value returned from the Perl code.
%eval - { 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.
%include <file>
Includes the contents of file as if they had been written at that point in the source file. Must 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: ( c e g ) 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:
%define minor { ( c e- g ) } # define minor to be a c-minor
%define major { ( c e g ) } # define major to be a c-major
%define 7th { ( c e g b- ) } # 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
~major # play a c-major
~minor/9/ # play an a-minor
~7th/5/ # play an f-7th
To make chords sound strummed, the strum keyword can be used:
$strum 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 + prepended for note on and a - 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:
+c4 /l4/r +e r +g /l2/r -c -e -g
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 %tuplet keyword:
%tuplet n:d { notes... }
plays n notes in the space of d. notes 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 not 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:
$key <name>[+|-][m]
Where name 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 $key_strict keyword instead. To get a natural note use the = sign, eg in G, f= plays an f natural. The $key_strict keyword can only be used in the @head section. The key can still be changed using the regular $key keyword.
$ctrl <num,val>
Set controller number num to val.
$rpn [num-msb,]<num-lsb,val-msb>[,val-lsb]
Set the rpn controller num to val
$nrpn [num-msb,]<num-lsb,val-msb>[,val-lsb]
Set the nrpn controller num to val
%verbatim { byteval... }
Insert a string of bytes into the midi file. Each byteval can be in either decimal (0-255) or hex (0x00-0xFF). The keyword bytes can be used instead of verbatim.
$print <text>
Print text to stdout. If text contains spaces it must be quoted using double quotes (").
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.
David Riley <dave@dmriley.demon.co.uk>
| 17 July 2006 |