Ann Hell Scripting - II: Extended Commands
This document describes the extended commands for the Ann Hell Scripting language. These directives are not pure music instructions or are specific to a given output mode.
Basic syntax
Extended commands 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.
sf2
sf2 "file.sf2" sf2 "file.sf2" "instrument name"
(New in 1.0.12). Lists all instrument names (first case) or loads an instrument (second case) from a SoundFont 2 (sf2) file. If an instrument name is given, all its layers 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.
master_volume
master_volume <number>
(New in 1.0.12) Sets the master volume (analogous to the -v command line switch).
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://triptico.com