Un naufragio personal

Ángel Ortega

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 "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).


 /* 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 "file.pat"

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


 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 <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 <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 <depth> <frequency>

Sets the vibrato for the subsequent notes.


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


 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 #> <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 <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:

all in one channel
left and right
3 channel
left, right and center
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 <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.


 /* 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 <note> <length> <volume>

This command is NOT IMPLEMENTED.


 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 <number>

(New in 1.0.12) Sets the master volume (analogous to the -v command line switch).

Digital effect commands


 delay <channel> <time>

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


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


 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.


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


 comb <channel> <time> <gain>

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


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


 allpass <channel> <time> <gain>

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


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


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

Creates a flanger effect in channel.


 /* 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 <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.


 /* 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 <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 <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 <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.


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


 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 <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);
	if(input < -threshold)
		output = -threshold + (-threshold - input);

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


 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 <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 <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 <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 <channel #>

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


 midi_program <program #>

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

Miscellaneous commands


 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