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 pat
  30 ~~~
  31
  32  pat "file.pat"
  33
  34 sustain
  35 ~~~~~~~
  36
  37  sustain <time>
  38
  39 vibrato
  40 ~~~~~~~
  41
  42  vibrato <depth> <frequency>
  43
  44 Example:
  45
  46  /* good depth values range from 0.45 to 0.68 */
  47  /* good frequency values are 6hz to 10hz */
  48  { vibrato 0.45ms 6 }
  49
  50 channel
  51 ~~~~~~~
  52
  53  channel <channel #> <volume>
  54
  55 vol
  56 ~~~
  57
  58  vol <volume>
  59  vol <volume> <volume>
  60  vol <volume> <volume> <volume>
  61  vol <volume> <volume> <volume> <volume>
  62  vol <volume> <volume> <volume> <volume> <volume> <volume>
  63
  64 pitch_stretch
  65 ~~~~~~~~~~~~~
  66
  67  pitch_stretch <note> <length in wholes> <volume>
  68
  69 time_stretch
  70 ~~~~~~~~~~~~
  71
  72  time_stretch <note> <length in wholes> <volume>
  73
  74 This command is NOT IMPLEMENTED.
  75
  76 Digital effect commands
  77 -----------------------
  78
  79 delay
  80 ~~~~~
  81
  82  delay <channel> <time>
  83
  84 Creates a phase delay in <channel>. Sample output will be delayed by
  85 the <time> specification. No further filtering is done.
  86
  87 Example:
  88
  89  /* add a phase delay of 20 milliseconds in the right channel */
  90  { delay 1 20ms }
  91
  92 echo
  93 ~~~~
  94
  95  echo <channel> <time> <gain>
  96
  97 Creates an echo effect in <channel>. Sample output will be pass as is,
  98 but mixed with the original signal phased by <time> and amplified by
  99 <gain>.
 100
 101 Example:
 102
 103  /* add an 50% echo after 15 milliseconds */
 104  { echo 0 15ms 0.5 }
 105
 106 comb
 107 ~~~~
 108
 109  comb <channel> <time> <gain>
 110
 111 Creates a comb filter in <channel>. Comb filters are used for implementing
 112 reverbs.
 113
 114 Example:
 115
 116  /* comb filter */
 117  { comb 0 1ms 0.4 }
 118
 119 allpass
 120 ~~~~~~~
 121
 122  allpass <channel> <time> <gain>
 123
 124 Creates an allpass filter in <channel>. Allpass filters are used for
 125 implementing reverbs (see the built-in reverb command).
 126
 127 Example:
 128
 129  /* allpass filter */
 130  { allpass 0 20ms 0.9 }
 131
 132 flanger
 133 ~~~~~~~
 134
 135  flanger <channel> <time> <gain> <depth> <freq> <phase>
 136
 137 Creates a flanger effect in <channel>.
 138
 139 Example:
 140
 141  /* good stereo flanger */
 142  { flanger 0 1s 0.9 3.40ms 0.1 0
 143    flanger 1 1s 0.9 3.40ms 0.1 0.25 }
 144
 145 wobble
 146 ~~~~~~
 147
 148  wobble <channel> <freq> <phase>
 149
 150 Creates a wobble effect in <channel>. Amplitude will have a sine wave
 151 applied with a frequency of <freq>, so volume will effectively go from
 152 full amplitude to silence twice a period. The initial value for the
 153 phase is set in <phase>. The wobble effect can be used to implement
 154 tremolos with short frequencies and pan effects with long ones.
 155
 156 Examples:
 157
 158  /* tremolo (10Hz frequency) */
 159  { wobble 0 10 0 }
 160
 161  /* long stereo panning: one complete cycle
 162     in 4 seconds (0.25Hz), with a 1/4 period
 163     phase difference between both channels */
 164  { wobble 0 0.25 0
 165    wobble 1 0.25 0.25 }
 166
 167 square_wobble
 168 ~~~~~~~~~~~~~
 169
 170  square_wobble <channel> <freq> <phase>
 171
 172 Creates a square wobble effect in <channel>. Its behaviour is the same
 173 as the wobble command, but applying a square wave instead, so volume
 174 will abruptly change from full amplitude to absolute silence twice a
 175 period.
 176
 177 fader
 178 ~~~~~
 179
 180  fader <channel> <time> <initial volume> <final volume>
 181
 182 Creates a fader effect in <channel>. <Time> is the length that will take
 183 the channel volume to change from <initial volume> to <final volume>.
 184 After <time> is passed, volume will be filtered to <final volume> until
 185 the effect is destroyed.
 186
 187 Example:
 188
 189  /* a 5 seconds fade-in in left channel */
 190  { fader 0 5s 0.0 1.0 }
 191
 192 reverb
 193 ~~~~~~
 194
 195  reverb <channel>
 196
 197 Creates simple reverb in <channel>. This reverb is defined as
 198
 199  { allpass 0 20ms 0.9
 200    allpass 0 36ms 0.9
 201    allpass 0 39ms 0.9 }
 202
 203 off
 204 ~~~
 205
 206  off <channel>
 207
 208 This command resets the digital effect chain for <channel>, destroying
 209 all possible effects in it. Samples will then pass unmodified.
 210
 211 MIDI commands
 212 -------------
 213
 214 midi_channel
 215 ~~~~~~~~~~~~
 216
 217  midi_channel <channel #>
 218
 219 Sets the MIDI channel for the current track. The <channel #> value must range
 220 from 1 to 16.
 221
 222 midi_program
 223 ~~~~~~~~~~~~
 224
 225  midi_program <program #>
 226
 227 Adds a MIDI program change event. The <program #> value ranges from 0 to 127.
 228
 229 ----
 230 Angel Ortega - http://www.triptico.com