/chapter: Unit-Generators / ChucK

ChucK

Unit Generators

Unit generators (ugens) can be connected using the ChucK operator ( => )

adc => dac;

the above connects the ugen `adc' (a/d convertor, or audio input) to `dac' (d/a convertor, or audio output).

Ugens can also unlinked (using =<) and relinked (see examples/unchuck.ck).

A unit generator may have 0 or more control parameters. A Ugen's parameters can be set also using the ChucK operator (=>, or ->)

//connect sine oscillator to dac
SinOsc osc => dac;
// set the Osc's frequency to 60.0 hz
60.0 => osc.freq;

(see examples/osc.ck)

All ugen's have at least the following four parameters:

.gain - (float, READ/WRITE) - set gain.
.op - (int, READ/WRITE) - set operation type

0: stop - always output 0.
1: normal operation, add all inputs (default).
2: normal operation, subtract all inputs starting from the earliest connected.
3: normal operation, multiply all inputs.
4 : normal operation, divide inputs starting from the earlist connected.
-1: passthru - all inputs to the ugen are summed and passed directly to output.

.last - (float, READ/WRITE) - returns the last sample computed by the unit generator as a float.
.channels - (int, READ only) - the number channels on the UGen
.chan - (int) - returns a reference on a channel (0 -N-1)
.isConnectedTo( Ugen ) returns 1 if the unit generator connects to the argument, 0 otherwise.

Multichannel UGens are adc, dac, Pan2, Mix2

Pan2 p;    
// assumes you called chuck with at least --chan5 or -c5    
p.chan(1) => dac.chan(4);

Audio output

dac

Digital -> analog converter abstraction for underlying audio output device

.left - (UGen) - input to left channel
.right - (UGen) - input to right channel
.chan( int n ) - (UGen) - input to channel N on the device (0 -N-1)
.channels - (int, READ only) - returns the number of channels open on device

adc

Analog -> digital converter abstraction for underlying audio input device. Note that this is system-wide and so all outputs can be read from as well, for example to record the signals that ChucK is generating to a wave file.

.left - (UGen) - output to left channel
.right - (UGen) - output to right channel
.chan( int n ) - (UGen) - output to channel N on the device (0 -N-1)
.channels - (int, READ only) - returns the number of channels open on device

blackhole

Sample rate sample sucker ( like dac it ticks ugens, but no more ). Useful for generating modulation signals that aren't ever send to the soundcard. While it is system-wide like dac it can't be read from; it's output will always be zero.

see examples/pwm.ck

UGen

Utility class that all other ugens inherit from. Useful in some cases to abstract sets of ugen types.

waveforms

Impulse

Pulse generator - can set the value of the next sample. Default for each sample is 0 if not set

.next - (float, READ/WRITE) - set value of next sample

see examples/impulse_example.ck

Step

Step generator - like Impulse, but once a value is set, it is held for all following samples, until the value is set again

.value - (float, READ/WRITE) - set the current value
.next - (float, READ/WRITE) - set the step value examples/step_example.ck

see examples/step.ck

basic signal processing

Gain

Gain control (NOTE - all unit generators can themselves change their gain) (this is a way to add N outputs together and scale them). Gain is in fact identical in function to the UGen mother class that all other UGens extend.

.gain - (float, READ/WRITE) - set gain ( all ugen's have this) examples/gain_example.ck

Used in examples/i-robot.ck

HalfRect

Half wave rectifier for half-wave rectification. Only passes the signal if it's values positive, outputs zero otherwise

FullRect

Full wave rectifier. Transparent for positive input values, inverts negative ones.

ZeroX

Zero crossing detector. Emits a pulse lasting a single sample at the the zero crossing in the direction of the zero crossing.

(see examples/zerox.ck)

filters

Before using filters in ChucK, for the sake of your ears and your speakers, please read the following thread http://www.electro-music.com/forum/topic-37921.html

BiQuad

BiQuad (two-pole, two-zero) filter class. examples/ugen/BiQuad.txt

.b2 (float, READ/WRITE) filter coefficient
.b1 (float, READ/WRITE) filter coefficient
.b0 (float, READ/WRITE) filter coefficient
.a2 (float, READ/WRITE) filter coefficient
.a1 (float, READ/WRITE) filter coefficient
.a0 (float, READ only) filter coefficient
.pfreq (float, READ/WRITE) set resonance frequency (poles)
.prad (float, READ/WRITE) pole radius (<= 1 to be stable)
.zfreq (float, READ/WRITE) notch frequency
.zrad (float, READ/WRITE) zero radius
.norm (float, READ/WRITE) normalization
.eqzs (float, READ/WRITE) equal gain zeroes

BPF

Band pass filter. 2nd order Butterworth. (In the future, this class may be expanded so that order and type of filter can be set.) extends FilterBasic

.freq (float, READ/WRITE) center frequency (Hz)
.Q (float, READ/WRITE) Q (default is 1)
.set (float, float WRITE only) set freq and Q

BRF

Band reject filter. 2nd order Butterworth. (In the future, this class may be expanded so that order and type of filter can be set.) extends FilterBasic

.freq (float, READ/WRITE) center frequency (Hz)
.Q (float, READ/WRITE) Q (default is 1)
.set (float, float WRITE only) set freq and Q

Filter

STK filter class.

.coefs (string, WRITE only)

examples/ugen/Filter.txt

FilterBasic

base class, don't instantiate.

.freq (float, READ/WRITE) cutoff/center frequency (Hz)
.Q (float, READ/WRITE) resonance/Q
.set (float, float WRITE only) set freq and Q

HPF

Resonant high pass filter. 2nd order Butterworth. (In the future, this class may be expanded so that order and type of filter can be set.) extends FilterBasic

.freq (float, READ/WRITE) cutoff frequency (Hz)
.Q (float, READ/WRITE) resonance (default is 1)
.set (float, float WRITE only) set freq and Q

LPF

Resonant low pass filter. 2nd order Butterworth. (In the future, this class may be expanded so that order and type of filter can be set.) extends FilterBasic

.freq (float, READ/WRITE) cutoff frequency (Hz)
.Q (float, READ/WRITE) resonance (default is 1)
.set (float, float WRITE only) set freq and Q

OnePole

STK one-pole filter class. examples/ugen/OnePole.txt

.a1 (float, READ/WRITE) filter coefficient
.b0 (float, READ/WRITE) filter coefficient
.pole (float, READ/WRITE) set pole position along real axis of z-plane

OneZero

STK one-zero filter class.

.zero (float, READ/WRITE) set zero position
.b0 (float, READ/WRITE) filter coefficient
.b1 (float, READ/WRITE) filter coefficient

examples/ugen/OneZero.txt

PoleZero

STK one-pole, one-zero filter class. examples/ugen/PoleZero.txt

.a1 (float, READ/WRITE) filter coefficient
.b0 (float, READ/WRITE) filter coefficient
.b1 (float, READ/WRITE) filter coefficient
.blockZero (float, READ/WRITE) DC blocking filter with given pole position
.allpass (float, READ/WRITE) allpass filter with given coefficient

ResonZ

Resonance filter. Same as BiQuad with equal gain zeros. extends FilterBasic

.freq (float, READ/WRITE) center frequency (Hz)
.Q (float, READ/WRITE) Q (default is 1)
.set (float, float WRITE only) set freq and Q

TwoPole

STK two-pole filter class.

.a1 (float, READ/WRITE) filter coefficient
.a2 (float, READ/WRITE) filter coefficient
.b0 (float, READ/WRITE) filter coefficient
.freq (float, READ/WRITE) filter resonance frequency
.radius (float, READ/WRITE) filter resonance radius
.norm (float, READ/WRITE) toggle filter normalization

see examples/powerup.ck examples/ugen/TwoPole.txt

TwoZero

STK two-zero filter class.

.b0 (float, READ/WRITE) filter coefficient
.b1 (float, READ/WRITE) filter coefficient
.b2 (float, READ/WRITE) filter coefficient
.freq (float, READ/WRITE) filter notch frequency
.radius (float, READ/WRITE) filter notch radius

examples/ugen/TwoZero.txt

sound files

LiSa

live sampling utility by Dan Trueman.

LiSa provides basic live sampling functionality. 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.

.duration - ( dur , READ/WRITE ) - sets buffer size; required to allocate memory, also resets all parameter values to default
.record - ( int , READ/WRITE ) - turns recording on and off
.getVoice - ( int READ ) - returns the voice number of the next available voice
.maxVoices - ( int , READ/WRITE ) - sets the maximum number of voices allowable; 10 by default (200 is the current hardwired internal limit)
.play - ( int, WRITE ) - turn on/off sample playback (voice 0)
.play - ( int voice, int, WRITE) - for particular voice (arg 1), turn on/off sample playback
.rampUp - ( dur, WRITE ) - turn on sample playback, with ramp (voice 0)
.rampUp - ( int voice dur, WRITE ) - for particular voice (arg 1), turn on sample playback, with ramp
.rampDown - ( dur, WRITE ) - turn off sample playback, with ramp (voice 0)
.rampDown - ( int voice, dur, WRITE ) - for particular voice (arg 1), turn off sample playback, with ramp
.rate - ( float, WRITE ) - set 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)
.rate - ( int voice, float, WRITE ) - for particular voice (arg 1), set playback rate
.rate - ( READ ) - get playback rate (voice 0)
.rate - ( int voice, READ ) - for particular voice (arg 1), get 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 number)
.playPos - ( READ ) - get playback position (voice 0)
.playPos - ( int voice, READ ) - for particular voice (arg 1), get playback position
.playPos - ( dur, WRITE ) - set playback position (voice 0)
.playPos - ( int voice, dur, WRITE ) - for particular voice (arg 1), set playback position
.recPos - ( dur, READ/WRITE ) - get/set record position
.recRamp - ( dur , READ/WRITE ) - set ramping when recording (from 0 to loopEndRec)
.loopRec - ( int, READ/WRITE ) - turn on/off loop recording
.loopEndRec - ( dur, READ/WRITE ) - set end point in buffer for loop recording
.loopStart - ( dur , READ/WRITE ) - set loop starting point for playback (voice 0). only applicable when 1 => loop.
.loopStart - ( int voice, dur , WRITE ) - for particular voice (arg 1), set loop starting point for playback. only applicable when .loop(voice, 1).
.loopEnd - ( dur , READ/WRITE ) - set loop ending point for playback (voice 0). only applicable when 1 => loop.
.loopEnd - ( int voice, dur , WRITE ) - for particular voice (arg 1), set loop ending point for playback. only applicable when .loop(voice, 1).
.loop - ( int , READ/WRITE ) - turn on/off looping (voice 0)
.loop - ( int voice, int, READ/WRITE ) - for particular voice (arg 1), turn on/off looping .bi - ( int , READ/WRITE ) - turn on/off bidirectional playback (voice 0)
.bi - ( int voice, int , WRITE ) - for particular voice (arg 1), turn on/off bidirectional playback .
voiceGain - ( float , READ/WRITE ) - set playback gain (voice 0) .voiceGain - ( int voice, float , WRITE ) - for particular voice (arg 1), set gain
.feedback - ( float , READ/WRITE ) - get/set feedback amount when overdubbing (loop recording; how much to retain)
.valueAt - ( dur, READ ) - get value directly from record buffer
.valueAt - ( sample, dur, WRITE ) - set value directly in record buffer
.sync - (int, READ/WRITE) - set input mode; (0) input is recorded to internal buffer, (1) input sets playback position [0,1] (phase value between loopStart and loopEnd for all active voices), (2) input sets playback position, interpreted as a time value in samples (only works with voice 0)
.track - (int, READ/WRITE) - identical to sync
.clear - clear recording buffer

See examples/special (various files)

SndBuf

sound buffer ( now interpolating ) reads from a variety of file formats see examples/sndbuf.ck

.read - (string, WRITE only) - loads file for reading
.chunks - (int, READ/WRITE) - size of chunk ( of frames) to read on-demand; 0 implies entire file, default; must be set before reading to take effect.
.write - (string, WRITE only) - loads a file for writing (currently unimplemented)
.pos - (int, READ/WRITE) - set position (0 p .samples)
.valueAt - (int, READ only) - returns the value at sample index .loop - (int, READ/WRITE) - toggle looping
.interp - (int, READ/WRITE) - set interpolation (0=drop, 1=linear, 2=sinc)
.rate - (float, READ/WRITE) - playback rate (relative to the file's natural speed)
.play - (float, READ/WRITE) - play (same as rate)
.freq - (float, READ/WRITE) - playback rate (file loops/second)
.phase - (float, READ/WRITE) - set phase position (0-1)
.channel - (int, READ/WRITE) - select channel (0 x .channels)
.phaseOffset - (float, READ/WRITE) - set a phase offset
.samples - (int, READ only) - fetch number of samples
.length - (dur, READ only) - fetch length as duration
.channels - (int, READ only) - fetch number of channels

WvIn

STK audio data input base class. examples/ugen/WvIn.txt

.rate (float, READ/WRITE) playback rate
.path (string, READ/WRITE) specifies file to be played

WaveLoop

STK waveform oscillator class. see examples/dope.ck examples/ugen/WaveLoop.txt

.freq (float, READ/WRITE) frequency of playback (loops/second)
.addPhase (float, READ/WRITE) offset by phase
.addPhaseOffset (float, READ/WRITE) set phase offset

WvOut

STK audio data output base class. examples/ugen/WvOut.txt

.matFilename (string, WRITE only) open a matlab file for writing
.sndFilename (string, WRITE only) open snd file for writing
.wavFilename (string, WRITE only) open WAVE file for writing
.rawFilename (string, WRITE only) open raw file for writing
.aifFilename (string, WRITE only) open AIFF file for writing
.closeFile () close file properly

network

netout

UDP-based network audio transmitter

.addr (string, READ/WRITE) target address
.port (int, READ/WRITE) target port
.size (int, READ/WRITE) packet size
.name (string, READ/WRITE) name

netin

UDP-based network audio receiver

.port (int, READ/WRITE) set port to receive
.name (string, READ/WRITE) name

mono <- -> stereo

Pan2

Spread mono signal to stereo see examples/stereo/moe2.ck

.left (UGen) left (mono) channel out
.right (UGen) right (mono) channel out
.pan (float, READ/WRITE) pan location value (-1 to 1)

Mix2

Mixes stereo input down to mono channel. Note that without this UGen or gain adjustment chucking stereo signals into a mono input will result in summing them, which may cause clipping.

.left - (UGen) left (mono) channel in
.right - (UGen) right (mono) channel in
.pan - (float, READ/WRITE) mix parameter value (0 - 1)

STK - Delay

Delay

STK non-interpolating delay line class

see examples/netrelay.ck

.delay (dur, READ/WRITE) length of delay
.max (dur, READ/WRITE) max delay (buffer size)

DelayA

STK allpass interpolating delay line class. examples/ugen/DelayA.txt

.delay (dur, READ/WRITE) length of delay
.max (dur, READ/WRITE) max delay (buffer size)

DelayL

STK linear interpolating delay line class.

.delay (dur, READ/WRITE) length of delay
.max (dur, READ/WRITE) max delay (buffer size)

see examples/i-robot.ck

Echo

STK echo effect class.

.delay (dur, READ/WRITE) length of echo
.max (dur, READ/WRITE) max delay
.mix (float, READ/WRITE) mix level (wet/dry)

STK - Envelopes

Envelope

STK envelope base class.

.keyOn (int, WRITE only) ramp to 1.0
.keyOff (int, WRITE only) ramp to 0.0
.target (float, READ/WRITE) ramp to arbitrary value
.time (float, READ/WRITE) time to reach target (in second)
.duration (dur, READ/WRITE) time to reach target
.rate (float, READ/WRITE) rate of change
.value (float, READ/WRITE) set immediate value

see examples/sixty.ck

ADSR

STK ADSR envelope class.

.keyOn (int, WRITE only) start the attack for non-zero values
.keyOff (int, WRITE only) start the release for non-zero values
.attackTime (dur, WRITE only) attack time
.attackRate (float, READ/WRITE) attack rate
.decayTime (dur, READ/WRITE) decay
.decayRate (float, READ/WRITE) decay rate
.sustainLevel (float, READ/WRITE) sustain level
.releaseTime (dur, READ/WRITE) release time
.releaseRate (float, READ/WRITE) release rate
.state (int, READ only) attack=0, decay=1, sustain=2, release=3,done=4

see examples/adsr.ck

STK - Reverbs

JCRev

John Chowning's reverberator class.

.mix (float, READ/WRITE) mix level

NRev

CCRMA's NRev reverberator class.

.mix (float, READ/WRITE) mix level

PRCRev

Perry's simple reverberator class.

.mix (float, READ/WRITE) mix level

STK - Components

Chorus

STK chorus effect class.

.modFreq (float, READ/WRITE) modulation frequency
.modDepth (float, READ/WRITE) modulation depth
.mix (float, READ/WRITE) effect mix
.baseDelay( dur ) sets current base delay

PitShift

STK simple pitch shifter effect class.

.mix (float, READ/WRITE) effect dry/wet mix level
.shift (float, READ/WRITE) degree of pitch shifting

Dyno

Dynamics processor by Matt Hoffman and Graham Coleman. Includes limiter, compressor, expander, noise gate, and ducker (presets)

preset	slopeAbove	slopeBelow	tresh	attackTime	releaseTime	ext.side
limiter	0.1	1.0	0.5	5::ms	300::ms	false
compressor	0.5	1.0	0.5	5::ms	300::ms	false
expander	2.0	1.0	0.5	20::ms	400::ms	false
noise gate	1.0	10000000	0.1	11::ms	100::ms	false
ducker	0.5	1.0	0.1	100::ms	second	true

(control parameters)

.limit - () - set parameters to default limiter values
.compress - () - set parameters to default compressor values
.expand - () - set parameters to default expander values
.gate - () - set parameters to default noise gate values
.duck - () - set parameters to default ducker values
.thresh - ( float, READ/WRITE ) - the point above which to stop using slopeBelow and start using slopeAbove to determine output gain vs input gain
.attackTime - ( dur, READ/WRITE ) - duration for the envelope to move linearly from current value to the absolute value of the signal's amplitude
.releaseTime - ( dur, READ/WRITE ) - duration for the envelope to decay down to around 1/10 of its current amplitude, if not brought back up by the signal
.ratio - ( float, READ/WRITE ) - alternate way of setting slopeAbove and slopeBelow; sets slopeBelow to 1.0 and slopeAbove to 1.0 / ratio
.slopeBelow - ( float, READ/WRITE ) - determines the slope of the output gain vs the input envelope's level in dB when the envelope is below thresh. For example, if slopeBelow were 0.5, thresh were 0.1, and the envelope's value were 0.05, the envelope's amplitude would be about 6 dB below thresh, so a gain of 3 dB would be applied to bring the output signal's amplitude up to only 3 dB below thresh. in general, setting slopeBelow to be lower than slopeAbove results in expansion of dynamic range.
.slopeAbove - ( float, READ/WRITE ) - determines the slope of the output gain vs the input envelope's level in dB when the envelope is above thresh. For example, if slopeAbove were 0.5, thresh were 0.1, and the envelope's value were 0.2, the envelope's amplitude would be about 6 dB above thresh, so a gain of -3 dB would be applied to bring the output signal's amplitude up to only 3 dB above thresh. in general, setting slopeAbove to be lower than slopeBelow results in compression of dynamic range
.sideInput - ( float, READ/WRITE ) - 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.
.externalSideInput - ( int, READ/WRITE ) - set to true to cue the amplitude envelope off of sideInput instead of the input signal. note that this means you will 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.

See examples/special/Dyno-limit.ck