Tune Language 1.1 Primer ======================== Copyright (C) 2004, 2005 J. David Sexton Not quite all rights reserved. DISCLAIMER: I do not guarantee that this document is free of errors. LICENSE: Everyone may give UNALTERED (i.e., verbatim) copies of this document to others, provided that no payment is received in return. All other rights under copyright law are jealously reserved. ====================================================================== WHAT IS THE TUNE LANGUAGE, AND WHY WAS IT INVENTED? =================================================== The Tune Language, along with the computer program TuneToMidi, provides a fairly easy and essentially free way to create MIDI files. I invented the Tune Language because I wanted to create MIDI files. The Tune Language is bit like "abc" and other languages where music can be written as text. However, it's easier to type than "abc" in a number of ways, and it allows you to do MIDI things like adjusting the volume and the location in stereo space of a musical instrument. The Tune Language is also rather like the schemes used by the many "MIDI-to- text" and "text-to-MIDI" programs around these days. The Tune Language beats these by being less "MIDIish" and easier to learn and use. The Tune Language is designed to minimize the amount of typing that must be done to create a MIDI file. It's also designed so that use of the Shift key is never required. This makes it much easier to transcribe sheet music into the Tune Language. You can create MIDI files by writing Tune files (regular ASCII text files written in the Tune Language), and then compiling the Tune files into MIDI files with TuneToMidi. TuneToMidi has a GTK graphical user interface that includes a built-in text editor, so any users who can compile TuneToMidi for GTK 2.0 will be able to do everything from that one program. Other users can compile TuneToMidi for the standard, command-line interface and use other software to edit the Tune files. The standard interface is written in C89 standard C for maximum portability. =========================================================================== HOW TO READ THIS TUNE LANGUAGE PRIMER ===================================== In order to make understanding the Tune language easier for the reader, I'm going to put some information into "tech notes" separated from the rest of the text, as in the example below. ** TECH NOTE: This is a tech note. This is where I'll write things that may be confusing at this point in the text. I'll do this in the interest of completeness, and to point out that I just simplified something--perhaps even to the point of telling you something that isn't true. I'll also be less than completely serious and business-like once in a while. ** ================================================================================= TUNE LANGUAGE BASICS ==================== I'm going to start this primer by defining some terms that I'd like to use later. ** TECH NOTE: The first term, ASCII, is rather technical, so I'll define it in a tech note. ASCII stands for "American Standard Code for Information Interchange." It's one of the older encodings still widely used. An encoding is a system of representing text in a computer. Computers only know about numbers, so text has to has to be "encoded" as numbers. In ASCII, for example, "A" is represented by the number 65. ** WORD ---- A word is any combination of the following letters and numerals: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 The following are examples of words used in the Tune Language. keysig cs4 NUMBER ------ A number is any combination of the following numerals: 0123456789 These, so-called, Arabic numerals can be preceded by a plus sign (+) or a minus sign (-). The plus sign is always optional, and the minus sign is only used for negative numbers. The following are examples of numbers. 0 -1 0048 "Leading zeros" are ignored. Also note that there can be no commas (,) or decimal points (.) as part of numbers in the Tune Language. Words and numbers in the Tune Language are separated from each other by white space. WHITE SPACE ---------- White space is any combination of spaces (what you get when you hit the space bar), tabs (what you get when you hit the Tab key), and end-of-lines (what you get when you hit the Return or Enter key). ** TECH NOTE: There is one other legal white-space character: the "form-feed" character. In the Tune Language, it counts as the end of a line, just like a return. The "form-feed" is an ASCII character that's meant to tell the printer to eject this piece of paper and start printing what follows on the top of the next page. It's a "next page" command. You probably won't be able to get one of these form-feeds into your Tune file (it's a bit tricky with the TuneToMidi built-in editor), so don't worry about it. By the way, any so-called "control" characters other than those encoded in ASCII as 9, 10, 12, and 13 are illegal in a Tune file. TuneToMidi will refuse to compile files that contain illegal control characters. See how technical TECH NOTEs can get? I warned you. While I'm being horrendously technical, I'll add that I'm aware that different operating systems use different ways of marking the end of lines in text files. TuneToMidi knows about this and tolerates all three methods. ** TEXT ---- Text always begins with a character that is not a space or tab, and ends with an end-of-line. Text can include any printable ASCII character. Specifically, it can include any combination of the following !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ [\]^_`abcdefghijklmnopqrstuvwxyz{|}~ and the space. The use of other printable characters in text is allowed, but discouraged. Some software and hardware will not be able to correctly display printable characters other than those above. Tabs should also be avoided in text because it's not clear how software and hardware should display them. Remember that text ends with the character you get by hitting the Return or Enter key. The word-wrapping that might be done by a text-editing program has nothing to do with the Tune Language. COMMAND ------- A command is the most basic unit of the Tune Language. A command is always a word (by our strict definition). ARGUMENT -------- An argument follows a command. Some commands take no arguments, some require arguments, and some can take optional arguments. Some commands (that take arguments) take just one argument, and some can take many. Arguments can be words, numbers, or text. Commands that take text as an argument take only one text argument. MIDI playing software and hardware may display this text while they play the MIDI file. CASE-INSENSITIVE ---------------- "Case-insensitive" means that it doesn't matter whether a letter is upper-case or lower-case. The Tune Language is case-insensitive when it comes to words, but not text. For example, "enddef" is a command in the Tune Language. Because all commands are words, the following are all the same command in the Tune Language. ENDDEF enddef EndDef ** TECH NOTE: The names of definitions are a special case. They can contain any printable ASCII character, but they may not contain any white space. This means that they're not quite words, by the strict definition above, and not quite text. With respect to the ASCII Latin letters (i.e., abcdefghijklmnopqrstuvwxyz), they're case-insensitive. Definition names are the first argument to the "define" command. ** TUNE FILE --------- A Tune file is an ordinary ASCII text file consisting entirely of Tune Language commands and arguments. ===================================================================================== YOUR FIRST TUNE FILE ==================== I'm going to give you an example Tune file right away, and go over all the commands in it briefly. The next section will be a hard-core reference section, but there are few concepts here, like the "track," that are essential later. Please read this through before you go on. Okay, here's your example Tune file. timesig 4 4 2 keysig cmaj tempo 125 r 12w endtrack i flute pan 64 vol 127 c4 qq c g g a a g hh f qq f e e d d c hh g qq g f f e e d hh g qq g f f e e d hh c qq c g g a a g hh f qq f e e d d c hh endtrack If you type this into a text file and compile that text file (which you now know should be called a "Tune" file) into a MIDI file, and then play the MIDI file, you'll hear the melody of an old French folk song called, "Ah! Vous dirai-je, Maman." You may recognize it as the melody of "Twinkle, Twinkle, Little Star" and the Alphabet Song. Oddly enough I'm going to begin the explanation with the last command. The last command (as you can see) is "endtrack." This command takes no arguments. The "endtrack" command ends the track. Now I just introduced a very basic concept in the Tune Language (and in MIDI): the track. A TRACK IS: a basic unit of any MIDI file, and (therefore) of any Tune file. There is no command that begins a track, but every track must end with an "endtrack" command. The purpose, basically, of having multiple tracks is to allow multiple instruments (including, perhaps, drums) to play at the same time. ** TECH NOTE: When you read the reference section, you'll find that many Tune commands and arguments have synonyms: words that (in the Tune Language) mean exactly the same thing. The two synonyms for "endtrack" are "o" and "owari." "o," of course, is short for "owari." Okay, I'll tell you. "Owari" is Japanese for "the end." You'll see it on the screen sometimes at the end of a Japanese movie (though probably not written in Latin letters). ** The first track of a Tune file (and a MIDI file) is special. It's where commands go that affect the other tracks. The first command in the example above is "timesig." "timesig" takes three arguments: 4 4 2. As you may have guessed, "timesig" means "time signature;" "timesig" commands specify the time signature. Not surprisingly, the first two arguments, 4 4, mean that the tune is in 4/4, or "common" time. The final argument, 2, says that there are two metronome clicks per measure. If you drum your fingers to the tune, you'll probably want to tap twice in each measure. ** TECH NOTE: There are three standard formats for MIDI files: 0, 1, and 2. TuneToMidi creates type 1 MIDI files. What I just wrote about the first track of a MIDI file is specifically true for format 1 MIDI files. ** The next command, "keysig," takes one argument, "cmaj." You're right, this command means that the key signature of the tune is C major. Now I'm sure you've concluded that the "tempo" command sets the tempo. The argument to this command is a number: specifically, the number of quarter notes (or crotchets) per minute. For some reason this is the tradition: to give tempo in crotchets per minute. Sometimes you'll see "beats-per-minute" when what is really meant is quarter notes per minute. These three commands, "timesig," "keysig," and "tempo," are all of the commands that really need to be in the first track of EVERY Tune file. You'll notice one more command, however, before the "endtrack." That's a rest command, just like a rest in a piece of sheet music. It may seem odd to have a rest with no notes, but every track in a Tune file, even the first (special) track, should last for the same amount of time. Actually, some MIDI-playing hardware and software can tolerate MIDI files where this is not true, but I think we have to consider it bad form. TuneToMidi gives you some extra help to get this right, so it's nothing to worry about. "r 12w" means "rest" or wait for twelve whole notes (twelve semibreves). This is the length of the tune. If you get this wrong, TuneToMidi will tell you by exactly how much it's wrong, so it's easy to get it right. Now on to the second track, which is where the music starts. The first command is "i flute." Did you guess that this says to play the flute? Well, you're right. The "i," of course, stands for "instrument." All 128 General MIDI instruments are available (and all the items in the standard MIDI drum kit, but there are other commands for the drum kit). The next command, "pan 64," is probably not obvious. The "pan" command specifies where the instrument is in stereo space. "pan 0" puts the instrument all the way to the left, "pan 127" puts the instrument all the way to the right, and "pan 64" puts it dead center. The meaning of the next command is easier to guess. "vol 127" sets the volume. Think of this as the volume control on a stereo or a guitar amp. This is not the command that specifies how hard the guitar string is plucked or how hard the piano key is struck; that's a different command you'll learn about later. "vol 127" is full volume, and "vol 0" is silence. Now we come to the heart of the Tune Language: the note. Most of the notes you type will be single letters: a, b, c, d, e, f, or g. However, when you type just "c," it has to be clear which C you mean. There is more than one C on a piano keyboard (and there are C sharps). The Tune Language has to have some way be specific and still minimize typing. Our example tune shows how this is done. The first note command is "c4 qq." The command, "c4," specifies middle C. The octave that starts with "c4" ends with "b4." C one octave above "c4" is "c5." Now you'll want to know what the argument "qq" means. That's one of the ways (and my favorite way) to specify a quarter note (or crotchet). Now that we've specified the octave and length of the first note, we can take it easy. The next note command after "c4 qq" is just "c." What octave? What length? Well, it's not specified, so it's the same as the previous note. The same holds true for "g g a a." The last note command on that first line is "g hh." The octave isn't specified, so it's still 4, but the length is different. "hh" means "half note" (or "minim"). The first note command on the next line is "f qq," so we're still in octave 4, but the length is back to quarter note. By the way, it doesn't matter where any of the lines in this example begin and end. I ended lines where I did because the file looks better to me this way. ** TECH NOTE: You might be thinking, "Hey, why do I have to type two h's and two q's? Why not just one?" Well, that would be problem when we get to "e" for "eighth" and "s" for "sixteenth." "e" and "s" are used for commands; "e" is a note command (it's the E), and "s" is a "stress" command. Besides, typing the same letter twice is only slightly more work than typing it once; hunt-and-peck typists spend most of their typing time hunting. ** The only other commands before the final "endtrack" are more note commands, so this is the end of my explanation. Now, just for the fun of it, I'm going to show you a few tricks. Here's another way to type the example tune. timesig 4 4 2 keysig cmaj tempo 125 repeat 6 r qq r r r r r r hh endrep endtrack i flute pan 64 vol 127 c4 qq c g g a a g hh f qq f e e d d c hh repeat 2 g qq g f f e e d hh endrep c qq c g g a a g hh f qq f e e d d c hh endtrack The MIDI file created from both versions of the example is the same, even though the Tune files are different. The difference is the repeat loops. It's probably intuitively obvious to you what repeat loops do: they repeat. The first repeat loop demonstrates an easier way to get the length (the playing time) of the first track the same as the second. Every line of the tune consists of two measures, with four quarter notes in the first measure, and two quarter notes followed by a half note in the second measure. So that's six quarter note rests followed by a half note rest, repeated 6 times--easy. You'll have noticed that rests follow one of the same rules as notes: if the length isn't specified, it's the same as the note, chord or rest before. ** TECH NOTE: The chord command will be discussed in the reference section. The octave and note value (or length) resets at the beginning of each track. The value defaults back to quarter note (or crotchet), and the octave defaults back to 4. This means that we could have begun the tune with just "c" instead of "c4 qq." ** The line "g qq g f f e e d hh" is repeated twice, so we just write "repeat 2," meaning "repeat twice." The "endrep" argument is needed to show where the repeated part stops. Here's yet another way to write the tune. timesig 4 4 2 keysig cmaj tempo 125 repeat 6 r qq r r r r r r hh endrep endtrack i flute pan 64 vol 127 usedef firstpart repeat 2 g4 qq g f f e e d hh endrep usedef firstpart endtrack define firstpart c4 qq c g g a a g hh f qq f e e d d c hh enddef The first part is repeated exactly at the end, so I just defined it as "firstpart" and used the definition twice. Don't worry that I haven't given you all the rules about repeat loops and definitions yet. That will come later in this primer. For now just get the idea that the Tune Language is flexible and designed to make things easy. Here's the tune in D major. timesig 4 4 2 keysig dmaj tempo 125 repeat 6 r qq r r r r r r hh endrep endtrack i flute pan 64 vol 127 auto dmaj usedef firstpart repeat 2 a4 qq a g g f f e hh endrep usedef firstpart endtrack define firstpart d4 qq d a a b b a hh g qq g f f e e d hh enddef This example uses the "auto" command, which automatically converts notes to flat or sharp to keep them "in key." The "auto dmaj" command converts all the C's to C sharps, and all the F's to F sharps. This is just one more way that the Tune Language is designed to minimize typing. In the reference section you'll find out more about the "auto" command and how to specify accidentals. Also check out the "transpose" command. I told you earlier that the basic reason for multiple tracks is to allow multiple instruments to play at the same time. Here's a small demonstration. Here's our tune as a flute and harp duet. timesig 4 4 2 keysig cmaj tempo 125 repeat 6 r qq r r r r r r hh endrep endtrack i flute pan 48 vol 127 usedef fpA repeat 2 g4 qq g f f e e d hh endrep usedef fpA endtrack i harp pan 96 vol 127 usedef fpB repeat 2 g4 qq g f f e ee f g e d qq g endrep usedef fpB endtrack define fpA c4 qq c g g a a g hh f qq f e e d d c hh enddef define fpB c4 qq c g g a ee b c5 a4 g qq e f qq f e e d ee e f d c hh enddef As you've no doubt guessed, "ee" means "eighth note" (or "quaver"). You'll notice that I've also added some extra white-space to make the tune easier for me to read. ============================================================================== REFERENCE SECTION ================= MIDI ---- MIDI stands for "Musical Instrument Digital Interface." MIDI sets standards for MIDI files that are strictly adhered to by the MIDI files created by TuneToMidi when it creates MIDI files from Tune files. All the MIDI files created by TuneToMidi are format 1 MIDI files. Some of the rules imposed by on the Tune Language by MIDI standards are discussed later in this primer. TRACKS ------ Every Tune file must have at least two tracks. Each track must end with an "endtrack" command (or one of its synonyms). There are some commands which may only appear in the first track, others that may never appear in the first track, and still others that may appear in any track. The "i" (instrument) command may appear in up to fifteen different tracks in the same Tune file (but not in the first track). ** TECH NOTE: In the world of MIDI there is an important concept called a "channel." MIDI uses four bits to indicate the channel, so there can be only 16 (two to the fourth power) channels. There's a special channel reserved just for the drum kit, so that leaves fifteen other channels. The Tune Language keeps the channel issue simple by following a one-track-one-channel rule. This is where the "fifteen" limit comes from. Some MIDI hardware and software support "banks" of channels, but not all. Using banks would create a compatibility risk. Channels are very important to people who have to use complicated software and hardware to create MIDI files. They have to know what a channel really is, but you don't. TuneToMidi takes care of channels for you. Don't worry about it. ** At the beginning of each track, the octave defaults to 4, the note length (or value) defaults to quarter note (crotchet), the stress defaults to mezzoforte (64), and the the "auto" command defaults to C major (in other words the "auto" command is off, and notes are not automatically flattened or sharpened). CASE ---- The Tune language is case-insensitive for everything but the arguments of text commands. This becomes important in choosing names for definitions; names that differ in case only are the same name. NOTES ----- Notes can be commands, or they can be arguments to other commands (the "chord," "noteon," and "noteoff" commands). The format and meaning of notes is the same in both cases. A note can have up to three parts. Each part is one character (a letter or numeral). For example, cs4 has all three parts. The first part is "c," the second part is "s," and the third is "4." The first part is the only required part. It must be one of the following letters: a b c d e f g These letters are used by English speakers to name the seven notes of a standard scale. In the Tune language, an octave begins with C. The second part of the note is optional. It must be one of the following letters: f n s The "f" means "flat," the "s" means "sharp," and the "n" means "natural." If the second part is missing, the note is natural; therefore, "n" is rarely used, except to override the "auto" command. Including and "f," "s," or "n" as the second part of a note always overrides the "auto" command. This is how we indicate accidentals. The "auto" command, documented later in this primer, causes notes missing the second part to be "understood" as in-key for the key set by the "auto" command. For example, if D major is set by the auto command, a "c" will be seen as a "cs," and an "f" will be seen as an "fs." However, an "fn" will always be natural. The third, optional, part of a note specifies the octave. It must be one of the following numerals. 0 1 2 3 4 5 6 7 8 9 If the third part of the note is missing, the octave of the note is the same as that of the previous note. If there is no previous note in the same track, the default octave is 4. Middle C is "c4." C one octave above middle C is "c5," and the note just below "c5" is "b4." Each octave begins with C natural. There is actually a -1 octave. This can be reached in the Tune Language with the "transpose" command, documented later in this primer. It should also be noted that octave 9 is incomplete; there is no note higher than G natural in the ninth octave. ** TECH NOTE: That makes ten (-1 through 8) octaves with twelve half-tones in each, plus eight half-tones in the incomplete octave nine, for a grand total of 128 possible tones. Why 128? It's because 128 happens to be a power of 2. In the world of digital electronics, 2 is much more important than 10. ** NOTE COMMANDS ------------- Note commands may not appear in the first track. They also may not appear in a track before the first "i" (instrument) command, or in a place where a drum beat would be appropriate (see the sections below about the "drum," "nodrum," "redrum, " and drum beat commands). Note commands consist of a note (as described above) followed, optionally, by one argument. The argument is the length, or value, of the note. There are a few different ways to write this argument. These are listed in the table below. ** TECH NOTE: The "Dave form" is the form I happen to prefer. ** Dave form long forms other forms number meaning --------- ---------- ----------- ------ ----------------------- ww ....... semibreve ....... 1w ........... 384 .. whole note or semibreve whole vs1 v1 hh ....... minim ........... v2 ........... 192 .. half note or minim half qq ....... crotchet ........ v4 ............ 96 .. quarter note or crotchet quarter ee ....... quaver .......... v8 ............ 48 .. eighth note or quaver eighth ss ....... semiquaver ...... v16 ........... 24 .. sixteenth note or semiquaver sixteenth tt ....... demisemiquaver .. v32 ........... 12 .. thirty-second note or thirtysecond demisemiquaver www ........................ wwd .......... 576 .. dotted whole note or vd1 dotted semibreve hhh ........................ hhd .......... 288 .. dotted half note or vd2 dotted minim qqq ........................ qqd .......... 144 .. dotted quarter note or vd4 dotted crotchet eee ........................ eed ........... 72 .. dotted eighth note or vd8 dotted quaver sss ........................ ssd ........... 36 .. dotted sixteenth note or vd16 dotted semiquaver ttt ........................ ttd ........... 18 .. dotted thirty-second note or vd32 dotted demisemiquaver hh3 ........................ vt2 .......... 128 .. two thirds of a half note; used for half-note triplets qq3 ........................ vt4 ........... 64 .. two thirds of a quarter note; used for quarter-note triplets ee3 ........................ vt8 ........... 32 .. two thirds of an eighth note; used for eighth-note triplets ss3 ........................ vt16 .......... 16 .. two thirds of a sixteenth note; used for sixteenth-note triplets tt3 ........................ vt32 ........... 8 .. two thirds of a thirty-second note; used for thirty-second-note triplets 2w ......................... vs2 .......... 768 .. two whole notes or semibreves 3w ......................... vs3 ......... 1152 .. three whole notes or semibreves 4w ......................... vs4 ......... 1536 .. four whole notes or semibreves 6w ......................... vs6 ......... 2304 .. six whole notes or semibreves 8w ......................... vs8 ......... 3072 .. eight whole notes or semibreves 12w ........................ vs12 ........ 4608 .. twelve whole notes or semibreves 16w ........................ vs16 ........ 6144 .. sixteen whole notes or semibreves 24w ........................ vs24 ........ 9216 .. twenty-four whole notes or semibreves 32w ........................ vs32 ....... 12288 .. thirty-two whole notes or semibreves 36w ........................ vs36 ....... 13824 .. thirty-six whole notes or semibreves 48w ........................ vs48 ....... 18432 .. forty-eight whole notes or semibreves 64w ........................ vs64 ....... 24576 .. sixty-four whole notes or semibreves The argument to the note command is optional. If it's omitted, the length (or value) of the note is the same as the note, chord or rest before. As an example, here are two measures from "Ah! Vous dirai-je, Maman." c4 qq c g g a a g hh The optional length (or value) argument is used only for the first and last notes. The length of the second C is quarter-note (or crotchet) because no length argument appears, and the length of the note before is quarter-note. The final G is a half note (or minim) because the "hh" argument explicitly specifies that it is. Notice that the octave of the first note is explicitly specified; it's 4. The octave of all the other notes is, implicitly, the same as that of the first note because no other octave is explicitly specified. Notice, also, that all the notes are implicitly natural because no "f" or "s" appears to explicitly specify otherwise. An "auto" command, discussed below, might also implicitly specify flat or sharp, but no such command appears in the example. You can always use numbers for the length argument--even numbers you don't see in the table above. If a number is used, it cannot be less than 1 or greater than 268435455. Here's the example line above with numbers. c4 96 c g g a a g 192 You'll notice as you study the table that there are three parallel systems: numbers, the "whqest" system, and the "v" system. The "v" in the "v" system stands for "value." When the "v" is followed by a "d," the "d" stands for "dotted." When it's followed by a "t," the "t" is for "triplet." Finally, when it's followed by an "s," the "s" stands for "semibreve." The numbers after the "s" are the numbers of semibreves, and the other numbers (1, 2, 4, 8, 16, and 32) stand for whole note, half note, quarter note, etc. In the "whqest" system, the letters w, h, q, e, s, and t stand for "whole," "half," "quarter," "eighth," "sixteenth," and "thirty-second," respectively. Because "qq" stands for "quarter note," it's logical that "qqq," which is half again as long, stands for "dotted quarter note." If that's not appealing, "qqd," with a "d" for "dotted," is a reasonable alternative. The "whqest" system doesn't have "t" free to indicate triplets, so it uses "3." Numbers were the original system. In the early days, back in 2003, I used my calculator quite a bit when I wrote Tune files. This is still an option. Sometimes it's useful for tricky little runs and trills. CHORD COMMANDS -------------- Chord commands may not appear in the first track. They also may not appear in a track before the first "i" (instrument) command, or in a place where a drum beat would be appropriate (see the sections below about the "drum," "nodrum," "redrum, " and drum beat commands). The chord command begins with "chord" (or the synonym, "ch"), and ends with a length (or value) argument just like the ones used for note commands, discussed in detail above. In between there must be at least one note. The notes are specified as detailed above in the section "NOTES." There is only one length for the chord, and it's specified by the length at the end. Here's an example. chord c4 g c5 qq The length (or value) of the chord is quarter-note, and the chord consists of three notes. The G in this chord is in the same octave as the note before; i.e., it's g4 (the G above middle C). The notes of a chord don't have to be specified in any special order, but the order may affect which notes are actually specified, as it does in the example above. Here are a few more examples to illustrate the point. chord c4 g c5 qq is the same as chord c4 g4 c5 qq However, chord c5 g c4 qq is the same as chord c5 g5 c4 qq I like to specify notes in ascending order, but I don't have to. chord c5 g4 c4 qq plays exactly the same chord as chord c4 g4 c5 qq Note that the "chord" command plays vertical chords, chords in which all the notes of the chord begin and end at the same time. Note, also, that the length (or value) of the chord is the default for the next note or rest command (just as with note commands), and that the octave of the last note in the chord is the default octave for the next note or chord command (again, just as with note commands). The length (or value) of a chord is always explicitly specified because it's what marks the end of the chord command. A chord can consist of up to 128 notes. That would be every key on our (virtual) MIDI keyboard pressed and released together. Of course, no note may appear twice in the same chord command. REST COMMANDS ------------- The rest command may appear in any track, including the first track. With certain exceptions in the first track, it may also appear at any point in the track. The rest command begins with the word "rest" (or one of its synonyms: "r," or "wait"), which may be followed by one optional argument. The optional argument is the length of the rest, specified exactly as it would be for a note or chord command. See the detailed discussion above in the section titled "NOTE COMMANDS." If the length is not specified, it the same as the last note, chord, or rest command that precedes it. Rest commands can follow other rest commands. For example, the following two lines are equivalent in length. r qq r r hh The only difference is that the default length of the next note, rest, or chord command will be quarter-note after the first line, and half-note after the second. NOTEON AND NOTEOFF COMMANDS --------------------------- Noteon and noteoff commands may not appear in the first track. They also may not appear in a track before the first "i" (instrument) command, or in a place where a drum beat would be appropriate (see the sections below about the "drum," "nodrum," "redrum, " and drum beat commands). A noteon command begins with a "noteon" followed by one required argument. This argument is a note (not a note command, just a note). The note is specified as detailed above in the section "NOTES." Here's an example noteon command. noteon c4 Note that no length is specified. The noteon command starts a note playing, but it doesn't stop it. The playing of the note is stopped by a noteoff command with the same or an equivalent argument. For example, noteon c4 r qq noteoff c is the same as c4 qq The rest command waits for the length of a quarter note (or crotchet), and the noteoff command stops the note. Note that the octave of the C argument in the noteoff command above is implicitly 4, the same as the note before. It may not be obvious, at first glance, why the noteon and noteoff commands even exist. In the example above, the note command is much simpler to use and understand. However, there are uses for noteon and noteoff commands. One use is to change the volume during a note. Here's an example. vol 32 noteon c4 r qq vol 64 r qq vol 96 r qq vol 127 r qq noteoff c The total length of the note is whole-note (or semibreve), and the volume increases as the note plays. Nonvertical chords are another use for noteon and noteoff. Here's a nonvertical chord. noteon c5 r ee noteon g4 r ee noteon c r hhh noteoff c5 noteoff g4 noteoff c The whole chord lasts for the length of a whole note (or semibreve), but the three notes don't all begin at the same time. ***************************************************************** As you can see, the Primer isn't finished yet. I'll continue to write more as I manage to scrounge more time.