1 Ann Hell Scripting - I: Basic Commands
2 ======================================
4 Angel Ortega <angel@triptico.com>
9 Ann Hell Ex Machina scripts consist of a sequence of commands and their
10 possible arguments which run from the top to the bottom. Formatting and
11 indentation can be used in a free-form way.
13 At any time, comments can be inserted in C language style as in the following
16 /* this is a C style comment,
20 Whitespace separation is not mandatory and commands can be conveniently
21 joined together if they are unambiguous.
25 T120 M4/4 o5 c4 d8 e& f4 g8 a&16 b& c'1
27 can also be written as
29 T120M4/4o5c4d8e&f4g8a&16b&c'1
31 or, grouped by measures,
33 T120 M4/4 o5 c4d8e& f4g8a&16b& c'1
38 Script files can be included from each other by enclosing filenames between
39 backticks, as in the example:
43 The referenced file will be inserted at that exact point.
48 Tempo is expressed in Beats Per Minute (bpm) as in the next example:
50 T120 /* sets tempo to 120 Beats Per Minute */
52 Obviously, tempo changes are global to all tracks. Though it's normally set
53 at the beginning of a song, it can be used anywhere. You can use marks to
54 be sure that tempo changes occur exactly where you want in all tracks (see
55 documentation for marks). The tempo can be a non-integer number.
60 Measure is expressed as in standard music notation. For example:
62 M4/4 /* classic 4 quarter notes measure */
64 Measure settings are global to all tracks as tempo.
78 letter[alteration][octave]
80 Letter is any from a to g for english notation notes in the currently selected
81 octave, r for rests, or z for a zero-note, that allows setting the length
82 for subsequent notes without doing anything more.
84 The alteration is optional, and is any of # (sharp) or & (flat). If not
85 specified, natural note is assumed.
87 The octave is also optional, and is one or more ocurrencies of ' (one octave
88 higher for each one) or , (one octave lower for each one). If none is
89 specified, note is assumed to belong to the current octave.
96 c' /* C, one octave above */
97 f#,, /* F sharp, two octaves below */
102 Optional, with the following syntax:
106 Figure is any of 1, 2, 4, 8, 16, 32, 64 measure partitions. Tuplet, if present,
107 is a / followed by a numeric divisor (3 for triplets, etc.). Currently, only 3
108 or 5 tuplets are supported. Mult, if present, can be expressed as an *
109 followed by a numeric multiplier of the figure meaning the final length is
110 that times longer, or as a more music-standard series of dots, adding each
113 If no length is present, the note length is inherited from the last one
118 a4 // an A longing one beat
119 r4. // a rest, longing one beat and a half
120 g8/3 // a G, in triplets of eighths
121 f1*6 // an F longing 6 complete 4/4 measures
122 r4*1.5 // same as r4.
123 z2 // sets note lengths to a half note (no note inserted)
128 Optional, can be expressed as a ~ followed by a real number ranging from
129 0 (silence) to 1 (full volume).
131 If no volume is specified, the full global one is used.
135 a4~0.8 // a quarter note of A at 80% of global volume
140 Measure marks help when writing music by asserting that measures last
141 exactly what the metric says. They are the equivalent of measure bars in
142 standard music notation and are expressed by the character |. Unlike in
143 standard music, though, they are optional. Apart from checking, these marks
144 do not modify the resulting music in any way.
146 This piece of music will trigger an error in the second mark, just before
147 the c2, because it does not fall in a measure boundary.
149 M3/4 a4 b c | c1 | c2
151 Permanent octave changes
152 ------------------------
154 Permanent octave changing can be expressed as an absolute or
155 relative change. Examples:
157 o2 /* sets octave number 2 (absolute) */
158 o+1 /* sets one octave higher (relative) */
159 o-2 /* sets two octaves lower (relative) */
161 Absolute octave numbers range from 0 to 10. Otherwise, for relative
162 changes, a signed integer number can be used.
164 A complete note trip up can be done this way, using absolute and
165 relative changes and blocks:
167 o0 z16 (cdefgab o+1)*10
169 Octaves can be out of range (the previous example will end with
170 an invalid octave number of 11), but inserting a note after it
171 will generate an error. This 'lazy error checking' is done purposely
172 to allow block repetitions like this one; just change to a valid octave
173 before inserting a new note.
175 Permanent volume changes
176 ------------------------
178 Permament volume can be expressed as an absolute or relative change.
181 v0.75 /* sets global volume to 0.75 (75%) */
182 v+0.1 /* increments current volume by 0.1 */
183 v-0.3 /* decrements current volume by 0.3 */
185 Absolute volume range from 0 (silence) to 1 (full volume).
190 Transposition is expressed as a negative or positive number of
191 semitones. By default, each track has an initial transposition
192 of 0. This is an example:
194 t5 /* transpose a fifth up */
196 Note that transpose, as octave changing, can lead to out-of-bound
197 notes. No error will be reported until an invalid note is inserted.
202 The staccato is expressed as the partial time of the total note
203 length that the note will really sound. By default, each track
204 has an initial value of 0.8 (80%). Usual values range from 0.5 (staccato)
205 to 1 (tenuto). For example:
207 s0.9 /* sets staccato to 90%: notes sound more tied together */
212 To form chords or more complicated sequences of polyphonic notes,
213 groups can be used. They are enclosed by < and > and separated
214 by semicolons. The group's duration is that of the longest of the parts.
216 The simplest example is a basic chord like this one:
218 <c1 ; e& ; g> /* a C minor chord for a whole 4/4 measure */
220 Each part of the group can contain more than one note:
222 // the classic bass drum, snare, close and open hat beat
223 <c8rrr crrr ; rrdr rrdr ; g#g#g#a# g#g#g#a#>
228 By default, each part of a group start at exactly the same time. To
229 implement strumming (as, for example, in guitar chords, where each note
230 is played slightly after the previous one), the glissando command is used,
231 with an argument expressed as a note length:
233 l16 <c;e;g> /* delay each chord note by a sixteenth */
235 Multipliers and tuplets can also be used (see the note length sections
236 for more information).
238 To disable glissando, use a glissando command with a value of 0.
243 The arpeggiator allows the programming of automatic repetitions for
244 each note, probably modifying some of its features. It's expressed
245 by the x command followed by a comma separated list of repetition
246 specifications with the following syntax:
248 offset[volume][transpose][track]
250 Offset is a length specification (see Notes) and is the delay of
251 the repetition after the start of the original note (it does NOT express
252 the length of the repeated note; each arpeggiated note last the same as
253 the original one). It can be zero for notes that sound at the same time
254 as the original note.
256 Volume, if specified, is a ~ followed by a real number (see also Notes).
257 This volume is multiplied by the original volume of the note. If none is
258 specified, the note is repeated at its original volume.
260 Transpose, if specified, is a signed number of semitones to transpose
261 the original note. If no transpose is specified, the pitch of the repeated
262 note will be the same as the original.
264 Track, if specified, is a / followed by a track offset, meaning the note
265 will be inserted that tracks after current one (and not in the current one).
267 An x command with no repetition specifications effectively disables
272 x4~0.6 // repeats each note a quarter later at 60% of vol.
273 x4~0.6,2~0.4 // the same, but another repetition later at 40%
274 x8-1,4-2,8*3-3 // 3 chromatic repetitions after each eighth
275 x8-1,4-2,8*3-3/2 // the same, last note is inserted 2 tracks after
276 x // disable arpeggiator
281 To create a mark, use
285 and, in tracks defined later, you can set the cursor at the mark by using
289 The mark name can use alphanumeric characters and hyphens. An error
290 is generated if a move to mark command is used but the current track's
291 cursor is already beyond that position (i.e. you cannot move 'backwards').
293 Marks can also be used for synchronization by using
297 if the track's cursor does not match that of the mark position, an
298 error is returned reporting the difference in measures.
303 The START mark defines the starting point of subsequent tracks. By default,
304 it's the very begining of the song. If it's defined, all next songs will
307 The END mark is an automatic one that always points to the furthest time
308 seen on a track. So, combining the START and END marks, it's possible to
309 mix different songs to play one after the other, as in
314 /* move to the furthest point */
317 /* set start of new tracks there */
327 Sometimes is useful to move back the internal 'cursor' of the song; for
328 example, when a voice starts just a note before a mark (an _anacrusa_).
329 The back command is implemented with the letter k followed by an optional
330 note length specification.
332 /* this instrument is silent until a quarter before tutti */
335 /* move back one quarter and play it */
338 /* tutti really starts here */
341 The back command can also be used to implement rudimentary chords:
343 /* a C major chord, using backs (same as <c1;e;g>) */
349 Blocks are marked using pairs of parentheses. The closing one should
350 be followed by a character indicating the operation to do with the
356 Blocks that should be repeated a defined number of times can be
361 Where code can be anything, from notes to track information, and
362 times the number of times the block will repeat.
364 Named blocks (patterns)
365 ~~~~~~~~~~~~~~~~~~~~~~~
367 A block can be assigned a name to be later inserted. To name it:
369 (code)=name-of-the-block
371 Where code can be anything, from notes to track information, and
372 name-of-the-block the name to be assigned. The name should not
373 contain spaces. The block is not inserted where it's defined; to
374 insert it, the following notation should be used:
380 (c16defgab)=scale // define a named block
381 $scale $scale $scale // insert several times
382 ($scale)*8 // blocks can be nested
384 Named blocks can be redefined anytime:
386 (($drumloop)*8)=phrase // valid even though drumloop is still undef
387 (cdcdcdcd)=drumloop $phrase // drumloop resolved when inserting phrase
388 (cdcccdcc)=drumloop $phrase // inserts now 8 copies of the new drumloop
390 Using blocks for random playing
391 -------------------------------
393 Blocks can be used to select alternatives for random playing. These alternatives
394 are defined inside a block and separated by a : (colon). This way, when inserting
395 a block, one of the subblocks will be randomly selected.
399 /* play 4 whole note chords; they can be CM, FM or GM at random */
400 z1 (<c;e;g> : <c;f;a> : <d;g;b> )*4
402 /* if you want different weights, just do it by repeating */
403 /* this way, CM will be 50%, FM 25% and GM 25% */
404 (<c;e;g> : /* CM again */ <c;e;g> : <c;f;a> : <d;g;b> )=chords1
411 (New in 1.0.8). Alterations can be implemented with the A command. The
412 argument to this command is a string specified up to seven alterations for
413 the natural notes c, d, e, f, g, a and b, where each alteration can be #
414 (sharp), & (flat) or - (natural). This command is useful to specify
419 /* plays a natural C scale (C Major) */
422 /* sets the alterations to match the C Minor mode;
423 flats on e, a and b, no change on the rest. From now on,
424 all references to those notes will be altered */
427 /* and now play a C Minor scale */
430 /* set now to G Major (notes not specified are naturals) */
434 /* set back to C Major */
440 Major and minor modes for classic tonalities are predefined as named
441 blocks and implemented as alterations. The name is formed by the uppercase
442 note, an optional modifier (# for sharp and & for flat, as always) and
443 an M or m (for Major and minor):
445 /* set tonality to C Major */
447 /* set tonality to B flat Major */
449 /* set tonality to F sharp minor */
452 Command reference table
453 -----------------------
465 r Insert rest (silence)
466 z Zero note (set length for future notes)
479 l Set glissando delay
486 * Block repetition if following )
487 = Named block assignment if following )
488 $ Named block insertion
512 Angel Ortega - http://www.triptico.com