doc/controller.txt

   1 Controller
   2 ---------
   3
   4 image::./images/uicontroller.png[]
   5
   6 General
   7 ~~~~~~~
   8
   9 * *ModWh*: Modulation Wheel depth
  10 * *Exp MWh*: Exponential Modulation Wheel (changes modulation scale to
  11              exponential)
  12 * *BwDpth*: Bandwidth Depth
  13 * *Exp BW*: Exponential Bandwidth (changes bandwidth scale to exponential)
  14 * *PanDpth*: Panning Depth
  15 * *FltQ*: Filter Q (resonance) depth
  16 * *FltCut* Filter Cutoff frequency depth
  17 * *Expr*: enable/disable expression
  18 * *Vol*: enable/disable receiving volume controller
  19 * *FMamp*: enable/disable receiving Modulation Amplitude controller (76)
  20 * *Sustain*: enable/disable sustain pedal
  21 * *PWheelB.Rng (cents)*: Pitch Wheel Bend Range (cents; 100 cents = 1 halftone)
  22
  23 Modulation wheel
  24 ~~~~~~~~~~~~~~~~
  25
  26 The modulation wheel (MIDI CC #1) controls the amount of modulation applied
  27 by the Amplitude, Frequency and Filter LFOs in all voices. The amount
  28 of control is governed by the Modulation Wheel depth parameter. When this
  29 parameter is set to 0, the modulation wheel has no control over the modulation
  30 amount, and it is always the value set by the *Depth* setting in the
  31 respective LFO. The default value for the Modulation Wheel depth parameter
  32 is 80.
  33
  34 When the modulation depth parameter is advanced above 0, the modulation wheel
  35 starts to influence the amount of modulation. When the modulation wheel
  36 is it its center position (control value 64), the modulation amount will
  37 always be at the value set by the *Depth* setting in LFO. Smaller modulation
  38 wheel values than 64 will decrease the amount of modulation, and larger
  39 modulation values will increase it, the amount of decrease or increase being
  40 governed by the modulation depth parameter. The modulation amount does not
  41 necessarily drop to zero just because the modulation wheel is at zero,
  42 depending on the setting of the depth parameter. For the modulation amount
  43 to drop to zero, the modulation wheel depth value must be 64 (half way
  44 position) or more.
  45
  46 Note that in any case, when the modulation depth is set such that modulation
  47 wheel does have control over the modulation amount, the maximum amount of
  48 modulation applied (when the modulation wheel has a value of 127), will be
  49 higher than the base setting in the LFO depth parameters.
  50
  51 When the *Exp Mwh* parameter is enabled, the modulation scale becomes
  52 exponential. Pragmatically, this has two effects:
  53
  54 * The amount of modulation as the modulation wheel is advanced becomes more
  55   gradual, or put another way, the modulation wheel must be advanced further to
  56   get the same amount of modulation when the scale is exponential compared to
  57   when it is not. This gives more precise control over the onset of modulation.
  58 * When the modulation wheel is advanced past its center position (value 64),
  59   the maximum attainable modulation amount is much higher.
  60
  61 Note that even when modulation scale is set to exponential, a center modulation
  62 wheel value (64) still corresponds to the modulation depth set in the
  63 respective LFOs.
  64
  65 So, to sum up:
  66
  67 * The Modulation Wheel depth parameter must be larger 0 for the modulation
  68   wheel to have any effect on the modulation amount.
  69 * A center modulation wheel position (value 64) corresponds to the modulation
  70   depth setting in the LFOs.
  71 * Decreasing the modulation wheel value towards 0 will reduce the amount of
  72   modulation, and advancing it towards the maximum value (127) will increase
  73   the amount of modulation, as governed by the Modulation Wheel depth
  74   parameter, with the amount of modulation set by the LFO depth parameters
  75   as the base.
  76 * For a modulation wheel value of 0 to completely inhibit any modulation,
  77   the Modulation Wheel depth control must be 64 (half way) or higher.
  78 * Enabling Exponential Modulation Wheel will provide finer control of
  79   the onset of modulation, as well as higher achievable maximum modulation
  80   values.
  81
  82 Portamento
  83 ~~~~~~~~~~
  84
  85 * *Prt.Rcv*: If the part receives portamento On/Off (65) controller
  86 * *Enable*: If portamento is enabled for the part
  87 * *Auto*: If portamento is applied only when playing legato
  88 * *Time*: The duration of the portamento
  89 * *Up/down*: Sets ratio of portamento time between up- and down-going pitch
  90 steps
  91 * *Tr.type*: The threshold type.
  92 Checked means that the portamento activates when the difference of frequencies
  93 is above the threshold ("Thresh"); not checked is for below the threshold.
  94 * *Thresh*: The threshold of the portamento.
  95 It represents the minimum or the maximum number of halftones
  96 (or hundred cents) required to start the portamento.
  97 The difference is computed between the last note and current note.
  98
  99 NOTE: The threshold refers to the frequencies and not to MIDI notes
 100       (you should consider this if you use microtonal scales).
 101
 102 Proportional Portamento
 103 ^^^^^^^^^^^^^^^^^^^^^^^
 104 ////
 105 TODO: add graphs to explain prp.rate and prp. depth
 106 ////
 107
 108 * *Prop.*: If the portamento time is proportional to ratio of frequencies
 109 * *Prp. Scale*: Ratio needed to double the time of portamento
 110 * *Prp. Depth*: The divergence from constant portamento time
 111
 112 Detailed portamento description
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 The basis for the portamento function is the corresponding function in a
 116 monophonic analog synthesizer.  In an analog synthesizer, portamento is
 117 implemented as a lag circuit on the CV from the keyboard to the oscillators,
 118 providing a smooth glide of the pitch rather than jumping to the new pitch when
 119 a new note is played.  Thus, a key feature of portamento is that whenever a new
 120 note is played, regardless of whether the target pitch of the previous note had
 121 been reached or not, the journey to the new pitch starts at whatever pitch
 122 prevailed at the time.
 123
 124 In a polyphonic analog synthesizer, a trivial implementation of portamento is
 125 using separate lag circuits at the keyboard CV inputs of each voice. This does
 126 create a bit of a chaotic portamento behavior however, because the glide for a
 127 played voice will start at whatever pitch the individual voice had previously,
 128 which is not necessarily the same as the previously played note, as it would be
 129 in the case of monophonic portamento. Nevertheless, this is the most common
 130 implementation of portamento on a polyphonic analog synthesizer, and the mild
 131 chaos that ensues when portamento is enabled is still musically useful.
 132
 133 Many analog synthesizers implement an optional so-called auto mode for the
 134 portamento, whereby portamento is only applied when notes are played
 135 legato (i.e. one one key is pressed without releasing the previously played
 136 key). This way, the player has direct control over the application of
 137 portamento directly in the playing style, without having to resort to a
 138 separate controller (button or pedal) to enable/disable portamento.
 139
 140 In a digital synthesizer, it is possible to emulate the behavior of an analog
 141 polyphonic synthesizer, especially if the implementation models the behavior
 142 in terms of a fixed set of voices which are allocated much in the same way as
 143 the analog voices would be. However, in synthesizers such as ZynAddSubFx,
 144 voices are allocated on an as-needed basis, and deallocated afterwards, so when
 145 triggering a new voice, it has no "previous pitch". Unless we purposely want to
 146 emulate the behavior of a voice allocated analog synthesizer, we can explore
 147 other portamento models.
 148
 149 Indeed, in a digital synthesizer, it is possible to use the monophonic
 150 portamento behavior as the basis also for polyphonic portamento. This means
 151 that when triggering a new note, the pitch of the note should start at the
 152 pitch of the previously played note, which may not actually be the target pitch
 153 of that note if there was an ongoing portamento at the time the new note was
 154 triggered.
 155
 156 For example, assume C1 is played, and then C2. C2 starts its pitch at C1 and
 157 glides upwards. Half way, say when the to-be-C2 voice has reached G1 during its
 158 glide, C3 is played. The portamento for C3 should then start at G1, i.e. the
 159 pitch that the second played note had reached at that time, rather than for
 160 instance at the target pitch of C2, which would give the impression of a C2
 161 suddenly being played from nowhere, before gliding up to C3. This mimics the
 162 smooth new-notes-start-at-the-current-pitch behavior of a monophonic
 163 portamento implementation, which is both logical and consistent.
 164
 165 Portamento operation in ZynAddSubFx
 166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 167
 168 For each note played, the portamento controller makes a decision as to whether
 169 the note should have portamento or not, governed by the *Auto*, *Enable*,
 170 *Tr.Type* and *Thresh* parameters. Whenever a note is played which should have
 171 portamento, the portamento starts at the pitch that the previously played note
 172 was at when the new note was played. This slightly long-winded explanation
 173 encompasses the case of the previous note being in the process of gliding due
 174 to portamento, in which case the new note should start precisely at that pitch.
 175 This behavior is the same in all key assignment modes (polyphonic, monophonic
 176 or legato).
 177
 178 In poly mode, each note will have its own portamento, i.e. each note will glide
 179 individually from its initial pitch (see previous section) to the target pitch
 180 (= the note played).
 181
 182 Regardless of the key assign mode, portamento can be enabled for every note, or
 183 only when notes are played legato. This is governed by the *Auto* parameter.
 184 This parameter is enabled by default. When loading patches created prior to
 185 Zynaddsubfx version 3.0.7, the *Auto* parameter is set according to the key
 186 assign mode: Auto is disabled in poly mode, and enabled in mono and legato
 187 modes.
 188
 189 Resonance
 190 ~~~~~~~~~
 191
 192 * *CFdpth*: resonance center controller depth
 193 * *BWdpth*: resonance bandwidth controller depth