Updated TODO.

[ahxm.git] / doc / ahs_overview_ii.txt

Ann Hell Scripting - II: Extended Commands
==========================================

 Angel Ortega <angel@triptico.com>

Overview
--------

Those directives that are not pure music instructions or are specific to a
given output mode are called extended commands. They are expressed as
curly bracket-enclosed blocks of keywords directly followed by their
optional, respective arguments. As for the basic commands, formatting and
indentation is free-form.

Extended commands are interleaved with basic commands, they are inserted
exactly where found and can be enclosed in blocks or group structures as
well.

Software synthesizer commands
-----------------------------

wav
~~~

 wav "file.wav" <base>
 wav "file.wav" <base> <min> <max>
 wav "file.wav" <base> <min> <max> <loop start> <loop end>
 wav "file.wav" <base> <min> <max> <loop start> <loop end> <first ch> <skip ch>

Loads a file containing a PCM wave as a layer for the current instrument.
If just the `base' note is specified, a layer will be created for that
note only. If `min' and `max' are specified, they conform the range of notes.
If `loop start' and `loop end' are not specified, the layer will be accepted
as an un-looped one (so the sound will immediately stop when reaching the end).
This non-looping behaviour can be simulated by setting a `loop start' of -1.
If `loop end' is negative, it's assumed as the end of the sample (so a loop
from 0 to -1 selects the full PCM wave for looping).

By default, all wav's channels are mapped sequentially to all channels of the
instrument, so that a mono wav file will be spread to all channels, a stereo one
to alternating odd/even channels, etc. The `first ch' and `skip ch' arguments
can be used to change this. `first ch' specify the first channel the wav will
start spreading into (default is 0, the first one), and `skip ch' is the number
of channels to skip before spreading to the next (default is 0, don't skip any
channel).

(New in 1.0.10) If the filename starts with the | (pipe) symbol, it's assumed
as a command to be executed. This command should include a %s mark where a
temporary file name will be inserted. The command should generate a wav file
in that temporary file.

Supported formats are: .wav (natively), .flac and .mp3 (via external
converters).

Examples:

 /* a simple wav with no loop and no range (just on note D1) */
 { wav "snare1.wav" d1 }
 
 /* a wav to be playing in the C3-C4 range, tuned to G4, unlooped */
 { wav "glockenspiel-g4.wav" g4 c3 c4 }
 
 /* another one, but using MIDI note numbers instead of note-octave notation */
 { wav "xilophone.wav" c5 1 127 }
 
 /* a looped one */
 { wav "pad10.wav" f4 f1 b9 150 154056 }
 
 /* another one, with a loop to fill the full wave */
 { wav "hiphop-drumline.wav" c1 c1 c1 0 -1 }
 
 /* another way of expressing the first example */
 { wav "snare1.wav" d1 d1 d1 -1 -1 }
 
 /* two looped waves for the same note, but from different wave files;
    the 'L' one will be on channels 0, 2, 4... and the 'R' one on 1, 3, 5... */
 { wav "piano1-L.wav" c2 c1 g2 150 146578 0 1 }
 { wav "piano1-R.wav" c2 c1 g2 175 143254 1 1 }
 
 /* this command will call the 'sox' program to generate a temporary
    filename (replacing the %s mark) and set it to play on C5 */
 { wav "|sox orig_file.wav %s stretch 6" c5 }

pat
~~~

 pat "file.pat"

Loads a GUS compatible sound patch. All layers defined in it will be
added to the current instrument.

sustain
~~~~~~~

 sustain <time>

Sets the sustain for subsequent notes to be the specified `time'. Sustain
is the time a digital sound will be sounding after being released.

attack
~~~~~~

 attack <time>

(New in 1.0.9). Sets the attack time for the subsequent notes to be the
specified `time'. This is the time that takes a sound to fade-in from
silence to full volume. By default, it's zero (sounds start immediately
at full volume).

vibrato
~~~~~~~

 vibrato <depth> <frequency>

Sets the vibrato for the subsequent notes.

Example:

 /* good depth values range from 0.45 to 0.68 */
 /* good frequency values are 6hz to 10hz */
 { vibrato 0.45ms 6 }

portamento
~~~~~~~~~~

 portamento <factor>

(New in 1.0.8). Sets the portamento for subsequent notes. If `factor' is
negative, the notes will slide down, or up if positive. Bigger values
generate more portamento. The final result depends on the frequency of each
note: lower notes will be more affected than higher ones for equal values
of `factor'. A `factor' of 0 disables portamento.

channel
~~~~~~~

 channel <channel #> <volume>

Sets the `volume' for the specified `channel #'. Usually it's a real number
ranging from 0 (total silence) to 1 (full volume), but any value is accepted;
numbers bigger than 1 will make the sound to be amplified (though with a
risk of saturating), and negative values will negate the amplitude of the
sound. By default, only channels 0 and 1 exist (the usual stereo ones);
setting a volume for a channel will create it automatically.

The 'vol' directive allows volumes for many channels to be specified at a time.

vol
~~~

 vol <volume>
 vol <volume> <volume>
 vol <volume> <volume> <volume>
 vol <volume> <volume> <volume> <volume>
 vol <volume> <volume> <volume> <volume> <volume> <volume>

Sets the volumes for a group of channels at a time. 1, 2, 3, 4 and 6 channels
can be specified, corresponding with the following well-known audio systems:

 * mono: all in one channel
 * stereo: left and right
 * 3 channel: left, right and center
 * quad: front left, front right, rear left and rear right
 * 4 channel: left, center, right and surround
 * 6 channel: left center, left, center, right center, right and surround

pitch_stretch
~~~~~~~~~~~~~

 pitch_stretch <note> <length> <volume>

Starts playing a special note that will last exactly `length' whole notes,
changing its pitch if necessary. The `note' is just specified to locate the
desired layer and not as a pitch. This is mainly used to match rhythm loops
(that don't have a significative pitch) to the current tempo.

Example:

 /* store three loops in the notes c1, d1 and e1 */
 { wav "loop1.wav" c1 }
 { wav "loop2.wav" d1 }
 { wav "loop3.wav" e1 }
 
 /* start loop2.wav lasting two measures */
 { pitch_stretch d1 2 0.8 }

time_stretch
~~~~~~~~~~~~

 time_stretch <note> <length> <volume>

This command is NOT IMPLEMENTED.

print_wave_tempo
~~~~~~~~~~~~~~~~

 print_wave_tempo <note> <number>

Prints the optimal tempo for the sample stored in `note' to last exactly
`number' whole notes. It does nothing to the output.


Digital effect commands
-----------------------

delay
~~~~~

 delay <channel> <time>

Creates a phase delay in `channel'. Sample output will be delayed by
the `time' specification. No further filtering is done.

Example:

 /* add a phase delay of 20 milliseconds in the right channel */
 { delay 1 20ms }

echo
~~~~

 echo <channel> <time> <gain>

Creates an echo effect in `channel'. Sample output will be pass as is,
but mixed with the original signal phased by `time' and amplified by
`gain'.

Example:

 /* add an 50% echo after 15 milliseconds */
 { echo 0 15ms 0.5 }

comb
~~~~

 comb <channel> <time> <gain>

Creates a comb filter in `channel'. Comb filters are used for implementing
reverbs.

Example:

 /* comb filter */
 { comb 0 1ms 0.4 }

allpass
~~~~~~~

 allpass <channel> <time> <gain>

Creates an allpass filter in `channel'. Allpass filters are used for
implementing reverbs (see the built-in reverb command).

Example:

 /* allpass filter */
 { allpass 0 20ms 0.9 }

flanger
~~~~~~~

 flanger <channel> <time> <gain> <depth> <freq> <phase>

Creates a flanger effect in `channel'.

Example:

 /* good stereo flanger */
 { flanger 0 1s 0.9 3.40ms 0.1 0
   flanger 1 1s 0.9 3.40ms 0.1 0.25 }

wobble
~~~~~~

 wobble <channel> <freq> <phase>
 wobble <channel> <freq> <phase> <gain>

Creates a wobble effect in `channel'. Amplitude will have a sine wave
applied with a frequency of `freq', so volume will effectively go from
full amplitude to silence twice a period. The initial value for the
phase is set in `phase'. The wobble effect can be used to implement
tremolos with short frequencies and pan effects with long ones.

If `gain' is set, it's the ratio of wobbled / unmodified signal, ranging
from 1 (full wobbled) to 0 (no effect). If not set, `gain' has a default
value of 0.8. This behaviour is new in 1.0.9; previous versions didn't
accept the 4th argument and acted as if a gain of 1.0 was given.

Examples:

 /* tremolo (10Hz frequency) */
 { wobble 0 10 0 }
 
 /* long stereo panning: one complete cycle
    in 4 seconds (0.25Hz), with a 1/4 period
    phase difference between both channels */
 { wobble 0 0.25 0
   wobble 1 0.25 0.25 }

square_wobble
~~~~~~~~~~~~~

 square_wobble <channel> <freq> <phase>

Creates a square wobble effect in `channel'. Its behaviour is the same
as the wobble command, but applying a square wave instead, so volume
will abruptly change from full amplitude to absolute silence twice a
period.

half_wobble
~~~~~~~~~~~

 half_wobble <channel> <freq> <phase>

(New in 1.0.8). Creates a half wobble effect in `channel'. Its behaviour is
the same as the wobble command, but the sine wave is applied to the
amplitude only the first half the period and silence the other half.

fader
~~~~~

 fader <channel> <time> <initial volume> <final volume>

Creates a fader effect in `channel'. `Time' is the length that will take
the channel volume to change from `initial volume' to `final volume'.
After `time' is passed, volume will be filtered to `final volume' until
the effect is destroyed.

Example:

 /* a 5 seconds fade-in in left channel */
 { fader 0 5s 0.0 1.0 }

reverb
~~~~~~

 reverb <channel>

Creates simple reverb in `channel'. This reverb is defined as

 { allpass 0 20ms 0.9
   allpass 0 36ms 0.9
   allpass 0 39ms 0.9 }

foldback
~~~~~~~~

 foldback <channel> <threshold>

(New in 1.0.8). Creates a simple distortion waveshaper where each amplitude
above `threshold' (range from -1 to 1) is folded back using the following
formula:

        if(input > threshold)
                output = threshold - (input - threshold);
        else
        if(input < -threshold)
                output = -threshold + (-threshold - input);

See http://www.musicdsp.org/archive.php?classid=4#203 for more
information.

atan
~~~~

 atan <channel> <gain>

(New in 1.0.9). Creates a simple distortion waveshaper that applies an
atan() function to each input sample. `gain' must be greater than 1.
The output from this filter is slightly distorted but a bit quieter.

See http://www.musicdsp.org/showArchiveComment.php?ArchiveID=104 for
more information.

distort
~~~~~~~

 distort <channel> <gain>

(New in 1.0.9). Creates a simple distortion waveshaper that applies a
simple formula to each input sample. `gain' must be greater than 1.

See http://www.musicdsp.org/showArchiveComment.php?ArchiveID=86 for more
information.

overdrive
~~~~~~~~~

 overdrive <channel> <gain>

(New in 1.0.9). Creates a simple distortion waveshaper that applies a
simple formula to each input sample. `gain' must be greater than 1. The
output from this filter is slightly distorted but a bit louder (it's not
a real overdrive, but for same waves it sounds similar).

See http://www.musicdsp.org/archive.php?classid=4#41 for more
information.

off
~~~

 off <channel>

This command resets the digital effect chain for `channel', destroying
all possible effects in it. Samples will then pass unmodified.

MIDI commands
-------------

midi_channel
~~~~~~~~~~~~

 midi_channel <channel #>

Sets the MIDI channel for the current track. The `channel #' value must range
from 1 to 16.

midi_program
~~~~~~~~~~~~

 midi_program <program #>

Adds a MIDI program change event. The `program #' value ranges from 0 to 127.

Miscellaneous commands
----------------------

song_info
~~~~~~~~~

 song_info "Song Author" "Song Name"

(New in 1.0.4). This directive is used to set the author and name of the song.
These metadata can be used to generate .cue files.

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