Tonality named blocks have been documented.

[ahxm.git] / doc / ahs_overview_i.txt

Ann Hell Scripting - I: Basic Commands
======================================

 Angel Ortega <angel@triptico.com>

Overview
--------

Ann Hell Ex Machina scripts consist of a sequence of commands and their
possible arguments which run from the top to the bottom. Formatting and
indentation can be used in a free-form way.

At any time, comments can be inserted in C language style as in the following
example:

 /* this is a C style comment,
        that spans multiple
        lines */

Whitespace separation is not mandatory and commands can be conveniently
joined together if they are unambiguous.

For example:

 T120 M4/4 o5 c4 d8 e& f4 g8 a&16 b& c'1

can also be written as

 T120M4/4o5c4d8e&f4g8a&16b&c'1

or, grouped by measures,

 T120 M4/4 o5 c4d8e& f4g8a&16b& c'1

Includes
--------

Script files can be included from each other by enclosing filenames between
backticks, as in the example:

 `path/to/file`

The referenced file will be inserted at that exact point.

Tempo
-----

Tempo is expressed in Beats Per Minute (bpm) as in the next example:

 T120   /* sets tempo to 120 Beats Per Minute */

Obviously, tempo changes are global to all tracks. Though it's normally set
at the beginning of a song, it can be used anywhere. You can use marks to
be sure that tempo changes occur exactly where you want in all tracks (see
documentation for marks). The tempo can be a non-integer number.

Measure
-------

Measure is expressed as in standard music notation. For example:

 M4/4   /* classic 4 quarter notes measure */

Measure settings are global to all tracks as tempo.

Notes
-----

Syntax:

 pitch[length][volume]

pitch
~~~~~

Syntax:

 letter[alteration][octave]

Letter is any from a to g for english notation notes in the currently selected
octave, r for rests, or z for a zero-note, that allows setting the length
for subsequent notes without doing anything more.

The alteration is optional, and is any of # (sharp) or & (flat). If not
specified, natural note is assumed.

The octave is also optional, and is one or more ocurrencies of ' (one octave
higher for each one) or , (one octave lower for each one). If none is
specified, note is assumed to belong to the current octave.

Examples:

 a#     /* A sharp */
 g&     /* G flat */
 a      /* normal A */
 c'     /* C, one octave above */
 f#,,   /* F sharp, two octaves below */

length
~~~~~~

Optional, with the following syntax:

 figure[tuplet][mult]

Figure is any of 1, 2, 4, 8, 16, 32, 64 measure partitions. Tuplet, if present,
is a / followed by a numeric divisor (3 for triplets, etc.). Currently, only 3
or 5 tuplets are supported. Mult, if present, can be expressed as an *
followed by a numeric multiplier of the figure meaning the final length is
that times longer, or as a more music-standard series of dots, adding each
one half the length.

If no length is present, the note length is inherited from the last one
previously defined.

Examples:

 a4     // an A longing one beat
 r4.    // a rest, longing one beat and a half
 g8/3   // a G, in triplets of eighths
 f1*6   // an F longing 6 complete 4/4 measures
 r4*1.5 // same as r4.
 z2     // sets note lengths to a half note (no note inserted)

Immediate volume
~~~~~~~~~~~~~~~~

Optional, can be expressed as a ~ followed by a real number ranging from
0 (silence) to 1 (full volume).

If no volume is specified, the full global one is used.

Examples:

 a4~0.8 // a quarter note of A at 80% of global volume

Measure marks
-------------

Measure marks help when writing music by asserting that measures last
exactly what the metric says. They are the equivalent of measure bars in
standard music notation and are expressed by the character |. Unlike in
standard music, though, they are optional. Apart from checking, these marks
do not modify the resulting music in any way.

This piece of music will trigger an error in the second mark, just before
the c2, because it does not fall in a measure boundary.

 M3/4 a4 b c | c1 | c2

Permanent octave changes
------------------------

Permanent octave changing can be expressed as an absolute or
relative change. Examples:

 o2     /* sets octave number 2 (absolute) */
 o+1    /* sets one octave higher (relative) */
 o-2    /* sets two octaves lower (relative) */

Absolute octave numbers range from 0 to 10. Otherwise, for relative
changes, a signed integer number can be used.

A complete note trip up can be done this way, using absolute and
relative changes and blocks:

 o0 z16 (cdefgab o+1)*10

Octaves can be out of range (the previous example will end with
an invalid octave number of 11), but inserting a note after it
will generate an error. This 'lazy error checking' is done purposely
to allow block repetitions like this one; just change to a valid octave
before inserting a new note.

Permanent volume changes
------------------------

Permament volume can be expressed as an absolute or relative change.
Examples:

 v0.75  /* sets global volume to 0.75 (75%) */
 v+0.1  /* increments current volume by 0.1 */
 v-0.3  /* decrements current volume by 0.3 */

Absolute volume range from 0 (silence) to 1 (full volume).

Transpose
---------

Transposition is expressed as a negative or positive number of
semitones. By default, each track has an initial transposition
of 0. This is an example:

 t5     /* transpose a fifth up */

Note that transpose, as octave changing, can lead to out-of-bound
notes. No error will be reported until an invalid note is inserted.

Staccato
--------

The staccato is expressed as the partial time of the total note
length that the note will really sound. By default, each track
has an initial value of 0.8 (80%). Usual values range from 0.5 (staccato)
to 1 (tenuto). For example:

 s0.9   /* sets staccato to 90%: notes sound more tied together */

Groups
------

To form chords or more complicated sequences of polyphonic notes,
groups can be used. They are enclosed by < and > and separated
by semicolons. The group's duration is that of the longest of the parts.

The simplest example is a basic chord like this one:

 <c1 ; e& ; g>  /* a C minor chord for a whole 4/4 measure */

Each part of the group can contain more than one note:

 // the classic bass drum, snare, close and open hat beat
 <c8rrr crrr ; rrdr rrdr ; g#g#g#a# g#g#g#a#>

Glissando
~~~~~~~~~

By default, each part of a group start at exactly the same time. To
implement strumming (as, for example, in guitar chords, where each note
is played slightly after the previous one), the glissando command is used,
with an argument expressed as a note length:

 l16 <c;e;g> /* delay each chord note by a sixteenth */

Multipliers and tuplets can also be used (see the note length sections
for more information).

To disable glissando, use a glissando command with a value of 0.

Arpeggiator
-----------

The arpeggiator allows the programming of automatic repetitions for
each note, probably modifying some of its features. It's expressed
by the x command followed by a comma separated list of repetition
specifications with the following syntax:

 offset[volume][transpose][track]

Offset is a length specification (see Notes) and is the delay of
the repetition after the start of the original note (it does NOT express
the length of the repeated note; each arpeggiated note last the same as
the original one). It can be zero for notes that sound at the same time
as the original note.

Volume, if specified, is a ~ followed by a real number (see also Notes).
This volume is multiplied by the original volume of the note. If none is
specified, the note is repeated at its original volume.

Transpose, if specified, is a signed number of semitones to transpose
the original note. If no transpose is specified, the pitch of the repeated
note will be the same as the original.

Track, if specified, is a / followed by a track offset, meaning the note
will be inserted that tracks after current one (and not in the current one).

An x command with no repetition specifications effectively disables
the arpeggiator.

Examples:

 x4~0.6                 // repeats each note a quarter later at 60% of vol.
 x4~0.6,2~0.4           // the same, but another repetition later at 40%
 x8-1,4-2,8*3-3         // 3 chromatic repetitions after each eighth
 x8-1,4-2,8*3-3/2       // the same, last note is inserted 2 tracks after
 x                      // disable arpeggiator

Marks
-----

To create a mark, use

 ^name-of-the-mark

and, in tracks defined later, you can set the cursor at the mark by using

 @name-of-the-mark

The mark name can use alphanumeric characters and hyphens. An error
is generated if a move to mark command is used but the current track's
cursor is already beyond that position (i.e. you cannot move 'backwards').

Marks can also be used for synchronization by using

 !name-of-the-mark

if the track's cursor does not match that of the mark position, an
error is returned reporting the difference in measures.

Moving back
-----------

Sometimes is useful to move back the internal 'cursor' of the song; for
example, when a voice starts just a note before a mark (an _anacrusa_).
The back command is implemented with the letter k followed by an optional
note length specification.

 /* this instrument is silent until a quarter before tutti */
 @tutti
 
 /* move back one quarter and play it */
 k4 g
 
 /* tutti really starts here */
 c'1

The back command can also be used to implement rudimentary chords:

 /* a C major chord, using backs (same as <c1;e;g>) */
 c1kekg

Blocks
------

Blocks are marked using pairs of parentheses. The closing one should
be followed by a character indicating the operation to do with the
block.

Repeating blocks
~~~~~~~~~~~~~~~~

Blocks that should be repeated a defined number of times can be
specified as

 (code)*times

Where code can be anything, from notes to track information, and
times the number of times the block will repeat.

Named blocks (patterns)
~~~~~~~~~~~~~~~~~~~~~~~

A block can be assigned a name to be later inserted. To name it:

 (code)=name-of-the-block

Where code can be anything, from notes to track information, and
name-of-the-block the name to be assigned. The name should not
contain spaces. The block is not inserted where it's defined; to
insert it, the following notation should be used:

 $name-of-the-block

So, for example:

 (c16defgab)=scale      // define a named block
 $scale $scale $scale   // insert several times
 ($scale)*8             // blocks can be nested

Named blocks can be redefined anytime:

 (($drumloop)*8)=phrase         // valid even though drumloop is still undef
 (cdcdcdcd)=drumloop $phrase    // drumloop resolved when inserting phrase
 (cdcccdcc)=drumloop $phrase    // inserts now 8 copies of the new drumloop

Using blocks for random playing
-------------------------------

Blocks can be used to select alternatives for random playing. These alternatives
are defined inside a block and separated by a : (colon). This way, when inserting
a block, one of the subblocks will be randomly selected.

For example:

 /* play 4 whole note chords; they can be CM, FM or GM at random */
 z1 (<c;e;g> : <c;f;a> : <d;g;b> )*4
 
 /* if you want different weights, just do it by repeating */
 /* this way, CM will be 50%, FM 25% and GM 25% */
 (<c;e;g> : /* CM again */ <c;e;g> : <c;f;a> : <d;g;b> )=chords1
 
 $chords1

Alterations
-----------

(New in 1.0.8). Alterations can be implemented with the A command. The
argument to this command is a string specified up to seven alterations for
the natural notes c, d, e, f, g, a and b, where each alteration can be #
(sharp), & (flat) or - (natural). This command is useful to specify
tonalities.

For example:

 /* plays a natural C scale (C Major) */
 c8defgab c1
 
 /* sets the alterations to match the C Minor mode;
    flats on e, a and b, no change on the rest. From now on,
    all references to those notes will be altered */
 A--&--&&
 
 /* and now play a C Minor scale */
 c8defgab c1
 
 /* set now to G Major (notes not specified are naturals) */
 A---#
 g8abcdef g1
 
 /* set back to C Major */
 A

Standard tonalities
~~~~~~~~~~~~~~~~~~~

Major and minor modes for classic tonalities are predefined as named
blocks and implemented as alterations. The name is formed by the uppercase
note, an optional modifier (# for sharp and & for flat, as always) and
an M or m (for Major and minor):

 /* set tonality to C Major */
 $CM
 /* set tonality to B flat Major */
 B&M
 /* set tonality to F sharp minor */
 F#m

Command reference table
-----------------------

Note commands
~~~~~~~~~~~~~

 a      Insert note A
 b      Insert note B
 c      Insert note C
 d      Insert note D
 e      Insert note E
 f      Insert note F
 g      Insert note G
 r      Insert rest (silence)
 z      Zero note (set length for future notes)
 o      Set default octave
 t      Set transpose
 s      Set staccato
 v      Set volume
 A      Set alterations

Group commands
~~~~~~~~~~~~~~

 <      Start of group
 ;      Group delimiter
 >      End of group
 l      Set glissando delay

Block commands
~~~~~~~~~~~~~~

 (      Start of block
 )      End of block
 *      Block repetition if following )
 =      Named block assignment if following )
 $      Named block insertion
 `      Include script

Mark commands
~~~~~~~~~~~~~

 ^      Set mark
 @      Move to mark
 !      Mark assertion

Global commands
~~~~~~~~~~~~~~~

 T      Set tempo
 M      Set measure

Special commands
~~~~~~~~~~~~~~~~

 |      Measure mark
 k      Move back
 x      Arpeggiator

----
Angel Ortega - http://www.triptico.com