1 Ann Hell Scripting - II: Extended Commands
2 ==========================================
4 Those directives that are not pure music instructions or are specific to a
5 given output mode are called extended commands. They are expressed as
6 curly bracket-enclosed blocks of keywords directly followed by their
7 optional, respective arguments. As for the basic commands, formatting and
8 indentation is free-form.
10 Extended commands are interleaved with basic commands, they are inserted
11 exactly where found and can be enclosed in blocks or group structures as
14 Software synthesizer commands
15 -----------------------------
21 wav "file.wav" <base> <min> <max>
22 wav "file.wav" <base> <min> <max> <loop start> <loop end>
23 wav "file.wav" <base> <min> <max> <loop start> <loop end> <first ch> <skip ch>
25 Loads a file containing a PCM wave as a layer for the current instrument.
26 If just the `base' note is specified, a layer will be created for that
27 note only. If `min' and `max' are specified, they conform the range of notes.
28 If `loop start' and `loop end' are not specified, the layer will be accepted
29 as an un-looped one (so the sound will immediately stop when reaching the end).
30 This non-looping behaviour can be simulated by setting a `loop start' of -1.
31 If `loop end' is negative, it's assumed as the end of the sample (so a loop
32 from 0 to -1 selects the full PCM wave for looping).
34 By default, all wav's channels are mapped sequentially to all channels of the
35 instrument, so that a mono wav file will be spread to all channels, a stereo one
36 to alternating odd/even channels, etc. The `first ch' and `skip ch' arguments
37 can be used to change this. `first ch' specify the first channel the wav will
38 start spreading into (default is 0, the first one), and `skip ch' is the number
39 of channels to skip before spreading to the next (default is 0, don't skip any
42 (New in 1.0.10) If the filename starts with the | (pipe) symbol, it's assumed
43 as a command to be executed. This command should include a %s mark where a
44 temporary file name will be inserted. The command should generate a wav file
45 in that temporary file.
47 Supported formats are: .wav (natively), .flac and .mp3 (via external
52 /* a simple wav with no loop and no range (just on note D1) */
53 { wav "snare1.wav" d1 }
55 /* a wav to be playing in the C3-C4 range, tuned to G4, unlooped */
56 { wav "glockenspiel-g4.wav" g4 c3 c4 }
58 /* another one, but using MIDI note numbers instead of note-octave notation */
59 { wav "xilophone.wav" c5 1 127 }
62 { wav "pad10.wav" f4 f1 b9 150 154056 }
64 /* another one, with a loop to fill the full wave */
65 { wav "hiphop-drumline.wav" c1 c1 c1 0 -1 }
67 /* another way of expressing the first example */
68 { wav "snare1.wav" d1 d1 d1 -1 -1 }
70 /* two looped waves for the same note, but from different wave files;
71 the 'L' one will be on channels 0, 2, 4... and the 'R' one on 1, 3, 5... */
72 { wav "piano1-L.wav" c2 c1 g2 150 146578 0 1 }
73 { wav "piano1-R.wav" c2 c1 g2 175 143254 1 1 }
75 /* this command will call the 'sox' program to generate a temporary
76 filename (replacing the %s mark) and set it to play on C5 */
77 { wav "|sox orig_file.wav %s stretch 6" c5 }
84 Loads a GUS compatible sound patch. All layers defined in it will be
85 added to the current instrument.
91 sf2 "file.sf2" "instrument name"
93 (New in 1.0.12). Lists all instrument names (first case) or loads an
94 instrument (second case) from a SoundFont 2 (sf2) file. If an instrument
95 name is given, all its layers will be added to the current instrument.
102 Sets the sustain for subsequent notes to be the specified `time'. Sustain
103 is the time a digital sound will be sounding after being released.
110 (New in 1.0.9). Sets the attack time for the subsequent notes to be the
111 specified `time'. This is the time that takes a sound to fade-in from
112 silence to full volume. By default, it's zero (sounds start immediately
118 vibrato <depth> <frequency>
120 Sets the vibrato for the subsequent notes.
124 /* good depth values range from 0.45 to 0.68 */
125 /* good frequency values are 6hz to 10hz */
133 (New in 1.0.8). Sets the portamento for subsequent notes. If `factor' is
134 negative, the notes will slide down, or up if positive. Bigger values
135 generate more portamento. The final result depends on the frequency of each
136 note: lower notes will be more affected than higher ones for equal values
137 of `factor'. A `factor' of 0 disables portamento.
142 channel <channel #> <volume>
144 Sets the `volume' for the specified `channel #'. Usually it's a real number
145 ranging from 0 (total silence) to 1 (full volume), but any value is accepted;
146 numbers bigger than 1 will make the sound to be amplified (though with a
147 risk of saturating), and negative values will negate the amplitude of the
148 sound. By default, only channels 0 and 1 exist (the usual stereo ones);
149 setting a volume for a channel will create it automatically.
151 The 'vol' directive allows volumes for many channels to be specified at a time.
157 vol <volume> <volume>
158 vol <volume> <volume> <volume>
159 vol <volume> <volume> <volume> <volume>
160 vol <volume> <volume> <volume> <volume> <volume> <volume>
162 Sets the volumes for a group of channels at a time. 1, 2, 3, 4 and 6 channels
163 can be specified, corresponding with the following well-known audio systems:
165 * mono: all in one channel
166 * stereo: left and right
167 * 3 channel: left, right and center
168 * quad: front left, front right, rear left and rear right
169 * 4 channel: left, center, right and surround
170 * 6 channel: left center, left, center, right center, right and surround
175 pitch_stretch <note> <length> <volume>
177 Starts playing a special note that will last exactly `length' whole notes,
178 changing its pitch if necessary. The `note' is just specified to locate the
179 desired layer and not as a pitch. This is mainly used to match rhythm loops
180 (that don't have a significative pitch) to the current tempo.
184 /* store three loops in the notes c1, d1 and e1 */
185 { wav "loop1.wav" c1 }
186 { wav "loop2.wav" d1 }
187 { wav "loop3.wav" e1 }
189 /* start loop2.wav lasting two measures */
190 { pitch_stretch d1 2 0.8 }
195 time_stretch <note> <length> <volume>
197 This command is NOT IMPLEMENTED.
202 print_wave_tempo <note> <number>
204 Prints the optimal tempo for the sample stored in `note' to last exactly
205 `number' whole notes. It does nothing to the output.
210 master_volume <number>
212 (New in 1.0.12) Sets the master volume (analogous to the -v command line switch).
214 Digital effect commands
215 -----------------------
220 delay <channel> <time>
222 Creates a phase delay in `channel'. Sample output will be delayed by
223 the `time' specification. No further filtering is done.
227 /* add a phase delay of 20 milliseconds in the right channel */
233 echo <channel> <time> <gain>
235 Creates an echo effect in `channel'. Sample output will be pass as is,
236 but mixed with the original signal phased by `time' and amplified by
241 /* add an 50% echo after 15 milliseconds */
247 comb <channel> <time> <gain>
249 Creates a comb filter in `channel'. Comb filters are used for implementing
260 allpass <channel> <time> <gain>
262 Creates an allpass filter in `channel'. Allpass filters are used for
263 implementing reverbs (see the built-in reverb command).
268 { allpass 0 20ms 0.9 }
273 flanger <channel> <time> <gain> <depth> <freq> <phase>
275 Creates a flanger effect in `channel'.
279 /* good stereo flanger */
280 { flanger 0 1s 0.9 3.40ms 0.1 0
281 flanger 1 1s 0.9 3.40ms 0.1 0.25 }
286 wobble <channel> <freq> <phase>
287 wobble <channel> <freq> <phase> <gain>
289 Creates a wobble effect in `channel'. Amplitude will have a sine wave
290 applied with a frequency of `freq', so volume will effectively go from
291 full amplitude to silence twice a period. The initial value for the
292 phase is set in `phase'. The wobble effect can be used to implement
293 tremolos with short frequencies and pan effects with long ones.
295 If `gain' is set, it's the ratio of wobbled / unmodified signal, ranging
296 from 1 (full wobbled) to 0 (no effect). If not set, `gain' has a default
297 value of 0.8. This behaviour is new in 1.0.9; previous versions didn't
298 accept the 4th argument and acted as if a gain of 1.0 was given.
302 /* tremolo (10Hz frequency) */
305 /* long stereo panning: one complete cycle
306 in 4 seconds (0.25Hz), with a 1/4 period
307 phase difference between both channels */
314 square_wobble <channel> <freq> <phase>
316 Creates a square wobble effect in `channel'. Its behaviour is the same
317 as the wobble command, but applying a square wave instead, so volume
318 will abruptly change from full amplitude to absolute silence twice a
324 half_wobble <channel> <freq> <phase>
326 (New in 1.0.8). Creates a half wobble effect in `channel'. Its behaviour is
327 the same as the wobble command, but the sine wave is applied to the
328 amplitude only the first half the period and silence the other half.
333 fader <channel> <time> <initial volume> <final volume>
335 Creates a fader effect in `channel'. `Time' is the length that will take
336 the channel volume to change from `initial volume' to `final volume'.
337 After `time' is passed, volume will be filtered to `final volume' until
338 the effect is destroyed.
342 /* a 5 seconds fade-in in left channel */
343 { fader 0 5s 0.0 1.0 }
350 Creates simple reverb in `channel'. This reverb is defined as
359 foldback <channel> <threshold>
361 (New in 1.0.8). Creates a simple distortion waveshaper where each amplitude
362 above `threshold' (range from -1 to 1) is folded back using the following
365 if(input > threshold)
366 output = threshold - (input - threshold);
368 if(input < -threshold)
369 output = -threshold + (-threshold - input);
371 See http://www.musicdsp.org/archive.php?classid=4#203 for more
377 atan <channel> <gain>
379 (New in 1.0.9). Creates a simple distortion waveshaper that applies an
380 atan() function to each input sample. `gain' must be greater than 1.
381 The output from this filter is slightly distorted but a bit quieter.
383 See http://www.musicdsp.org/showArchiveComment.php?ArchiveID=104 for
389 distort <channel> <gain>
391 (New in 1.0.9). Creates a simple distortion waveshaper that applies a
392 simple formula to each input sample. `gain' must be greater than 1.
394 See http://www.musicdsp.org/showArchiveComment.php?ArchiveID=86 for more
400 overdrive <channel> <gain>
402 (New in 1.0.9). Creates a simple distortion waveshaper that applies a
403 simple formula to each input sample. `gain' must be greater than 1. The
404 output from this filter is slightly distorted but a bit louder (it's not
405 a real overdrive, but for same waves it sounds similar).
407 See http://www.musicdsp.org/archive.php?classid=4#41 for more
415 This command resets the digital effect chain for `channel', destroying
416 all possible effects in it. Samples will then pass unmodified.
424 midi_channel <channel #>
426 Sets the MIDI channel for the current track. The `channel #' value must range
432 midi_program <program #>
434 Adds a MIDI program change event. The `program #' value ranges from 0 to 127.
436 Miscellaneous commands
437 ----------------------
442 song_info "Song Author" "Song Name"
444 (New in 1.0.4). This directive is used to set the author and name of the song.
445 These metadata can be used to generate .cue files.
448 Angel Ortega - http://triptico.com