This transform has the functionality of a mixing board, allowing clients to control gain and pan for each voice.
It is often useful for clients to be able to control multiple gain values that multiply together to produce the overall gain for a voice. Thus, there are five total variables for each voice whose values are multiplied together to produce the overall gain: gain, gain_scale1, gain_scale2, gain_scale3, and gain_scale4.
This transform also supplies linear and logarithmic amplitude envelopes, which ramp gradually from the current value to the desired value over a given number of seconds. These envelopes can affect any of the five gain parameters.
The gain of the even-numbered and odd-numbered partials can be controlled individually. This effect is predictable if the partials lie along a harmonic series, which may not always be the case.
Message | Argument(s) | Type(s) | Description |
pan | Pan from 0 (hard left) to 1 (hard right) | Float | Pan for this voice (possibly broken) |
gain | Gain scaler | Float | Gain for this voice |
gain_scale1 | Gain scaler | Float | Gain for this voice |
gain_scale2 | Gain scaler | Float | Gain for this voice |
gain_scale3 | Gain scaler | Float | Gain for this voice |
gain_scale4 | Gain scaler | Float | Gain for this voice |
gain_ramp | New gain, time to get there (in seconds) | Float, Float | Move gain to the given value over the given amount of time. |
gain_scale1_ramp | New gain_scale1, time to get there (in seconds) | Float, Float | Move gain_scale1 to the given value over the given amount of time. |
gain_scale2_ramp | New gain_scale2, time to get there (in seconds) | Float, Float | Move gain_scale2 to the given value over the given amount of time. |
gain_scale3_ramp | New gain_scale3, time to get there (in seconds) | Float, Float | Move gain_scale3 to the given value over the given amount of time. |
gain_scale4_ramp | New gain_scale4, time to get there (in seconds) | Float, Float | Move gain_scale4 to the given value over the given amount of time. |
gain_dbramp | New gain in dB, time to get there (in seconds) | Float, Float | Move gain to the given value over the given amount of time with an exponential curve. |
gain_scale1_dbramp | New gain_scale1 in dB, time to get there (in seconds) | Float, Float | Move gain_scale1 to the given value over the given amount of time with an exponential curve. |
gain_scale2_dbramp | New gain_scale2 in dB, time to get there (in seconds) | Float, Float | Move gain_scale2 to the given value over the given amount of time with an exponential curve. |
gain_scale3_dbramp | New gain_scale3 in dB, time to get there (in seconds) | Float, Float | Move gain_scale3 to the given value over the given amount of time with an exponential curve. |
gain_scale4_dbramp | New gain_scale4 in dB, time to get there (in seconds) | Float, Float | Move gain_scale4 to the given value over the given amount of time with an exponential curve. |
odd_gain | Gain scaler | Float | Gain for odd-numbered partials |
even_gain | Gain scaler | Float | Gain for even-numbered partials |
The "dbramp" messages specify a target value in decibels. A value of 0.0 dB corresponds to "unity gain", i.e., a gain value of 1.0. The gain ramp created by the dbramp messages is linear along a decibel scale. Since decibels are a logarithmic scale, a linear ramp along the decibel scale is an exponential curve.
Keep in mind that there are infinitely many exponential curves that can connect the current value of a gain parameter to a desired value sometime in the future. This definition of dbramps uniquely specifies a particular curve.
Each voice has five gain parameters whose values are multiplied together on each synthesis frame to produce the actual gain value that scales the amplitudes of the partials. By default all of these values are 1.0, so the product is also 1.0, causing this transform not to alter the gains of anything. (This number five is totally arbitrary, and comes from needs we happened to have for a particular concert. It would be very easy to add more of these parameters.)
The messages gain, gain_ramp, and gain_dbramp are three mutually exclusive ways to control the same underlying parameter. (And so on for gain_scale1, gain_scale1_ramp, and gain_scale1_dbramp, etc.) If a voice is in the middle of a ramp (either linear or log), not yet having arrived at the desired value, and it receives a gain message, the gain parameter goes immediately to the new value, and the rest of the ramp is cancelled. If a voice is in the middle of a ramp and receives a new ramp or dbramp message, it starts from the current gain value, cancels the ramp it's in the middle of, and starts on a new ramp with the new parameters.
If a voice gets to the end of a ramp, reaching the target value, that gain parameter stays at the target value until a new message is received.
Make voice 1 louder by 50%:
/voices/0/mixer/gain 1.5 /voices/0/tm/goto 0.
Make voice 1 fade out over 3 seconds:
/voices/0/mixer/gain 1. /voices/0/mixer/gain_ramp 0. 3. /voices/0/tm/goto 0.
Make voice 1 fade out exponentially over 3 seconds:
/voices/0/mixer/gain 1. /voices/0/mixer/gain_dbramp -120. 3. /voices/0/tm/goto 0.
Start in the middle of a timbral prototype and use a short exponential envelope to avoid a click:
/voices/0/mixer/gain_scale1 0. /voices/0/mixer/gain_scale1_dbramp 0. 0.2 /voices/0/tm/goto 0.5
Hear only the odd-numbered partials
/voices/0/mixer/even_gain 0. /voices/0/mixer/odd_gain 1. /voices/0/tm/goto 0.
Hear only the even-numbered partials
/voices/0/mixer/even_gain 0. /voices/0/mixer/odd_gain 1. /voices/0/tm/goto 0.