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

 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