Shape Class Reference
[Waveshaping (a.k.a. Nonlinear Distortion) Synthesis]
Waveshaping synthesis, with index control and amplitude envelope.
More...
#import <Shape.h>
Public Member Functions | |
| (id) | - noteOnSelf: |
| aNote is assumed to be a noteOn or noteDur. | |
| (id) | - noteUpdateSelf: |
| aNote is assumed to be a noteUpdate and the receiver is assumed to be currently playing a MKNote. | |
| (double) | - noteOffSelf: |
| aNote is assumed to be a noteOff. | |
| (id) | - noteEndSelf |
| Resest instance variables to default values. | |
| (id) | - preemptFor: |
| Preempts envelope, if any. | |
| (id) | - init |
| Sent by the MKOrchestra only when a new MKSynthPatch has just been created and before its MKUnitGenerator connections have been made, as defined by the MKPatchTemplate. | |
Static Public Member Functions | |
| (id) | + patchTemplateFor: |
| Returns a default template. | |
Detailed Description
Waveshaping synthesis, with index control and amplitude envelope.Shape is a single-lookup table non-linear distortion (waveshaping) SynthPatch. It has an interpolating-oscillator for a "carrier" (oscillator driving the lookup) with an arbitrary waveform, an interpolating lookup table, and envelopes on amplitude (scaler on output), frequency, and waveshaping index (amplitude of carrier). Additionally,
For further information, see the LeBrun article sited below. Other documentation includes WaveShaping.math.ps (or the similarly-named Mathematica files) in the folder /LocalLibrary/Documentation/MusicKit+DSP/Music/Concepts/SpecialTopics/
Note that the result of the usual envelope computation (val = m1IndEnv(time) * (m1Ind1 - m1Ind0) + m1Ind0) must be between 0.0 and 1.0, otherwise you will be reading values outside of the table. Note also that m1IndEnv can have some small effect on amplitude, even though its primary purpose is to affect timbre. (The smallness of the effect is achieved through the Le Brun "signification" algorithm.)
Here is a diagram of Shape:
If the m1Waveform parameter's value is a Partials object, it gives a specification for the harmonic structure of the lookup table. For example, if you want the table to produce two harmonics, you could specify a Partials object with two partials, one at harmonic number 1 and one at harmonic number 2. Note also that using higher numbered harmonics in a waveshaping table Partials object, results in a greater compute time to create the table. If you specify a Samples object to m1Waveform, it is used directly as the distortion lookup table.
Additional features that ambitious users might want to consider adding include doing some of the other things that Arfib, LeBrun, and Beauchamp described in their articles:
1- adding a post-lookup multiplication with a sinusoid, to obtain symmetric Spectra, and with proper choice of the multiplying sine's frequency, inharmonic to obtain bell-like sounds. (see LeBrun; Arfib) 2- Double Modulation (See Arfib) 3- adding a filter after the table-lookup. (See Beauchamp)
When using this SynthPatch in an interactive real-time context, such as playing from a MIDI keyboard, call MKUseRealTimeEnvelopes() before allocating the SynthPatch.
For more Information:
Arfib, D. 1979. "Digital Waveshaping Synthesis of complex spectra by means of multiplication of nonlinear distorted sine waves." Journal of the Audio Engineering Society 27(10): 757-768. Beauchamp, J. 1979. "Brass Tone Synthesis by Spectrum Evolution Matching with Nonlinear Functions." Computer Music Journal 3(2): 35-43. (Available in: Foundations of Computer Music, Curtis Roads and John Strawn, eds. The MIT Press, Cambridge, MA. 1985.) LeBrun, M. 1979. "Digital WaveShaping Synthesis." Journal of the Audio Engineering Society 27(4): 250-266. Moore, F. R. 1990. Elements of Computer Music. Prentice Hall, Englewood Cliffs, NJ. Roads, C. 1979. "A Tutorial on Nonlinear Distortion or Waveshaping Synthesis." Computer Music Journal 3(2): 29-34. (Also available in the Roads and Strawn book.)
Parameter Interpretation
ampEnv - Amplitude envelope. Default is an envelope that is always a constant 1.0.
amp - Amplitude. In the range 0.0:1.0. amp1 is a synonym for amp. Default is 0.1.
amp0 - Amplitude when the envelope is at 0.0. amp is amplitude when the envelope is at 1.0. amp1 is a synonym for amp. Default is 0.0.
ampAtt - Time of attack portion of envelope in seconds. If this parameter is not present, the times in the envelope are used verbatim.
ampRel - Time of release portion of envelope in seconds. If this parameter is not present, the times in the envelope are used verbatim.
bearing - Left/right panning of signal. In range -45.0:45.0. -45.0 is far left. Default is 0.0.
bright - Brightness, a multiplier on index. Defaults to 1.0.
controlChange - This parameter is the MIDI controller number to be affected. It is used in conjunction with the parameter controlVal, which provides the value the controller is set to. This SynthPatch uses MIDI volume (controller 7) to adjust output volume as an attenuation of the final output signal. The default for MIDI volume is 127.
controlVal - See controlChange.
freq - Frequency in Hz. freq1 is a synonym for freq. Default is A440.
freqEnv - Frequency envelope. Default is an envelope that is always a constant 1.0.
freq0 -Fundamental frequency when the envelope is at 0. freq is frequency when the envelope is at 1. freq1 is a synonym for freq. Default is 0.0.
freqAtt -Time of attack portion of envelope in seconds. If this parameter is not present, the times in the envelope are used verbatim.
freqRel -Time of release portion of envelope in seconds. If this parameter is not present, the times in the envelope are used verbatim.
keyNum - The MIDI key number, an alternative to freq. If both freq and keyNum are present, freq, takes precedence. In the range 0:127.
m1Ind - Modulation index. If an envelope, is specified, this is the index when the envelope is at 1. m1Ind1 is synonym for m1Ind. Default is 1.0.
m1IndEnv - Modulation index envelope. Default is a constant value of 1.0.
m1Ind0 - Modulation index when envelope is at 0.0. m1Ind is index when envelope is at 1.0. Default is 0.0.
m1IndAtt -Time of attack portion of envelope in seconds. If this parameter is not present, the times in the envelope are used verbatim.
m1IndRel - Time of release portion of envelope in seconds. If this parameter is not present, the times in the envelope are used verbatim.
m1Waveform - Modulator wave table. Default produces a sine wave. See comments above.
phase - Initial phase of wavetable in degrees. Rarely needed. Default is 0.0.
pitchBend - Modifies frequency (or keyNum) as a 14 bit integer. A value of MIDI_ZEROBEND (defined as 0x2000 in <mididriver/midi_spec.h>) gives no bend. 0 is maximum negative bend. 0x3fff is maximum positive bend. See TuningSystem class for details. May give unexpected results when combined with frequency envelopes. Default is MIDI_ZEROBEND.
portamento - Portamento time. In a phrase, the transition time to a note from the immediately preceding note. Overrides the time values of the first segment of the envelopes. Note that portamento is applied after the attack-time parameters.
velocity - A MIDI parameter. In range 0:127. The default is 64. Velocity scales amplitude by an amount deteremined by velocitySensitivity. Some SynthPatches also scale brightness or FM index based on velocity.
velocitySensitivity - In range 0.0:1.0. Default is 0.5. When velocitySensitivity is 0, velocity has no effect.
pitchBendSensitivity - A value of 0.0 means pitchBend has no effect. A value of 1.0 means pitch bend corresponds to plus or minus a semitone. Larger values give larger pitch deviation. Default is 3.0.
waveform - WaveTable used for the oscillator. Defaults to sine. Note that the WaveTable you supply is normalized so that its peak amplitude is 1.0.
waveLen - Length of wavetable. Defaults to an optimal value. May only be set at the start of a phrase or with a noteUpdate that has no noteTag.
Member Function Documentation
| + (id) patchTemplateFor: | (MKNote *) | aNote |
Returns a default template.
- Parameters:
-
aNote is a (id)
- Returns:
- A (id) aNote is ignored.
Reimplemented from MKSynthPatch.
Reimplemented in Shapev.
| - (id) noteOnSelf: | (MKNote *) | aNote |
aNote is assumed to be a noteOn or noteDur.
- Parameters:
-
aNote is a (id)
- Returns:
- A (id) This method triggers (or retriggers) the MKNote's envelopes, if any. If this is a new phrase, all instance variables are set to default values, then the values are read from the MKNote.
Reimplemented from MKSynthPatch.
| - (id) noteUpdateSelf: | (MKNote *) | aNote |
aNote is assumed to be a noteUpdate and the receiver is assumed to be currently playing a MKNote.
- Parameters:
-
aNote is a (id)
- Returns:
- A (id) Sets parameters as specified in aNote.
Reimplemented from MKSynthPatch.
| - (double) noteOffSelf: | (MKNote *) | aNote |
aNote is assumed to be a noteOff.
- Parameters:
-
aNote is a (id)
- Returns:
- A (double) This method causes the MKNote's envelopes (if any) to begin its release portion and returns the time for the envelopes to finish. Also sets any parameters present in aNote.
Reimplemented from MKSynthPatch.
| - (id) noteEndSelf |
| - (id) preemptFor: | (MKNote *) | aNote |
Preempts envelope, if any.
- Parameters:
-
aNote is a (id)
- Returns:
- A (id)
Reimplemented from MKSynthPatch.
| - (id) init |
Sent by the MKOrchestra only when a new MKSynthPatch has just been created and before its MKUnitGenerator connections have been made, as defined by the MKPatchTemplate.
- Returns:
- Returns an id. A subclass may override the init method to provide additional initialization. A return of nil aborts the creation and frees the new MKSynthPatch. The default implementation does nothing and returns the receiver.
Reimplemented from MKSynthPatch.
The documentation for this class was generated from the following file:
