doc/ahs_overview_ii.txt

   1 Ann Hell Scripting - II: Extended Commands
   2 ==========================================
   3
   4  Angel Ortega <angel@triptico.com>
   5
   6 Overview
   7 --------
   8
   9 Those directives that are not pure music instructions or are specific to a
  10 given output mode are called extended commands. They are expressed as
  11 curly bracket-enclosed blocks of keywords directly followed by their
  12 optional, respective arguments. As for the basic commands, formatting and
  13 indentation is free-form.
  14
  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
  17 well.
  18
  19 Software synthesizer commands
  20 -----------------------------
  21
  22 wav
  23 ~~~
  24
  25  wav "file.wav" <base>
  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>
  29
  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).
  38
  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
  45 channel).
  46
  47 Supported formats are: .wav (natively), .flac and .mp3 (via external
  48 converters).
  49
  50 Examples:
  51
  52  /* a simple wav with no loop and no range (just on note D1) */
  53  { wav "snare1.wav" d1 }
  54
  55  /* a wav to be playing in the C3-C4 range, tuned to G4, unlooped */
  56  { wav "glockenspiel-g4.wav" g4 c3 c4 }
  57
  58  /* another one, but using MIDI note numbers instead of note-octave notation */
  59  { wav "xilophone.wav" c5 1 127 }
  60
  61  /* a looped one */
  62  { wav "pad10.wav" f4 f1 b9 150 154056 }
  63
  64  /* another one, with a loop to fill the full wave */
  65  { wav "hiphop-drumline.wav" c1 c1 c1 0 -1 }
  66
  67  /* another way of expressing the first example */
  68  { wav "snare1.wav" d1 d1 d1 -1 -1 }
  69
  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 }
  74
  75 pat
  76 ~~~
  77
  78  pat "file.pat"
  79
  80 Loads a GUS compatible sound patch. All layers defined in it will be
  81 added to the current instrument.
  82
  83 sustain
  84 ~~~~~~~
  85
  86  sustain <time>
  87
  88 Sets the sustain for subsequent notes to be the specified `time'. Sustain
  89 is the time a digital sound will be sounding after being released.
  90
  91 vibrato
  92 ~~~~~~~
  93
  94  vibrato <depth> <frequency>
  95
  96 Sets the vibrato for the subsequent notes.
  97
  98 Example:
  99
 100  /* good depth values range from 0.45 to 0.68 */
 101  /* good frequency values are 6hz to 10hz */
 102  { vibrato 0.45ms 6 }
 103
 104 portamento
 105 ~~~~~~~~~~
 106
 107  portamento <factor>
 108
 109 (New in 1.0.8). Sets the portamento for subsequent notes. If `factor' is
 110 negative, the notes will slide down, or up if positive. Bigger values
 111 generate more portamento. The final result depends on the frequency of each
 112 note: lower notes will be more affected than higher ones for equal values
 113 of `factor'. A `factor' of 0 disables portamento.
 114
 115 channel
 116 ~~~~~~~
 117
 118  channel <channel #> <volume>
 119
 120 Sets the `volume' for the specified `channel #'. Usually it's a real number
 121 ranging from 0 (total silence) to 1 (full volume), but any value is accepted;
 122 numbers bigger than 1 will make the sound to be amplified (though with a
 123 risk of saturating), and negative values will negate the amplitude of the
 124 sound. By default, only channels 0 and 1 exist (the usual stereo ones);
 125 setting a volume for a channel will create it automatically.
 126
 127 The 'vol' directive allows volumes for many channels to be specified at a time.
 128
 129 vol
 130 ~~~
 131
 132  vol <volume>
 133  vol <volume> <volume>
 134  vol <volume> <volume> <volume>
 135  vol <volume> <volume> <volume> <volume>
 136  vol <volume> <volume> <volume> <volume> <volume> <volume>
 137
 138 Sets the volumes for a group of channels at a time. 1, 2, 3, 4 and 6 channels
 139 can be specified, corresponding with the following well-known audio systems:
 140
 141  * mono: all in one channel
 142  * stereo: left and right
 143  * 3 channel: left, right and center
 144  * quad: front left, front right, rear left and rear right
 145  * 4 channel: left, center, right and surround
 146  * 6 channel: left center, left, center, right center, right and surround
 147
 148 pitch_stretch
 149 ~~~~~~~~~~~~~
 150
 151  pitch_stretch <note> <length> <volume>
 152
 153 Starts playing a special note that will last exactly `length' whole notes,
 154 changing its pitch if necessary. The `note' is just specified to locate the
 155 desired layer and not as a pitch. This is mainly used to match rhythm loops
 156 (that don't have a significative pitch) to the current tempo.
 157
 158 Example:
 159
 160  /* store three loops in the notes c1, d1 and e1 */
 161  { wav "loop1.wav" c1 }
 162  { wav "loop2.wav" d1 }
 163  { wav "loop3.wav" e1 }
 164
 165  /* start loop2.wav lasting two measures */
 166  { pitch_stretch d1 2 0.8 }
 167
 168 time_stretch
 169 ~~~~~~~~~~~~
 170
 171  time_stretch <note> <length> <volume>
 172
 173 This command is NOT IMPLEMENTED.
 174
 175 print_wave_tempo
 176 ~~~~~~~~~~~~~~~~
 177
 178  print_wave_tempo <note> <number>
 179
 180 Prints the optimal tempo for the sample stored in `note' to last exactly
 181 `number' whole notes. It does nothing to the output.
 182
 183
 184 Digital effect commands
 185 -----------------------
 186
 187 delay
 188 ~~~~~
 189
 190  delay <channel> <time>
 191
 192 Creates a phase delay in `channel'. Sample output will be delayed by
 193 the `time' specification. No further filtering is done.
 194
 195 Example:
 196
 197  /* add a phase delay of 20 milliseconds in the right channel */
 198  { delay 1 20ms }
 199
 200 echo
 201 ~~~~
 202
 203  echo <channel> <time> <gain>
 204
 205 Creates an echo effect in `channel'. Sample output will be pass as is,
 206 but mixed with the original signal phased by `time' and amplified by
 207 `gain'.
 208
 209 Example:
 210
 211  /* add an 50% echo after 15 milliseconds */
 212  { echo 0 15ms 0.5 }
 213
 214 comb
 215 ~~~~
 216
 217  comb <channel> <time> <gain>
 218
 219 Creates a comb filter in `channel'. Comb filters are used for implementing
 220 reverbs.
 221
 222 Example:
 223
 224  /* comb filter */
 225  { comb 0 1ms 0.4 }
 226
 227 allpass
 228 ~~~~~~~
 229
 230  allpass <channel> <time> <gain>
 231
 232 Creates an allpass filter in `channel'. Allpass filters are used for
 233 implementing reverbs (see the built-in reverb command).
 234
 235 Example:
 236
 237  /* allpass filter */
 238  { allpass 0 20ms 0.9 }
 239
 240 flanger
 241 ~~~~~~~
 242
 243  flanger <channel> <time> <gain> <depth> <freq> <phase>
 244
 245 Creates a flanger effect in `channel'.
 246
 247 Example:
 248
 249  /* good stereo flanger */
 250  { flanger 0 1s 0.9 3.40ms 0.1 0
 251    flanger 1 1s 0.9 3.40ms 0.1 0.25 }
 252
 253 wobble
 254 ~~~~~~
 255
 256  wobble <channel> <freq> <phase>
 257  wobble <channel> <freq> <phase> <gain>
 258
 259 Creates a wobble effect in `channel'. Amplitude will have a sine wave
 260 applied with a frequency of `freq', so volume will effectively go from
 261 full amplitude to silence twice a period. The initial value for the
 262 phase is set in `phase'. The wobble effect can be used to implement
 263 tremolos with short frequencies and pan effects with long ones.
 264
 265 If `gain' is set, it's the ratio of wobbled / unmodified signal, ranging
 266 from 1 (full wobbled) to 0 (no effect). If not set, `gain' has a default
 267 value of 0.8. This behaviour is new in 1.0.9; previous versions didn't
 268 accept the 4th argument and acted as if a gain of 1.0 was given.
 269
 270 Examples:
 271
 272  /* tremolo (10Hz frequency) */
 273  { wobble 0 10 0 }
 274
 275  /* long stereo panning: one complete cycle
 276     in 4 seconds (0.25Hz), with a 1/4 period
 277     phase difference between both channels */
 278  { wobble 0 0.25 0
 279    wobble 1 0.25 0.25 }
 280
 281 square_wobble
 282 ~~~~~~~~~~~~~
 283
 284  square_wobble <channel> <freq> <phase>
 285
 286 Creates a square wobble effect in `channel'. Its behaviour is the same
 287 as the wobble command, but applying a square wave instead, so volume
 288 will abruptly change from full amplitude to absolute silence twice a
 289 period.
 290
 291 half_wobble
 292 ~~~~~~~~~~~
 293
 294  half_wobble <channel> <freq> <phase>
 295
 296 (New in 1.0.8). Creates a half wobble effect in `channel'. Its behaviour is
 297 the same as the wobble command, but the sine wave is applied to the
 298 amplitude only the first half the period and silence the other half.
 299
 300 fader
 301 ~~~~~
 302
 303  fader <channel> <time> <initial volume> <final volume>
 304
 305 Creates a fader effect in `channel'. `Time' is the length that will take
 306 the channel volume to change from `initial volume' to `final volume'.
 307 After `time' is passed, volume will be filtered to `final volume' until
 308 the effect is destroyed.
 309
 310 Example:
 311
 312  /* a 5 seconds fade-in in left channel */
 313  { fader 0 5s 0.0 1.0 }
 314
 315 reverb
 316 ~~~~~~
 317
 318  reverb <channel>
 319
 320 Creates simple reverb in `channel'. This reverb is defined as
 321
 322  { allpass 0 20ms 0.9
 323    allpass 0 36ms 0.9
 324    allpass 0 39ms 0.9 }
 325
 326 foldback
 327 ~~~~~~~~
 328
 329  foldback <channel> <threshold>
 330
 331 (New in 1.0.8). Creates a simple distortion waveshaper where each amplitude
 332 above `threshold' (range from -1 to 1) is folded back using the following
 333 formula:
 334
 335         if(input > threshold)
 336                 output = threshold - (input - threshold);
 337         else
 338         if(input < -threshold)
 339                 output = -threshold + (-threshold - input);
 340
 341 See http://www.musicdsp.org/archive.php?classid=4#203 for more
 342 information.
 343
 344 off
 345 ~~~
 346
 347  off <channel>
 348
 349 This command resets the digital effect chain for `channel', destroying
 350 all possible effects in it. Samples will then pass unmodified.
 351
 352 MIDI commands
 353 -------------
 354
 355 midi_channel
 356 ~~~~~~~~~~~~
 357
 358  midi_channel <channel #>
 359
 360 Sets the MIDI channel for the current track. The `channel #' value must range
 361 from 1 to 16.
 362
 363 midi_program
 364 ~~~~~~~~~~~~
 365
 366  midi_program <program #>
 367
 368 Adds a MIDI program change event. The `program #' value ranges from 0 to 127.
 369
 370 Miscellaneous commands
 371 ----------------------
 372
 373 song_info
 374 ~~~~~~~~~
 375
 376  song_info "Song Author" "Song Name"
 377
 378 (New in 1.0.4). This directive is used to set the author and name of the song.
 379 These metadata can be used to generate .cue files.
 380
 381 ----
 382 Angel Ortega - http://www.triptico.com