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