Unit generators - Programming for Musicians and Digital Artists: Creating music with ChucK (2015)

Programming for Musicians and Digital Artists: Creating music with ChucK (2015)

Appendix C. Unit generators

You’ve used many unit generators throughout this book, but we didn’t touch on all of them or on all of the things that UGens can do. This appendix lists all current ChucK UGens and the methods and variables available for you to access in using them.

In general, UGens deal with audio on a per-sample basis. This means that in a UGen connection such as

adc => Gain myGain => dac;

at each point, dac asks myGain for a sample, which in turn asks adc for a sample. The adc passes the most recent sample to myGain, which then scales it according to the set gain; then passes it to dac for output. Audio samples in ChucK have a nominal range of -1.0 to 1.0. They’re floats and can be any value, but before they reach the dac or WvOut for sound file writing, they should get back down to approximately the +/- 1.0 range.

For each UGen in this appendix, we list the methods that it implements. Most of these can be accessed by ChucKing a value to them, as in 0.3 => myGain.gain, or by using them in their function call form, like myGain.gain(0.3);. In most cases, using the function form with an empty argument causes the UGen to return that value, so <<< myGain.gain() >>> would print out the current gain of that UGen.

C.1. Audio input and output UGens

These special ChucK system UGens (dac, adc, and blackhole) are different from all others, in that they’re persistent (always exist as long as the VM is running), so you don’t have to make an instance of them. In fact, trying to execute SinOsc s => dac myDac; generates warnings. SinOsc s => dac is the proper way to use dac.

· dac— Digital-to-analog converter, abstraction for underlying audio output device.

o .left— Input to left channel output.

o .right— Input to right channel output.

o .chan(int n)—nth channel; all UGens obey this function.

· adc— Analog/digital converter, abstraction for underlying audio input device.

o .left— Input from left channel.

o .right— Input from right channel.

o .chan(int n)— Returns nth channel; all UGens obey this function.

· blackhole— Sample rate sample sucker (like dac, blackhole ticks UGens, but the samples aren’t heard; see section 6.1 for more details on using blackhole).

Because these UGens are always in existence, it’s a bad idea to modify their gain because that gain will persist as long as the VM runs, and other shreds might not be expecting that. Neither should you connect them directly (don’t do adc => dac), because they’re stuck there forever, as long as the VM runs. There are some other things you should likely not do with adc/dac, such as changing .op as described in the next section.

C.2. Methods common to all unit generators

Unit generators are designed to be connected together, so they all obey the ChucK operator, like this:

adc => Gain myGain => blackhole;

Once connected, UGens can be un-ChucKed like this:

myGain =< blackhole;

Some unit generators only yield samples of audio, so ChucKing to their input does nothing. Because Noise only generates noise, ChucKing something to its input isn’t necessary and doesn’t do anything if you do it anyway.

Other methods that all unit generators, where applicable, obey are these:

· .gain(float)— Sets gain; all UGens have this, can be any float value.

· .gain() (with no argument)— Returns current value of gain.

· .last()— Returns last sample output as a float.

· .channels()— Returns an integer, the number of channels output by the UGen, usually 1.

· .chan(int)— Returns a reference to the int-th channel of the UGen. Example: Noise n => dac.chan0; // connect to left or 0-th channel

· .op(int)— Changes relationship of inputs; the following are the available options:

o 0: Silence, stop, output 0.0 forever.

o 1: Add inputs (default).

o 2: Subtract all subsequent inputs from the first connected.

o 3: Multiply all inputs.

o 4: Divide all subsequent inputs into the first connected.

o -1: Passthrough, sum all inputs, output sum, don’t apply gain.

· .isConnectedTo(UGen otherUG)— Returns 1 if this UGen is connected to otherUG.

C.3. Gain and stereo/mono UGens

Even though every UGen obeys the .gain method, there is a Gain UGen dedicated to gain and other functions. As you learned early on in the book, making one or more common patches or mixing points out of Gain UGens is a useful thing.

· Gain— Gains control. Note: all unit generators can change their own gain. A Gain UGen provides a way to add N outputs together and scale them.

o .gain(float)— Sets gain. All UGens have this ability.

o .op(int)— Changes relationship of inputs: 1=add, 3=multiply.

Because by default everything ChucKed to a Gain sums together, it acts as a mixer, unless you use the .op method to change how Gain treats its inputs, as described previously. So if you wanted a make a patch that squares a signal (multiplies it by itself), you could do this:

adc => Gain mySquarer => blackhole; // so far so good

adc => mySquarer; // connect again

3 => mySquarer.op; // and set to multiply

These unit generators help in converting between stereo and mono UGen inputs/ outputs:

· Pan2— Spreads mono signal to stereo.

o .left(UGen)— Left (mono) channel out.

o .right(UGen)— Right (mono) channel out.

o .pan(float)— Pan location value (-1 to 1).

· Mix2— Mixes stereo input down to mono channel.

o .left(UGen)— Left (mono) channel in.

o .right(UGen)— Right (mono) channel in.

o .pan(float)— Mix parameter value (0 to 1).

C.4. Basic sound waves and function generator UGens

· Impulse— Pulse generator; default output is 0.0, unless you set the .next value.

o .next(float v)— Sets value of next sample to be generated. After one sample time has passed, the Impulse UGen outputs 0.0 again until .next is set.

· Step— Step generator; like Impulse, but once the .next value is set, it’s held for all following samples, until the value is set again.

o .next(float v)— Sets the step value to v.

· Noise— White noise generator, uncorrelated random samples (in range -1.0 to 1.0).

· SubNoise— STK subsampled noise generator. Generates a new random number with every integer-rate sample using the C rand() function. The quality of the rand() function varies from one OS to another.

o .rate(int)—subsampling rate

C.5. Oscillator unit generators

All Oscillator UGens obey the following methods:

· .freq(float)— Oscillator frequency (Hz), phase-matched.

· .sfreq(float)— Oscillator frequency (Hz).

· .phase(float)— Current phase.

· .sync(int)— (0) frequency sync, (1) phase sync, (2) fm synth.

· SinOsc— Sine wave oscillator.

o Obeys .freq, .sfreq, .phase, and .sync as described previously.

· TriOsc— Triangle wave oscillator.

o Obeys .freq, .sfreq, .phase, and .sync as described previously.

o .width(float)— Controls midpoint of triangle, 0 to 1 (0.5 default).

· SawOsc— Sawtooth wave oscillator.

o Obeys .freq, .sfreq, .phase, and .sync as described previously.

o .width(float)— Increasing (w > 0.5) or decreasing (w < 0.5).

· SqrOsc— Square wave oscillator (pulse with fixed width of 0.5).

o Obeys .freq, .sfreq, .phase, and .sync as described previously.

· PulseOsc— Pulse wave oscillator with variable width.

o Obeys .freq, .sfreq, .phase, and .sync as described previously.

o .width(float)— Length of duty cycle (0.0–1.0)

· Phasor— Simple ramp generator (range 0.0–1.0), can be used as a phase control for other oscillators/table UGens.

o Obeys .freq, .sfreq, .phase, and .sync as described previously.

o .width(float)— Sets duration of ramp in each cycle (default 1.0).

· Modulate— STK periodic/random modulator. This class combines random and periodic (sine) modulations to give a natural modulation function.

o .vibratoRate(float)— Sets rate of vibrato.

o .vibratoGain(float)— Gain for vibrato.

o .randomGain(float)— Gain for random contribution.

C.6. Lookup table unit generators

These UGens were all ported from RTcmix, by Brad Garton, Dave Topper, and others (after CMIX by Paul Lansky): www.music.columbia.edu/cmix/makegens.html.

The ChucK/RTcmix Lookup Table UGens are commonly used in one of two ways. The first is to drive them with a Phasor UGen, which ramps from 0.0 to 1.0 and repeats, essentially reading out the values in the table from beginning to end as a waveform, synchronous with the phasor cycle. The other way to use these is as a table lookup, using a Step UGen as input, or by using the .lookup() method. Input should range from 0.0 (beginning of the table) to 1.0 (end of table). Absolute value is used for inputs between -1.0 and 0.0. Note: currently coefficients past the 100th are ignored.

· GenX— Base class for classic MusicN lookup table unit generators.

o .lookup(float i) (float)— Returns lookup table value at index i [ -1, 1 ]; absolute value is used in the range [ -1, 0).

o .coefs(float[])— Sets lookup table coefficients; meaning is dependent on subclass.

· Gen5 extends GenX— Exponential line segment lookup table generator. Constructs a lookup table composed of sequential exponential curves. For a table with N curves, starting value of y’, and value yn for lookup index xn, set the coefficients to [y’, y0, x0, ..., yN-1, xN-1]. Note that there must be an odd number of coefficients. If an even number of coefficients is specified, the behavior is undefined. The sum of xn for 0 ≤ n < N must be 1. yn = 0 is approximated as 0.000001 to avoid strange results arising from the nature of exponential curves.

· Gen7 extends GenX— Line segment lookup table generator. Constructs a lookup table composed of sequential line segments. For a table with N lines, starting value of y’, and value yn for lookup index xn, set the coefficients to [y’, y0, x0, ..., yN-1, xN-1]. Note that there must be an odd number of coefficients. If an even number of coefficients is specified, behavior is undefined. The sum of xn for 0 ≤ n < N must be 1.

· Gen9 extends GenX— Additive sinusoidal lookup table with harmonic ratio, amplitude, and phase control. Constructs a lookup table of partials with specified amplitudes, phases, and harmonic ratios to the fundamental. Coefficients are specified in triplets of [ratio, amplitude, phase] arranged in a single linear array.

· Gen10 extends GenX— Sinusoidal lookup table with partial amplitude control and constructs a lookup table of harmonic partials with specified amplitudes. The amplitude of partial n is specified by the nth element of the coefficients. For example, setting coefs to [1] produces a sine wave.

· Gen17 extends GenX— Chebyshev polynomial lookup table. Constructs a Chebyshev polynomial wavetable with harmonic partials of specified weights. The weight of partial n is specified by the nth element of the coefficients. Primarily used for waveshaping, driven by a SinOsc instead of aPhasor.

· CurveTable extends GenX— Flexible curve/line segment table generator. Constructs a wavetable composed of segments of variable times, values, and curvatures. Coefficients are specified as a single linear array of triplets of [time, value, curvature] followed by a final duple of [time, value] to specify the final value of the table. Time values are expressed in unitless, ascending values. For curvature equal to 0, the segment is a line; for curvature less than 0, the segment is a convex curve; for curvature greater than 0, the segment is a concave curve.

C.7. LiSa: a live sampling unit generator

Dan Trueman really wanted to do live sampling, recording data from adc into a UGen on the fly, for immediate manipulation and playback. His creation of LiSa began in 2007, and this is the result. An internal buffer stores samples ChucKed to LiSa’s input. Segments of this buffer can be played back, with ramping and speed/direction control. Multiple voice facility is built in, allowing for a single LiSa object to serve as a source for sample layering and granular textures. See http://wiki.cs.princeton.edu/index.php/LiSa_examples for examples and http://dtrueman.mycpanel.prince-ton.edu/LiSa/LiSa_tutorial.html for a tutorial.

· LiSa— Live sampling utility.

o .duration(dur)— Sets buffer size; required to allocate memory; also resets all parameter values to default.

o .record(int)— Turns recording on and off.

o .getVoice()— Returns the voice number of the next available voice.

o .maxVoices(int)— Sets the maximum number of voices allowable, 10 by default; 200 is the current hardwired internal limit.

o .play(int, WRITE)— Turns on/off sample playback (voice 0).

o .play(int voice, int, WRITE)— For a particular voice (arg 1), turns on/off sample playback.

o .rampUp(dur, WRITE)— Turns on sample playback, with ramp (voice 0).

o .rampUp(int voice, dur, WRITE)— For a particular voice (arg 1), turns on sample playback, with ramp.

o .rampDown(dur, WRITE)— Turns off sample playback, with ramp (voice 0).

o .rampDown(int voice, dur, WRITE)— For a particular voice (arg 1), turns off sample playback, with ramp.

o .rate(float, WRITE)— Sets playback rate (voice 0). Note that the int/float type for this method will determine whether the rate is being set (float, for voice 0) or read (int, for voice number).

o .rate(int voice, float, WRITE)— For a particular voice (arg 1), sets playback rate.

o .rate()— Gets playback rate (voice 0).

o .rate(int voice, READ)— For a particular voice (arg 1), gets playback rate. Note that the int/float type for this method will determine whether the rate is being set (float, for voice 0) or read (int, for voice#).

o .playPos()— Gets playback position (voice 0).

o .playPos(int voice, READ)— For a particular voice (arg 1), gets playback position.

o .playPos(dur, WRITE)— Sets playback position (voice 0).

o .playPos(int voice, dur, WRITE)— For a particular voice (arg 1), sets playback position.

o .recPos(dur)— Gets/sets record position.

o .recRamp(dur)— Sets ramping when recording (from 0 to loopEndRec).

o .loopRec(int)— Turns on/off loop recording.

o .loopEndRec(dur)— Sets end point in buffer for loop recording.

o .loopStart(dur)— Sets loop starting point for playback (voice 0). Applicable only when 1 => loop.

o .loopStart(int voice, dur, WRITE)— For a particular voice (arg 1), sets loop starting point for playback. Applicable only when .loop(voice, 1).

o .loopEnd (dur)— Sets loop ending point for playback (voice 0). Applicable only when 1 => loop.

o .loopEnd(int voice, dur, WRITE)— For a particular voice (arg 1), sets loop ending point for playback. Applicable only when .loop(voice, 1).

o .loop(int)— Turns on/off looping (voice 0).

o .loop(int voice, int)— For a particular voice (arg 1), turns on/off looping.

o .bi(int)— Turns on/off bidirectional playback (voice 0).

o .bi(int voice, int, WRITE)— For a particular voice (arg 1), turns on/off bidirectional playback.

o .voiceGain(float)— Sets playback gain (voice 0).

o .voiceGain(int voice, float, WRITE)— For a particular voice (arg 1), sets gain.

o .feedback(float)— Gets/sets feedback amount when overdubbing (loop recording, how much to retain).

o .valueAt(dur, READ)— Gets value directly from record buffer.

o .valueAt(float, dur, WRITE)— Sets value directly in record buffer.

o .sync(int, READ/WRITE)— Sets input mode; (0) input is recorded to internal buffer:

§ Input sets playback position [0,1] (phase value between loopStart and loopEnd for all active voices).

§ Input sets playback position, interpreted as a time value in samples (works only with voice 0).

o .track(int, READ/WRITE)— Identical to sync.

o .clear— Clears recording buffer.

C.8. STK Envelope generators

· Envelope— STK envelope base class. Simple envelope generator that’s capable of ramping to .target value by a specified .time or duration or at a specified rate. Also responds to simple .keyOn (ramps to 1.0) and .keyOff (ramps to 0.0) messages.

o .keyOn(int, WRITE only)— Ramps to 1.0.

o .keyOff(int, WRITE only)— Ramps to 0.0.

o .target(float)— Ramps to arbitrary value.

o .time(float)— Sets time to reach target (in seconds).

o .duration(dur)— Sets duration to reach target.

o .rate(float)— Sets rate of change.

o .value(float)— Sets immediate value.

· ADSR extends Envelope— STK Attack Decay Sustain Release envelope class.

o Responds to simple .keyOn and .keyOff messages, keeping track of its state. The state = ADSR.DONE after the envelope value reaches 0.0 in the ADSR .RELEASE state.

o .keyOn(int, WRITE only)— Starts the attack for non-zero values.

o .keyOff(int, WRITE only)— Starts release for non-zero values.

o .attackTime(dur)— Sets attack time.

o .attackRate(float)— Sets attack rate.

o .decayTime(dur)— Sets decay time.

o .decayRate(float)— Sets decay rate.

o .sustainLevel(float)— Sets sustain level.

o .releaseTime(dur)— Sets release time.

o .releaseRate(float)— Sets release rate.

o .state(int, READ only)— Attack: 0, Decay: 1, Sustain: 2, Release: 3, Done: 4.

o .set(dur, dur, float, dur)— Set A, D, S, and R all at once.

C.9. STK delays, reverberators, and delay-based effects

· Delay— STK non-interpolating delay line class.

o .delay(dur)— Length of delay (default is 0).

o .max(dur)— Max delay (buffer size, default is 4095).

· DelayA— STK allpass interpolating delay line class.

o .delay(dur)— Length of delay (default is 0.5 samples).

o .max(dur)— Max delay (buffer size, default is 4095).

· DelayL— STK linear interpolating delay line class.

o .delay(dur)— Length of delay (default is 0).

o .max(dur)— Max delay (buffer size, default is 4095).

· Echo— STK echo effect class.

o .delay(dur)— Length of echo.

o .max(dur)— Max delay.

o .mix(float)— Mix level (wet/dry).

· PRCRev— Perry’s way-simple reverberator class. This class is based on some of the famous Stanford/CCRMA reverbs (NRev, JCRev, KipRev), which were based on the Chowning/Moorer/Schroeder reverberators using networks of simple allpass and comb delay filters. This class implements two series allpass units and two parallel comb filters.

o .mix(float)— Mix level.

· JCRev— John Chowning’s reverberator class. This reverb is implemented using three allpass filters in series, followed by four parallel comb filters, and two decor-relation delay lines in parallel at the output.

o .mix(float)— Mix level.

· NRev— CCRMA’s NRev (we think this means New) reverberator class. This reverb consists of six comb filters in parallel, followed by three allpass filters, a low-pass filter, and another allpass in series, followed by two allpass filters in parallel with corresponding right and left outputs.

o .mix(float)— Mix level.

· Chorus— STK chorus effect class. Implements a chorus effect using time-varying delay lines.

o .modFreq(float)— Modulation frequency.

o .modDepth(float)— Modulation depth.

o .mix(float)— Effect mix.

· PitShift— STK simple pitch shifter effect class. This class implements a simple pitch shifter using time-varying, overlapping, cross-fading, delay lines.

o .mix(float)— Effect dry/web mix level.

o .shift(float)— Amount of pitch shift (1.0: normal, .5: octave down, 2: octave up, ...).

C.10. Sound file unit generators

· SndBuf— Sound buffer (interpolating). Reads a variety of uncompressed audio file formats.

o .read(string, WRITE only)— Loads file for reading.

o .chunks(int)— Size of chunk (# of frames) to read on demand; 0 implies entire file, default; must be set before reading to take effect.

o .samples(int, READ only)— Gets total file size in samples.

o .length(dur, READ only)— Gets length as duration.

o .channels(int, READ only)— Gets number of channels.

o .pos(int)— Sets position (0 < p < .samples).

o .rate(float)— Sets/gets playback rate (relative to file’s natural speed).

o .interp(int)— Sets/gets interpolation (0=drop, 1=linear, 2=sinc).

o .loop(int)— Toggles looping.

o .freq(float)— Sets/gets loop rate (file loops/second).

o .phase(float)— Sets/gets phase position (0–1).

o .channel(int)— Sets/gets channel (0 < p < .channels).

o .phaseOffset(float)— Sets/gets a phase offset.

· SndBuf2— Stereo sound buffer (interpolating). Reads a variety of uncompressed audio file formats. If loaded with a stereo file, connecting to dac connects left to left, right to right. All previous methods, plus:

o .chan(int)— Returns mono UGen for the channel specified by int.

· WvIn— STK audio data input base class. Provides (different from SndBuf, primarily for legacy compatibility) input support for various audio file formats.

o .rate(float)— Playback rate.

o .path(string)— Specifies file to be played.

· WaveLoop extends WvIn— STK waveform oscillator class. Provides audio file looping functionality.

o .freq(float)— Sets frequency of playback (loops/second, not necessarily pitch!).

o .addPhase(float)— Offset by phase.

o .addPhaseOffset(float)— Sets phase offset.

· WvOut— STK audio data output base class. Allows for sound file writing.

o .matFilename(string, WRITE only)— Opens MATLAB file for writing.

o .sndFilename(string, WRITE only)— Opens snd file for writing.

o .wavFilename(string, WRITE only)— Opens WAVE file for writing.

o .rawFilename(string, WRITE only)— Opens raw file for writing.

o .aifFilename(string, WRITE only)— Opens AIFF file for writing.

o .fileGain(float)— Gain applied to samples before writing to file (different from .gain).

o .closeFile()— Closes file properly.

· WvOut2— Stereo version of STK audio data output base class. For sound file writing.

C.11. Synthesis ToolKit filters

· OnePole— STK one-pole filter class, implements y(n) = b0*x(n) + a1*y(n-1). A method is provided for setting the pole position along the real axis of the z-plane while maintaining a constant peak filter gain.

o .a1(float)— Filter coefficient.

o .b0(float)— Filter coefficient.

o .pole(float)— Sets pole position along real axis of z-plane; maintains constant maximum gain.

· TwoPole— STK two-pole filter class, implements y(n) = b0*x(n) + a1*y(n-1) + a2*y(n-2).

o .a1(float)— Filter coefficient.

o .a2(float)— Filter coefficient.

o .b0(float)— Filter coefficient.

o .freq(float)— Filter resonance frequency.

o .radius(float)— Filter resonance radius.

o .norm(int)— Toggles filter auto-normalization.

· OneZero— STK one-zero filter class. A method is provided for setting the zero position along the real axis of the z-plane while maintaining a constant max filter gain.

o .zero(float)— Sets zero position.

o .b0(float)— Filter coefficient.

o .b1(float)— Filter coefficient.

· TwoZero— STK two-zero filter class, implements y(n) = b0*x(n)+b1*y(n-1)+b2* y(n-1).

o .b0(float)— Filter coefficient.

o .b1(float)— Filter coefficient.

o .b2(float)— Filter coefficient.

o .freq(float)— Filter notch frequency.

o .radius(float)— Filter notch radius.

· PoleZero— STK one-pole, one-zero filter class, implements y(n) = b0*x(n)+b1* y(n-1)-a1*x(n-1).

o .a1(float)— Filter coefficient.

o .b0(float)— Filter coefficient.

o .b1(float)— Filter coefficient.

o .blockZero(float)— DC blocking filter with given pole position.

o .allpass(float)— Allpass filter with given coefficient.

· BiQuad— STK biquad (two-pole, two-zero) filter class. Implements a0*y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2]- a1*y[n-1] - a2*y[n-2]. Can access raw coefficients or freq/radius for poles and zeroes. A method is provided (.eqzs) for creating a resonance in the frequency response while maintaining a (roughly) constant filter gain.

o .b2(float)—b2 coefficient.

o .b1(float)—b1 coefficient.

o .b0(float)—b0 coefficient.

o .a2(float)—a2 coefficient.

o .a1(float)—a1 coefficient.

o .a0(float, READ only)—a0 coefficient (used for normalization).

o .pfreq(float, READ/WRITE)— Sets resonance frequency (poles).

o .prad(float)— Pole radius (less than 1 to be stable).

o .zfreq(float)— Notch frequency.

o .zrad(float)— Zero radius.

o .norm(float)— Normalization.

o .eqzs(float)— Equal gain zeroes.

· FilterBasic— Base/parent class for the next few filters, which are all special BiQuads. You don’t use one of these by itself, only subclasses.

o .freq(float)— Cutoff/center frequency.

o .Q(float)— Resonance (default is 1).

o .set(float, float)— Sets freq and Q at once.

· LPF extends FilterBasic— Resonant low-pass filter. 2nd order Butterworth.

o .freq, .Q, and .set as described previously.

· HPF extends FilterBasic— Resonant high-pass filter. 2nd order Butterworth.

o .freq, .Q, and .set as described previously.

· BPF extends FilterBasic— Band-pass filter. 2nd order Butterworth.

o .freq, .Q, and .set as described previously.

· BRF extends FilterBasic— Band-reject filter. 2nd order Butterworth.

o .freq, .Q, and .set as described previously.

· ResonZ extends FilterBasic— Resonance filter. BiQuad with equal-gain zeroes.

o .freq, .Q, and .set as described previously.

C.12. Non-linear signal-processing UGens

· HalfRect— Half-wave rectifier (only allows samples >= 0.0 through, blocks negative).

· FullRect— Full-wave rectifier (passes absolute value of all samples).

· ZeroX— Zero crossing detector. Emits a single pulse at zero crossings, in the direction of the zero crossing. Outputs +1.0 when signal crosses from negative to positive, and -1 for xing in other direction.

· Dyno— Dynamics processor. Includes presets for limiter, compressor, expander, noise gate, and ducker. Default is a hard-limiter (limiter with zero attack/release times).

o .limit()— Sets parameters to default limiter values:

-

slopeAbove = 0.1

slopeBelow = 1.0

thresh = 0.5

-

attackTime = 5 ms

releaseTime = 300 ms

externalSideInput = false

o .compress()— Sets parameters to default compressor values:

-

slopeAbove = 0.5

slopeBelow = 1.0

thresh = 0.5

-

attackTime = 5 ms

releaseTime = 300 ms

externalSideInput = false

o .expand()— Sets parameters to default expander values:

-

slopeAbove = 2.0

slopeBelow = 1.0

thresh = 0.5

-

attackTime = 20 ms

releaseTime = 400 ms

externalSideInput = false

o .gate()— Sets parameters to default noise gate values:

-

slopeAbove = 1.0

slopeBelow = 10000000

thresh = 0.1

-

attackTime = 11 ms

releaseTime = 100 ms

externalSideInput = false

o .duck()— Sets parameters to default ducker values:

-

slopeAbove = 0.5

slopeBelow = 1.0

thresh = 0.1

-

attackTime = 100 ms

releaseTime = 1000 ms

-

externalSideInput = true

o Note that the input to sideInput determines the level of gain, not the direct signal input to Dyno.

o .thresh(float)— The point above which to stop using slopeBelow and start using slopeAbove to determine output gain versus input gain.

o .attackTime(dur)— Duration for the envelope to move linearly from current value to the absolute value of the signal’s amplitude.

o .releaseTime(dur)— Duration for the envelope to decay down to around 1/10 of its current amplitude, if not brought back up by the signal.

o .ratio(float)— Alternate way of setting slopeAbove and slopeBelow; sets slopeBelow to 1.0 and slopeAbove to 1.0/ratio.

o .slopeBelow(float)— Determines the slope of the output gain versus the input envelope’s level in dB when the envelope is below thresh. In general, setting slopeBelow to be lower than slopeAbove results in expansion of dynamic range.

o .slopeAbove(float)— Determines the slope of the output gain versus the input envelope’s level in dB when the envelope is above thresh. In general, setting slopeAbove to be lower than slopeBelow results in compression of dynamic range.

o .sideInput(float)— If externalSideInput is set to true, replaces the signal being processed as the input to the amplitude envelope. See dynoduck.ck for an example of using an external side chain.

o .externalSideInput(int)— Set to true to cue the amplitude envelope off of sideInput instead of the input signal. Note that this means you’ll need to manually set sideInput every so often. If false, the amplitude envelope represents the amplitude of the input signal whose dynamics are being processed. See dynoduck.ck for an example of using an external side chain.

C.13. STK instruments

· StkInstrument (imported from Instrmnt)— Superclass for STK instruments.

o .noteOn(float velocity)— Triggers note on.

o .noteOff(float velocity)— Triggers note off.

o .freq(float frequency)— Sets/gets frequency (Hz).

o .controlChange(int number, float value)— Instrument specific, range: [0.0–128.0].

· Clarinet extends StkInstrument— STK clarinet physical model class. Implements a simple clarinet physical model, as discussed by Smith (1986), McIntyre, Schumacher, Woodhouse (1983), and others.

o .reed(float)— Reed stiffness [0.0–1.0].

o .noiseGain(float)— Noise component gain [0.0–1.0].

o .clear()— Clears instrument.

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .pressure(float)— Pressure/volume [0.0–1.0].

o .startBlowing(float, WRITE only)— Starts blowing [0.0–1.0].

o .stopBlowing(float, WRITE only)— Stops blowing [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange

o Control change numbers:

-

Reed Stiffness = 2

Noise Gain = 4

Vibrato Frequency = 11

-

Vibrato Gain = 1

Breath Pressure = 128

· BlowBotl extends StkInstrument— STK blown pop-bottle instrument class. This class implements a Helmholtz resonator (biquad filter) with a polynomial jet excitation (see Cook, Real Sound Synthesis for Interactive Applications [A K Peters/CRC Press, 2002]).

o .noiseGain(float)— Noise component gain [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .volume(float)— Yet another volume knob [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o .startBlowing(float, WRITE only)— Starts blowing [0.0–1.0].

o .stopBlowing(float, WRITE only)— Stops blowing [0.0–1.0].

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Noise Gain = 4

Vibrato Frequency = 11

Vibrato Gain = 1

-

Volume = 128

· Flute extends StkInstrument— STK flute physical model class. Implements a simple flute physical model, as discussed by Karjalainen, Smith, Waryznyk, etc. The jet model uses a polynomial jet, a la Cook.

o .jetDelay(float)— Jet delay [...].

o .jetReflection(float)— Jet reflection [...].

o .endReflection(float)— End delay [...].

o .noiseGain(float)— Noise component gain [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .pressure(float)— Pressure/volume [0.0–1.0].

o .clear()— Clear instrument.

o .startBlowing(float, WRITE only)— Start blowing [0.0–1.0].

o .stopBlowing(float, WRITE only)— Stop blowing [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange

o Control change numbers:

-

Jet Delay = 2

Noise Gain = 4

Vibrato Frequency = 11

-

Vibrato Gain = 1

Breath Pressure = 128

· BlowHole extends StkInstrument— STK clarinet physical model with a two-port register hole and a three-port dynamic tonehole implementation, as discussed by Scavone and Cook (1998).

o .reed(float)— Reed stiffness [0.0–1.0].

o .noiseGain(float)— Noise component gain [0.0–1.0].

o .tonehole(float)— Tonehole size [0.0–1.0].

o .vent(float)— Vent frequency [0.0–1.0].

o .pressure(float)— Pressure [0.0–1.0].

o .startBlowing(float, WRITE only)— Start blowing [0.0–1.0].

o .stopBlowing(float, WRITE only)— Stop blowing [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Reed Stiffness = 2

Noise Gain = 4

Tonehole State = 11

-

Register State = 1

Breath Pressure = 128

· Saxofony extends StkInstrument— STK faux conical bore reed instrument class. Hybrid digital waveguide instrument that can generate a variety of wind-like sounds. Also called the blowed string. Essentially a string with one rigid end and one lossy (filter) end. The non-linear function is a reed table, but the string can be blown at any point between the terminations. If the excitation is placed at the string midpoint, the sound is that of a clarinet. Closer to the bridge, the sound is closer to that of a saxophone.

o .stiffness(float)— Reed stiffness [0.0–1.0].

o .aperture(float)— Reed aperture [0.0–1.0].

o .pressure(float)— Pressure/volume [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .noiseGain(float)— Noise component gain [0.0–1.0].

o .blowPosition(float)— Lip stiffness [0.0–1.0].

o .clear()— Clear instrument.

o .startBlowing(float, WRITE only)— Start blowing [0.0–1.0].

o .stopBlowing(float, WRITE only)— Stop blowing [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Reed Stiffness = 2

Reed Aperture = 26

Noise Gain = 4

-

Blow Position = 11

Vibrato Frequency = 29

Vibrato Gain = 1

-

Breath Pressure = 128

· Brass extends StkInstrument— STK simple brass instrument class. Implements a simple brass instrument waveguide model (a la Cook, TBone ICMC 1991 and HosePlayer, ICMC 1992).

o .lip(float)— Lip tension [0.0–1.0].

o .slide(float)— Slide length [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .volume(float)— Volume [0.0–1.0].

o .clear(float, WRITE only)— Clear instrument.

o .startBlowing(float, WRITE only)— Start blowing [0.0–1.0].

o .stopBlowing(float, WRITE only)— Stop blowing [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Lip Tension = 2

Slide Length = 4

Vibrato Frequency = 11

-

Vibrato Gain = 1

Volume = 128

· Bowed extends StkInstrument— STK bowed string instrument class. Implements a bowed string model, a la Smith (1986), after McIntyre, Schumacher, Woodhouse (1983).

o .bowPressure(float)— Bow pressure [0.0–1.0].

o .bowPosition(float)— Bow position [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .volume(float)— Volume [0.0–1.0].

o .startBowing(float, WRITE only)— Start bowing [0.0–1.0].

o .stopBowing(float, WRITE only)— Stop bowing [0.0–1.0].

o .rate(float)— Rate of attack (sec).

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Bow Pressure = 2

Bow Position = 4

Vibrato Frequency = 11

-

Vibrato Gain = 1

Volume = 128

· StifKarp extends StkInstrument— STK plucked stiff string instrument. Implements a simple plucked string algorithm (Karplus-Strong) with enhancements (Jaffe-Smith, Smith, and others), including string stiffness (allpass filters) and pluck position controls.

o .pickupPosition(float)— Pickup position [0.0–1.0].

o .sustain(float)— String sustain [0.0–1.0].

o .stretch(float)— String stretch [0.0–1.0].

o .pluck(float, WRITE only)— Pluck string [0.0–1.0].

o .baseLoopGain(float)— Frequency-independent gain of the feedback loop [0.0–1.0].

o .clear()— Reset instrument.

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange. Control change numbers:

-

Pickup Position = 4

String Sustain = 11

String Stretch = 1

· Sitar extends StkInstrument— STK sitar string model class. Implements a sitar plucked string physical model based on the Karplus-Strong algorithm.

o .pluck(float, WRITE only)— Pluck string [0.0–1.0].

o .clear()— Reset.

o Inherited from StkInstrument: .noteOn, .noteOff, .freq.

o No available control changes.

· Mandolin extends StkInstrument— STK mandolin instrument model class. Uses commuted synthesis techniques to model a mandolin.

o .bodySize(float)— Body size (percentage).

o .pluckPos(float)— Pluck position [0.0–1.0].

o .stringDamping(float)— String damping [0.0–1.0].

o .stringDetune(float)— Detuning of string pair [0.0–1.0].

o .afterTouch(float, WRITE only)— Aftertouch (currently unsupported).

o .pluck(float, WRITE only)— Pluck instrument [0.0–1.0].

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Body Size = 2

Pluck Position = 4

String Sustain = 11

-

String Detuning = 1

Microphone Position = 128

· ModalBar extends StkInstrument— STK resonant bar instrument class.

o .stickHardness(float)— Stick hardness [0.0–1.0].

o .strikePosition(float)— Strike position [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .directGain(float)— Direct gain [0.0–1.0].

o .masterGain(float)— Master gain [0.0–1.0].

o .volume(float)— Volume [0.0–1.0].

o .preset(int)— Choose preset (see below).

o .strike(float, WRITE only)— Strike bar [0.0–1.0].

o .damp(float, WRITE only)— Damp bar [0.0–1.0].

o .clear()— Reset [none].

o .mode(int)— Select mode [0.0–1.0].

o .modeRatio(float)— Edit selected mode ratio [...].

o .modeRadius(float)— Edit selected mode radius [0.0–1.0].

o .modeGain(float)— Edit selected mode gain [0.0–1.0].

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Stick Hardness = 2

Tick Position = 4

Vibrato Gain = 11

-

Vibrato Frequency = 7

Direct Stick Mix = 1

Volume = 128

o Modal presets = 1 (.preset arguments)

-

Marimba = 0

Vibraphone = 1

Agogo = 2

Wood1 = 3

Reso = 4

-

Wood2 = 5

Beats = 6

Two Fixed = 7

Clump = 8

· BandedWG extends StkInstrument— Banded waveguide modeling class. For more information, see Essl and Cook, ICMC 1999.

o .bowPressure(float)— Bow pressure [0.0–1.0].

o .bowMotion(float)— Bow motion [0.0–1.0].

o .bowRate(float)— Bow attack rate (sec).

o .strikePosition(float)— Strike position [0.0–1.0].

o .integrationConstant(float)— A cool non-physical parameter [0.0–1.0].

o .modesGain(float)— Amplitude for modes [0.0–1.0].

o .preset(int)— Instrument presets (0–3, see Control change below).

o .pluck(float, WRITE only)— Pluck instrument [0.0–1.0].

o .startBowing(float, WRITE only)— Start bowing [0.0–1.0].

o .stopBowing(float, WRITE only)— Stop bowing [0.0–1.0].

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Bow Pressure = 2

Bow Motion = 4

Strike Position = 8 (not implemented)

-

Vibrato Frequency = 11

Gain = 1

Bow Velocity = 128

-

Set Striking = 64

o Instrument Presets = 16

-

Uniform Bar = 0

Tuned Bar = 1

Glass Harmonica = 2

-

Tibetan Bowl = 3

· Moog extends StkInstrument— STK analog swept filter synthesis class. Uses one attack wave, one looped wave, and an ADSR envelope and adds two sweepable formant (FormSwep) filters.

o .filterQ(float)— Filter Q value [0.0–1.0].

o .filterSweepRate(float)— Filter sweep rate [0.0–1.0].

o .vibratoFreq(float)— Vibrato frequency (Hz).

o .vibratoGain(float)— Vibrato gain [0.0–1.0].

o .afterTouch(float, WRITE only)— Aftertouch [0.0–1.0].

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Filter Q = 2

Filter Sweep Rate = 4

Vibrato Frequency = 11

-

Vibrato Gain = 1

Gain = 128

· Shakers extends StkInstrument —PhISEM and PhOLIES (particle models) class. PhISEM (Physically Informed Stochastic Event Modeling) is a statistical algorithmic approach for simulating collisions of multiple independent sound producing objects. This class is a meta-model that can simulate a maraca, sekere, cabasa, bamboo wind chimes, water drops, tambourine, sleigh bells, and a guiro. PhOLIES (Physically-Oriented Library of Imitated Environmental Sounds) is a similar approach for the synthesis of environmental sounds. This class implements simulations of breaking sticks, crunchy snow (or not), a wrench, sandpaper, and more.

o .preset(int)— Select instrument (0–22; see below).

o .energy(float)— Shake energy [0.0–1.0].

o .decay(float)— System decay [0.0–1.0].

o .objects(float)— Number of objects [0.0–128.0].

o Inherited from StkInstrument: .noteOn, .noteOff, .freq, .controlChange.

o Control change numbers:

-

Shake Energy = 2

System Decay = 4

Number Of Objects = 11

-

Resonance Frequency = 1

Shake Energy = 128

o Instrument selection = 1071

-

Maraca = 0

Cabasa = 1

Sekere = 2

-

Guiro = 3

Water Drops = 4

Bamboo Chimes = 5

-

Tambourine = 6

Sleigh Bells = 7

Sticks = 8

-

Crunch = 9

Wrench = 10

Sand Paper = 11

-

Coke Can = 12

Next Mug = 13

Penny + Mug = 14

-

Nickle + Mug = 15

Dime + Mug = 16

Quarter + Mug = 17

-

Franc + Mug = 18

Peso + Mug = 19

Big Rocks = 20

-

Little Rocks = 21

Tuned Bamboo Chimes = 22

· FM extends StkInstrument— STK abstract FM synthesis base class. This class controls an arbitrary number (usually four) of waves and envelopes, determined via a constructor argument.

o .lfoSpeed(float)— Modulation Speed (Hz).

o .lfoDepth(float)— Modulation Depth [0.0–1.0].

o .afterTouch(float)— Aftertouch [0.0–1.0].

o .controlOne(float)— Control one [instrument specific].

o .controlTwo(float)— Control two [instrument specific].

o Inherited from StkInstrument—.noteOn, .noteOff, .freq, .controlChange

o Control change numbers:

-

Control One = 2

Control Two = 4

LFO Speed = 11

-

LFO Depth = 1

ADSR 2 & 4 Target = 128

· BeeThree extends FM— STK Hammond-oid organ FM synthesis instrument. This class implements a simple four-operator topology, also referred to as algorithm 8 (simple additive) of the TX81Z.

o Control parameters: See super classes

o Control change numbers:

-

Operator 4 (feedback) Gain = 2 (.controlOne)

-

Operator 3 Gain = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

· HevyMetl extends FM —STK heavy metal FM synthesis instrument. This class implements three cascade operators with feedback modulation, also referred to as algorithm 3 of the TX81Z.

o Control parameters: See super classes

o Control change numbers:

-

Total Modulator Index = 2 (.controlOne)

-

Modulator Crossfade = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

· PercFlut extends FM— STK percussive flute FM synthesis instrument. This class implements algorithm 4 of the TX81Z.

o Control parameters: See super classes

o Control change numbers:

-

Total Modulator Index = 2 (.controlOne)

-

Modulator Crossfade = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

· Rhodey extends FM— STK Fender Rhodes-like FM electric piano. This class implements two simple FM pairs summed together, also referred to as algorithm 5 of the TX81Z.

o Control parameters: See super classes

o Control change numbers:

-

Modulator Index One = 2 (.controlOne)

-

Crossfade of Outputs = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

· TubeBell extends FM— STK FM synthesis tubular bell (orchestral chime) FM. This class implements two simple FM pairs summed together, also referred to as algorithm 5 of the TX81Z.

o Control parameters: See super classes

o Control change numbers:

-

Modulator Index One = 2 (.controlOne)

-

Crossfade of Outputs = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

· Wurley extends FM— STK FM Wurlitzer electric piano synthesis. This class implements two simple FM pairs summed together, also referred to as algorithm 5 of the TX81Z.

o Control parameters: See super classes

o Control change numbers:

-

Modulator Index One = 2 (.controlOne)

-

Crossfade of Outputs = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

· FMVoices extends FM— STK singing FM synthesis instrument. This class implements three carriers sharing a common modulator, also referred to as algorithm 6 of the TX81Z.

o Control parameters: See super classes, plus

o .vowel(float, WRITE only)— Select vowel [0.0–1.0].

o .spectralTilt(float, WRITE only)— Spectral tilt [0.0–1.0].

o .adsrTarget(float, WRITE only)—ADSR targets [0.0–1.0].

o Control change numbers:

-

Vowel = 2 (.controlOne)Spectral Tilt = 4 (.controlTwo)

-

LFO Speed = 11

LFO Depth = 1

ADSR 2 & 4 Target = 128

o VoicForm extends StkInstrument— Four formant filter voice synthesis instrument. This instrument contains an excitation singing wavetable (looping wave with random and periodic vibrato, smoothing on frequency, etc.), excitation noise, and four sweepable resonances. Measured formant data presets are included.

§ Control parameters:

§ .phoneme(string)— Select phoneme (see previous).

§ Phoneme names:

§ "eee" "ihh" "ehh" "aaa" "ahh" "aww" "ohh" "uhh"

§ "uuu" "ooo" "rrr" "lll" "mmm" "nnn" "nng" "ngg"

§ "fff" "sss" "thh" "shh" "xxx" "hee" "hoo" "hah"

§ "bbb" "ddd" "jjj" "ggg" "vvv" "zzz" "thz" "zhh"

§ .phonemeNum(int)— Select phoneme by number [0.0 - 128.0].

§ .speak(float, WRITE only)— Start singing [0.0–1.0].

§ .quiet(float, WRITE only)— Stop singing [0.0–1.0].

§ .voiced(float)— Set mix for voiced component [0.0–1.0].

§ .unVoiced(float)— Set mix for unvoiced component [0.0–1.0].

§ .pitchSweepRate(float)— Pitch sweep [0.0–1.0].

§ .voiceMix(float)— Voiced/unvoiced mix [0.0–1.0].

§ .vibratoFreq(float)— Vibrato frequency (Hz).

§ .vibratoGain(float)— Vibrato gain [0.0–1.0].

§ .loudness(float)— Loudness of voice [0.0–1.0].

§ Inherited from StkInstrument—.noteOn, .noteOff, .freq, .controlChange

§ Control change numbers:

-

Voiced/Unvoiced Mix = 2

Vowel/Phoneme Selection = 4

-

Vibrato Frequency = 11

Vibrato Gain = 1

-

Loudness (Spectral Tilt) = 128

C.14. Blit: band-limited oscillator family

This class generates band-limited waveforms (impulse Train, sawtooth, etc.) using a closed-form algorithm reported by Stilson and Smith in “Alias-Free Digital Synthesis of Classic Analog Waveforms,” 1996. The user can specify both the fundamental frequency of the impulse train and the number of harmonics contained in the resulting signal. If .harmonics is 0, then the signal will contain all harmonics up to half the sample rate. Note that this setting may produce aliasing in the signal when the frequency is changing (no automatic modification of the number of harmonics is performed by freq()).

All Blit family oscillators support the following methods:

· .freq(float)— Base frequency (Hz).

· .harmonics(int)— Number of harmonics in pass band.

· .phase(float)— Phase of the signal.

The Blit family of oscillators consists of the following UGens:

· Blit— STK band-limited impulse train.

· BlitSaw— STK band-limited sawtooth wave.

· BlitSquare— STK band-limited square wave.