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).
187 Dynamic (random) volumes
188 ~~~~~~~~~~~~~~~~~~~~~~~~
190 (New in 1.0.10) If the volume command has two arguments separated by
191 a comma, each note will be generated with a random value from within
194 v0.2,0.8 /* next volumes will be from 0.2 to 0.8, randomly chosen */
199 Transposition is expressed as a negative or positive number of
200 semitones. By default, each track has an initial transposition
201 of 0. This is an example:
203 t5 /* transpose a fifth up */
205 Note that transpose, as octave changing, can lead to out-of-bound
206 notes. No error will be reported until an invalid note is inserted.
211 The staccato is expressed as the partial time of the total note
212 length that the note will really sound. By default, each track
213 has an initial value of 0.8 (80%). Usual values range from 0.5 (staccato)
214 to 1 (tenuto). For example:
216 s0.9 /* sets staccato to 90%: notes sound more tied together */
221 To form chords or more complicated sequences of polyphonic notes,
222 groups can be used. They are enclosed by < and > and separated
223 by semicolons. The group's duration is that of the longest of the parts.
225 The simplest example is a basic chord like this one:
227 <c1 ; e& ; g> /* a C minor chord for a whole 4/4 measure */
229 Each part of the group can contain more than one note:
231 // the classic bass drum, snare, close and open hat beat
232 <c8rrr crrr ; rrdr rrdr ; g#g#g#a# g#g#g#a#>
237 By default, each part of a group start at exactly the same time. To
238 implement strumming (as, for example, in guitar chords, where each note
239 is played slightly after the previous one), the glissando command is used,
240 with an argument expressed as a note length:
242 l16 <c;e;g> /* delay each chord note by a sixteenth */
244 Multipliers and tuplets can also be used (see the note length sections
245 for more information).
247 To disable glissando, use a glissando command with a value of 0.
252 The arpeggiator allows the programming of automatic repetitions for
253 each note, probably modifying some of its features. It's expressed
254 by the x command followed by a comma separated list of repetition
255 specifications with the following syntax:
257 offset[volume][transpose][track]
259 Offset is a length specification (see Notes) and is the delay of
260 the repetition after the start of the original note (it does NOT express
261 the length of the repeated note; each arpeggiated note last the same as
262 the original one). It can be zero for notes that sound at the same time
263 as the original note.
265 Volume, if specified, is a ~ followed by a real number (see also Notes).
266 This volume is multiplied by the original volume of the note. If none is
267 specified, the note is repeated at its original volume.
269 Transpose, if specified, is a signed number of semitones to transpose
270 the original note. If no transpose is specified, the pitch of the repeated
271 note will be the same as the original.
273 Track, if specified, is a / followed by a track offset, meaning the note
274 will be inserted that tracks after current one (and not in the current one).
276 An x command with no repetition specifications effectively disables
281 x4~0.6 // repeats each note a quarter later at 60% of vol.
282 x4~0.6,2~0.4 // the same, but another repetition later at 40%
283 x8-1,4-2,8*3-3 // 3 chromatic repetitions after each eighth
284 x8-1,4-2,8*3-3/2 // the same, last note is inserted 2 tracks after
285 x // disable arpeggiator
290 To create a mark, use
294 and, in tracks defined later, you can set the cursor at the mark by using
298 The mark name can use alphanumeric characters and hyphens. An error
299 is generated if a move to mark command is used but the current track's
300 cursor is already beyond that position (i.e. you cannot move 'backwards').
302 Marks can also be used for synchronization by using
306 if the track's cursor does not match that of the mark position, an
307 error is returned reporting the difference in measures.
312 The START mark defines the starting point of subsequent tracks. By default,
313 it's the very begining of the song. If it's defined, all next songs will
316 The END mark is an automatic one that always points to the furthest time
317 seen on a track. So, combining the START and END marks, it's possible to
318 mix different songs to play one after the other, as in
323 /* move to the furthest point */
326 /* set start of new tracks there */
336 Sometimes is useful to move back the internal 'cursor' of the song; for
337 example, when a voice starts just a note before a mark (an _anacrusa_).
338 The back command is implemented with the letter k followed by an optional
339 note length specification.
341 /* this instrument is silent until a quarter before tutti */
344 /* move back one quarter and play it */
347 /* tutti really starts here */
350 The back command can also be used to implement rudimentary chords:
352 /* a C major chord, using backs (same as <c1;e;g>) */
358 Blocks are marked using pairs of parentheses. The closing one should
359 be followed by a character indicating the operation to do with the
365 Blocks that should be repeated a defined number of times can be
370 Where code can be anything, from notes to track information, and
371 times the number of times the block will repeat.
373 Named blocks (patterns)
374 ~~~~~~~~~~~~~~~~~~~~~~~
376 A block can be assigned a name to be later inserted. To name it:
378 (code)=name-of-the-block
380 Where code can be anything, from notes to track information, and
381 name-of-the-block the name to be assigned. The name should not
382 contain spaces. The block is not inserted where it's defined; to
383 insert it, the following notation should be used:
389 (c16defgab)=scale // define a named block
390 $scale $scale $scale // insert several times
391 ($scale)*8 // blocks can be nested
393 Named blocks can be redefined anytime:
395 (($drumloop)*8)=phrase // valid even though drumloop is still undef
396 (cdcdcdcd)=drumloop $phrase // drumloop resolved when inserting phrase
397 (cdcccdcc)=drumloop $phrase // inserts now 8 copies of the new drumloop
399 Using blocks for random playing
400 -------------------------------
402 Blocks can be used to select alternatives for random playing. These alternatives
403 are defined inside a block and separated by a : (colon). This way, when inserting
404 a block, one of the subblocks will be randomly selected.
408 /* play 4 whole note chords; they can be CM, FM or GM at random */
409 z1 (<c;e;g> : <c;f;a> : <d;g;b> )*4
411 /* if you want different weights, just do it by repeating */
412 /* this way, CM will be 50%, FM 25% and GM 25% */
413 (<c;e;g> : /* CM again */ <c;e;g> : <c;f;a> : <d;g;b> )=chords1
420 (New in 1.0.8). Alterations can be implemented with the A command. The
421 argument to this command is a string specified up to seven alterations for
422 the natural notes c, d, e, f, g, a and b, where each alteration can be #
423 (sharp), & (flat) or - (natural). This command is useful to specify
428 /* plays a natural C scale (C Major) */
431 /* sets the alterations to match the C Minor mode;
432 flats on e, a and b, no change on the rest. From now on,
433 all references to those notes will be altered */
436 /* and now play a C Minor scale */
439 /* set now to G Major (notes not specified are naturals) */
443 /* set back to C Major */
449 Major and minor modes for classic tonalities are predefined as named
450 blocks and implemented as alterations. The name is formed by the uppercase
451 note, an optional modifier (# for sharp and & for flat, as always) and
452 an M or m (for Major and minor):
454 /* set tonality to C Major */
456 /* set tonality to B flat Major */
458 /* set tonality to F sharp minor */
461 Command reference table
462 -----------------------
474 r Insert rest (silence)
475 z Zero note (set length for future notes)
488 l Set glissando delay
495 * Block repetition if following )
496 = Named block assignment if following )
497 $ Named block insertion
521 Angel Ortega - http://www.triptico.com