1 Ann Hell Scripting - II: Extended Commands
2 ==========================================
4 This document describes the extended commands for the Ann Hell Scripting
5 language. These directives are not pure music instructions or are
6 specific to a given output mode.
11 Extended commands are expressed as curly bracket-enclosed blocks of
12 keywords directly followed by their optional, respective arguments. As
13 for the basic commands, formatting and indentation is free-form.
15 Extended commands are interleaved with basic commands, they are inserted
16 exactly where found and can be enclosed in blocks or group structures as
19 Software synthesizer commands
20 -----------------------------
26 wav "file.wav" <base> <min> <max>
27 wav "file.wav" <base> <min> <max> <loop start> <loop end>
28 wav "file.wav" <base> <min> <max> <loop start> <loop end> <first ch> <skip ch>
30 Loads a file containing a PCM wave as a layer for the current instrument.
31 If just the `base' note is specified, a layer will be created for that
32 note only. If `min' and `max' are specified, they conform the range of notes.
33 If `loop start' and `loop end' are not specified, the layer will be accepted
34 as an un-looped one (so the sound will immediately stop when reaching the end).
35 This non-looping behaviour can be simulated by setting a `loop start' of -1.
36 If `loop end' is negative, it's assumed as the end of the sample (so a loop
37 from 0 to -1 selects the full PCM wave for looping).
39 By default, all wav's channels are mapped sequentially to all channels of the
40 instrument, so that a mono wav file will be spread to all channels, a stereo one
41 to alternating odd/even channels, etc. The `first ch' and `skip ch' arguments
42 can be used to change this. `first ch' specify the first channel the wav will
43 start spreading into (default is 0, the first one), and `skip ch' is the number
44 of channels to skip before spreading to the next (default is 0, don't skip any
47 (New in 1.0.10) If the filename starts with the | (pipe) symbol, it's assumed
48 as a command to be executed. This command should include a %s mark where a
49 temporary file name will be inserted. The command should generate a wav file
50 in that temporary file.
52 Supported formats are: .wav (natively), .flac and .mp3 (via external
57 /* a simple wav with no loop and no range (just on note D1) */
58 { wav "snare1.wav" d1 }
60 /* a wav to be playing in the C3-C4 range, tuned to G4, unlooped */
61 { wav "glockenspiel-g4.wav" g4 c3 c4 }
63 /* another one, but using MIDI note numbers instead of note-octave notation */
64 { wav "xilophone.wav" c5 1 127 }
67 { wav "pad10.wav" f4 f1 b9 150 154056 }
69 /* another one, with a loop to fill the full wave */
70 { wav "hiphop-drumline.wav" c1 c1 c1 0 -1 }
72 /* another way of expressing the first example */
73 { wav "snare1.wav" d1 d1 d1 -1 -1 }
75 /* two looped waves for the same note, but from different wave files;
76 the 'L' one will be on channels 0, 2, 4... and the 'R' one on 1, 3, 5... */
77 { wav "piano1-L.wav" c2 c1 g2 150 146578 0 1 }
78 { wav "piano1-R.wav" c2 c1 g2 175 143254 1 1 }
80 /* this command will call the 'sox' program to generate a temporary
81 filename (replacing the %s mark) and set it to play on C5 */
82 { wav "|sox orig_file.wav %s stretch 6" c5 }
89 Loads a GUS compatible sound patch. All layers defined in it will be
90 added to the current instrument.
96 sf2 "file.sf2" "instrument name"
98 (New in 1.0.12). Lists all instrument names (first case) or loads an
99 instrument (second case) from a SoundFont 2 (sf2) file. If an instrument
100 name is given, all its layers will be added to the current instrument.
107 Sets the sustain for subsequent notes to be the specified `time'. Sustain
108 is the time a digital sound will be sounding after being released.
115 (New in 1.0.9). Sets the attack time for the subsequent notes to be the
116 specified `time'. This is the time that takes a sound to fade-in from
117 silence to full volume. By default, it's zero (sounds start immediately
123 vibrato <depth> <frequency>
125 Sets the vibrato for the subsequent notes.
129 /* good depth values range from 0.45 to 0.68 */
130 /* good frequency values are 6hz to 10hz */
138 (New in 1.0.8). Sets the portamento for subsequent notes. If `factor' is
139 negative, the notes will slide down, or up if positive. Bigger values
140 generate more portamento. The final result depends on the frequency of each
141 note: lower notes will be more affected than higher ones for equal values
142 of `factor'. A `factor' of 0 disables portamento.
147 channel <channel #> <volume>
149 Sets the `volume' for the specified `channel #'. Usually it's a real number
150 ranging from 0 (total silence) to 1 (full volume), but any value is accepted;
151 numbers bigger than 1 will make the sound to be amplified (though with a
152 risk of saturating), and negative values will negate the amplitude of the
153 sound. By default, only channels 0 and 1 exist (the usual stereo ones);
154 setting a volume for a channel will create it automatically.
156 The 'vol' directive allows volumes for many channels to be specified at a time.
162 vol <volume> <volume>
163 vol <volume> <volume> <volume>
164 vol <volume> <volume> <volume> <volume>
165 vol <volume> <volume> <volume> <volume> <volume> <volume>
167 Sets the volumes for a group of channels at a time. 1, 2, 3, 4 and 6 channels
168 can be specified, corresponding with the following well-known audio systems:
170 * mono: all in one channel
171 * stereo: left and right
172 * 3 channel: left, right and center
173 * quad: front left, front right, rear left and rear right
174 * 4 channel: left, center, right and surround
175 * 6 channel: left center, left, center, right center, right and surround
180 pitch_stretch <note> <length> <volume>
182 Starts playing a special note that will last exactly `length' whole notes,
183 changing its pitch if necessary. The `note' is just specified to locate the
184 desired layer and not as a pitch. This is mainly used to match rhythm loops
185 (that don't have a significative pitch) to the current tempo.
189 /* store three loops in the notes c1, d1 and e1 */
190 { wav "loop1.wav" c1 }
191 { wav "loop2.wav" d1 }
192 { wav "loop3.wav" e1 }
194 /* start loop2.wav lasting two measures */
195 { pitch_stretch d1 2 0.8 }
200 time_stretch <note> <length> <volume>
202 This command is NOT IMPLEMENTED.
207 print_wave_tempo <note> <number>
209 Prints the optimal tempo for the sample stored in `note' to last exactly
210 `number' whole notes. It does nothing to the output.
215 master_volume <number>
217 (New in 1.0.12) Sets the master volume (analogous to the -v command line switch).
219 Digital effect commands
220 -----------------------
225 delay <channel> <time>
227 Creates a phase delay in `channel'. Sample output will be delayed by
228 the `time' specification. No further filtering is done.
232 /* add a phase delay of 20 milliseconds in the right channel */
238 echo <channel> <time> <gain>
240 Creates an echo effect in `channel'. Sample output will be pass as is,
241 but mixed with the original signal phased by `time' and amplified by
246 /* add an 50% echo after 15 milliseconds */
252 comb <channel> <time> <gain>
254 Creates a comb filter in `channel'. Comb filters are used for implementing
265 allpass <channel> <time> <gain>
267 Creates an allpass filter in `channel'. Allpass filters are used for
268 implementing reverbs (see the built-in reverb command).
273 { allpass 0 20ms 0.9 }
278 flanger <channel> <time> <gain> <depth> <freq> <phase>
280 Creates a flanger effect in `channel'.
284 /* good stereo flanger */
285 { flanger 0 1s 0.9 3.40ms 0.1 0
286 flanger 1 1s 0.9 3.40ms 0.1 0.25 }
291 wobble <channel> <freq> <phase>
292 wobble <channel> <freq> <phase> <gain>
294 Creates a wobble effect in `channel'. Amplitude will have a sine wave
295 applied with a frequency of `freq', so volume will effectively go from
296 full amplitude to silence twice a period. The initial value for the
297 phase is set in `phase'. The wobble effect can be used to implement
298 tremolos with short frequencies and pan effects with long ones.
300 If `gain' is set, it's the ratio of wobbled / unmodified signal, ranging
301 from 1 (full wobbled) to 0 (no effect). If not set, `gain' has a default
302 value of 0.8. This behaviour is new in 1.0.9; previous versions didn't
303 accept the 4th argument and acted as if a gain of 1.0 was given.
307 /* tremolo (10Hz frequency) */
310 /* long stereo panning: one complete cycle
311 in 4 seconds (0.25Hz), with a 1/4 period
312 phase difference between both channels */
319 square_wobble <channel> <freq> <phase>
321 Creates a square wobble effect in `channel'. Its behaviour is the same
322 as the wobble command, but applying a square wave instead, so volume
323 will abruptly change from full amplitude to absolute silence twice a
329 half_wobble <channel> <freq> <phase>
331 (New in 1.0.8). Creates a half wobble effect in `channel'. Its behaviour is
332 the same as the wobble command, but the sine wave is applied to the
333 amplitude only the first half the period and silence the other half.
338 fader <channel> <time> <initial volume> <final volume>
340 Creates a fader effect in `channel'. `Time' is the length that will take
341 the channel volume to change from `initial volume' to `final volume'.
342 After `time' is passed, volume will be filtered to `final volume' until
343 the effect is destroyed.
347 /* a 5 seconds fade-in in left channel */
348 { fader 0 5s 0.0 1.0 }
355 Creates simple reverb in `channel'. This reverb is defined as
364 foldback <channel> <threshold>
366 (New in 1.0.8). Creates a simple distortion waveshaper where each amplitude
367 above `threshold' (range from -1 to 1) is folded back using the following
370 if(input > threshold)
371 output = threshold - (input - threshold);
373 if(input < -threshold)
374 output = -threshold + (-threshold - input);
376 See http://www.musicdsp.org/archive.php?classid=4#203 for more
382 atan <channel> <gain>
384 (New in 1.0.9). Creates a simple distortion waveshaper that applies an
385 atan() function to each input sample. `gain' must be greater than 1.
386 The output from this filter is slightly distorted but a bit quieter.
388 See http://www.musicdsp.org/showArchiveComment.php?ArchiveID=104 for
394 distort <channel> <gain>
396 (New in 1.0.9). Creates a simple distortion waveshaper that applies a
397 simple formula to each input sample. `gain' must be greater than 1.
399 See http://www.musicdsp.org/showArchiveComment.php?ArchiveID=86 for more
405 overdrive <channel> <gain>
407 (New in 1.0.9). Creates a simple distortion waveshaper that applies a
408 simple formula to each input sample. `gain' must be greater than 1. The
409 output from this filter is slightly distorted but a bit louder (it's not
410 a real overdrive, but for same waves it sounds similar).
412 See http://www.musicdsp.org/archive.php?classid=4#41 for more
420 This command resets the digital effect chain for `channel', destroying
421 all possible effects in it. Samples will then pass unmodified.
429 midi_channel <channel #>
431 Sets the MIDI channel for the current track. The `channel #' value must range
437 midi_program <program #>
439 Adds a MIDI program change event. The `program #' value ranges from 0 to 127.
441 Miscellaneous commands
442 ----------------------
447 song_info "Song Author" "Song Name"
449 (New in 1.0.4). This directive is used to set the author and name of the song.
450 These metadata can be used to generate .cue files.
453 Angel Ortega - http://triptico.com