doc/language2.txt

   1 Ann Hell Ex Machina 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 note>
  26  wav "file.wav" <base note> <min note> <max note>
  27  wav "file.wav" <base note> <min note> <max note> <loop start> <loop end>
  28
  29 Loads a WAV file as a layer for the current instrument. If just the <base note>
  30 is specified, a layer will be created for that note only. If <loop start>
  31 and <loop end> are not specified, the layer will be accepted as an un-looped one.
  32
  33 pat
  34 ~~~
  35
  36  pat "file.pat"
  37
  38 Loads a GUS compatible sound patch. All layers defined in it will be
  39 added to the current instrument.
  40
  41 copy
  42 ~~~~
  43
  44  copy <track #>
  45
  46 Copies all instrument layers in <track #> into the current one. This way, the real
  47 (probably memory-expensive) PCM wave data can be shared among many tracks.
  48
  49 Example:
  50
  51  /* track 0: piano, left hand */
  52
  53  /* loads a very big piano patch */
  54  { pat "verybigpiano.pat" }
  55
  56  /* left hand notes */
  57  /* ... */
  58
  59  \
  60
  61  /* track 1: piano, right hand */
  62
  63  /* copies the instrument layers from track # 0 */
  64  { copy 0 }
  65
  66  /* right hand notes */
  67  /* ... */
  68
  69 sustain
  70 ~~~~~~~
  71
  72  sustain <time>
  73
  74 Sets the sustain for subsequent notes to be the specified <time>. Sustain
  75 is the time a digital sound will be sounding after being released.
  76
  77 vibrato
  78 ~~~~~~~
  79
  80  vibrato <depth> <frequency>
  81
  82 Sets the vibrato for the subsequent notes.
  83
  84 Example:
  85
  86  /* good depth values range from 0.45 to 0.68 */
  87  /* good frequency values are 6hz to 10hz */
  88  { vibrato 0.45ms 6 }
  89
  90 channel
  91 ~~~~~~~
  92
  93  channel <channel #> <volume>
  94
  95 Sets the <volume> for the specified <channel #>. Usually it's a real number
  96 ranging from 0 (total silence) to 1 (full volume), but any value is accepted;
  97 numbers bigger than 1 will make the sound to be amplified (though with a
  98 risk of saturating), and negative values will negate the amplitude of the
  99 sound. By default, only channels 0 and 1 exist (the usual stereo ones);
 100 setting a volume for a channel will create it automatically.
 101
 102 The 'vol' directive allows volumes for many channels to be specified at a time.
 103
 104 vol
 105 ~~~
 106
 107  vol <volume>
 108  vol <volume> <volume>
 109  vol <volume> <volume> <volume>
 110  vol <volume> <volume> <volume> <volume>
 111  vol <volume> <volume> <volume> <volume> <volume> <volume>
 112
 113 Sets the volumes for a group of channels at a time. 1, 2, 3, 4 and 6 channels
 114 can be specified, corresponding with the following well-known audio systems:
 115
 116  * mono: all in one channel
 117  * stereo: left and right
 118  * 3 channel: left, right and center
 119  * quad: front left, front right, rear left and rear right
 120  * 4 channel: left, center, right and surround
 121  * 6 channel: left center, left, center, right center, right and surround
 122
 123 pitch_stretch
 124 ~~~~~~~~~~~~~
 125
 126  pitch_stretch <note> <length> <volume>
 127
 128 Starts playing a special note that will last exactly <length> whole notes,
 129 changing its pitch if necessary. The <note> is just specified to locate the
 130 desired layer and not as a pitch. This is mainly used to match rhythm loops
 131 (that don't have a significative pitch) to the current tempo.
 132
 133 Example:
 134
 135  /* store three loops in the notes c1, d1 and e1 */
 136  { wav "loop1.wav" c1 }
 137  { wav "loop2.wav" d1 }
 138  { wav "loop3.wav" e1 }
 139
 140  /* start loop2.wav lasting two measures */
 141  { pitch_stretch d1 2 0.8 }
 142
 143 time_stretch
 144 ~~~~~~~~~~~~
 145
 146  time_stretch <note> <length> <volume>
 147
 148 This command is NOT IMPLEMENTED.
 149
 150 Digital effect commands
 151 -----------------------
 152
 153 delay
 154 ~~~~~
 155
 156  delay <channel> <time>
 157
 158 Creates a phase delay in <channel>. Sample output will be delayed by
 159 the <time> specification. No further filtering is done.
 160
 161 Example:
 162
 163  /* add a phase delay of 20 milliseconds in the right channel */
 164  { delay 1 20ms }
 165
 166 echo
 167 ~~~~
 168
 169  echo <channel> <time> <gain>
 170
 171 Creates an echo effect in <channel>. Sample output will be pass as is,
 172 but mixed with the original signal phased by <time> and amplified by
 173 <gain>.
 174
 175 Example:
 176
 177  /* add an 50% echo after 15 milliseconds */
 178  { echo 0 15ms 0.5 }
 179
 180 comb
 181 ~~~~
 182
 183  comb <channel> <time> <gain>
 184
 185 Creates a comb filter in <channel>. Comb filters are used for implementing
 186 reverbs.
 187
 188 Example:
 189
 190  /* comb filter */
 191  { comb 0 1ms 0.4 }
 192
 193 allpass
 194 ~~~~~~~
 195
 196  allpass <channel> <time> <gain>
 197
 198 Creates an allpass filter in <channel>. Allpass filters are used for
 199 implementing reverbs (see the built-in reverb command).
 200
 201 Example:
 202
 203  /* allpass filter */
 204  { allpass 0 20ms 0.9 }
 205
 206 flanger
 207 ~~~~~~~
 208
 209  flanger <channel> <time> <gain> <depth> <freq> <phase>
 210
 211 Creates a flanger effect in <channel>.
 212
 213 Example:
 214
 215  /* good stereo flanger */
 216  { flanger 0 1s 0.9 3.40ms 0.1 0
 217    flanger 1 1s 0.9 3.40ms 0.1 0.25 }
 218
 219 wobble
 220 ~~~~~~
 221
 222  wobble <channel> <freq> <phase>
 223
 224 Creates a wobble effect in <channel>. Amplitude will have a sine wave
 225 applied with a frequency of <freq>, so volume will effectively go from
 226 full amplitude to silence twice a period. The initial value for the
 227 phase is set in <phase>. The wobble effect can be used to implement
 228 tremolos with short frequencies and pan effects with long ones.
 229
 230 Examples:
 231
 232  /* tremolo (10Hz frequency) */
 233  { wobble 0 10 0 }
 234
 235  /* long stereo panning: one complete cycle
 236     in 4 seconds (0.25Hz), with a 1/4 period
 237     phase difference between both channels */
 238  { wobble 0 0.25 0
 239    wobble 1 0.25 0.25 }
 240
 241 square_wobble
 242 ~~~~~~~~~~~~~
 243
 244  square_wobble <channel> <freq> <phase>
 245
 246 Creates a square wobble effect in <channel>. Its behaviour is the same
 247 as the wobble command, but applying a square wave instead, so volume
 248 will abruptly change from full amplitude to absolute silence twice a
 249 period.
 250
 251 fader
 252 ~~~~~
 253
 254  fader <channel> <time> <initial volume> <final volume>
 255
 256 Creates a fader effect in <channel>. <Time> is the length that will take
 257 the channel volume to change from <initial volume> to <final volume>.
 258 After <time> is passed, volume will be filtered to <final volume> until
 259 the effect is destroyed.
 260
 261 Example:
 262
 263  /* a 5 seconds fade-in in left channel */
 264  { fader 0 5s 0.0 1.0 }
 265
 266 reverb
 267 ~~~~~~
 268
 269  reverb <channel>
 270
 271 Creates simple reverb in <channel>. This reverb is defined as
 272
 273  { allpass 0 20ms 0.9
 274    allpass 0 36ms 0.9
 275    allpass 0 39ms 0.9 }
 276
 277 off
 278 ~~~
 279
 280  off <channel>
 281
 282 This command resets the digital effect chain for <channel>, destroying
 283 all possible effects in it. Samples will then pass unmodified.
 284
 285 MIDI commands
 286 -------------
 287
 288 midi_channel
 289 ~~~~~~~~~~~~
 290
 291  midi_channel <channel #>
 292
 293 Sets the MIDI channel for the current track. The <channel #> value must range
 294 from 1 to 16.
 295
 296 midi_program
 297 ~~~~~~~~~~~~
 298
 299  midi_program <program #>
 300
 301 Adds a MIDI program change event. The <program #> value ranges from 0 to 127.
 302
 303 ----
 304 Angel Ortega - http://www.triptico.com