[Note: this section of the manual pertains to the recent Beta Release of Minim and not to the version currently being distributed with Processing.]

UGens

We’ve seen the synthesis algorithms and synthesis chains, but these are made up of UGens which are patched together. It’s now important to talk about the UGens a bit more.

List of UGens

First, here’s a list of the UGens currently included with Minim.

sound generators
—————–
Noise
Oscil
LiveInput
FilePlayer

effects
——-
Delay
Pan
Balance
Gain
IIRFilter
BitCrush
WaveShaper

envelopes
———
Line
ADSR
Damp
GranulateRandom
GranulateSteady

math
—-
Constant
Midi2Hz
Multiplier
Reciprocal
Summer

AudioOutput can also be treated as a UGen for the purposes of patching, but it stands alone, different from the rest. IIRFilter is a special case as well and will be discussed later.

Instantiating a UGen

For those who don’t know object-oriented programming yet, you’ll have to take the next section on faith just a bit. Whenever you want to use a UGen, you’ll need to instantiate it first. The code to instantiate and Oscil UGen can look like this.

[snip java]
Oscil osc = new Oscil( 349.23, 0.8 );
[/snip]

This line tells Processing to create a new reference to an Oscil object and call that reference “osc”. This line also says to “instantiate” an Oscil object using one of its constructors, specifically, the constructor which takes two float values. This line also tells Processing to make the new object ref “osc” and make it point to the newly instantiated Oscil object. In summary, this line makes “osc” refer to a new Oscil object. Every UGen will need to be instantiated in a fashion similar to this, although sometimes the creation of the reference and the creation of the object may need to be put in different locations.

Sound Generators

An Oscil UGen is an oscillator. It creates an output waveform which repeats at the specified frequency and at the specified amplitude. In the case of Oscil, if a constructor with two floats is called, the first is read as the frequency and the second is read as the amplitude. It is possible to include a waveshape as well, as a third argument, but that will be discussed more in Special Classes.

You are now encouraged to go take a look at the JavaDocs for the Oscil UGen. There, you’ll find a list of the inputs, constructors, and methods available for the Oscil UGen. The use of the methods will be discussed more in the next section, Instruments.

The Noise UGen generates noise of different “tints”: white, pink, and red/brown. Wikipedia has some excellent articles on audio noise.

LiveInput transmits incoming audio through the synthesis chain. The incoming audio is selected by the operating system.

FilePlayer will play a file (even from the web!) into the synthesis stream. It can be looped and paused as desired.

You’re encouraged once again to go look at the JavaDocs for these UGens. The list of UGens available at http://code.compartmental.net/minim-beta/javadoc/ddf/minim/ugens/package-summary.html.

Inputs

Almost all UGens have inputs. An input is a way to control what the UGen does while it’s generating sound. For instance, an Oscil UGen has an amplitude, frequency, and phase input. The frequency input allows the frequency to be changed as the Oscil is sound. Many of the UGens, like the following effects UGens, have an audio input. This is what brings in the sampleframes from the previous UGens. Often when directly patching to a UGen, you are actually patching to its audio input.

Effects

The Delay UGen repeats a delayed version of the incoming signal.

The Pan UGen takes a mono signal and specifies a stereo position for that signal.

The Balance UGen attenuates the left or right channel of stereo signal.

The Gain attenuates or amplifies the incoming signal. Gain is expressed in dB.

BitCrush reduces the bit resolution of the incoming signal.

WaveShaper uses the incoming signal as the index to another wave. This is a standard form of waveform synthesis and Wikipedia has a good article about it.

All of the effects UGens above can be found in the JavaDocs for UGens. The list of UGens available is at http://code.compartmental.net/minim-beta/javadoc/ddf/minim/ugens/package-summary.html.

IIRFilter (infinite impulse response filter) is a generic filter UGen. It’s actually implemented by several other UGens which are extended from IIRFilter. Those filters are BandPass, ChebFilter, HighPassSP (single pole), LowPassSP (single pole), LowPassFS (four stage), or Notch Filter. Each of these filters removes part of the audio signal in the way described by the name of the UGen.

The JavaDocs for the IIRFilter are found in the effects package for minim. The list of filters can be found at http://code.compartmental.net/minim-beta/javadoc/ddf/minim/effects/package-summary.html.

Envelopes

Envelopes are generally used to control the amplitude or another aspect of the sound during the playback of a note. A more detailed discussion of the usage of envelopes will follow in the Instruments section.

The Line Ugen outputs a value which changes from a specified beginning value to an ending value over a specified time.

The ADSR UGen produces an attack-decay-sustain-release envelope.

The Damp UGen produces an attack-decay envelope.

The GranulateSteady UGen produces steady length granular-synthesis grains from the input signal.

The GranulateRandom UGen produces random length granular-synthesis grains from the input signal. At this time, the grains for both GranulateSteady and GranulateRandom have a linear fade in and out.

The Oscil UGen can also be used as an envelope if the frequency is set so the period of the wave is about the duration of the note.

These envelope UGens are also found in the JavaDocs for UGens at http://code.compartmental.net/minim-beta/javadoc/ddf/minim/ugens/package-summary.html.

Math

Due to our decision to use the patching mechanism to connect synthesis chains, it’s unfortunately not simple to do math with the sampleframes being passed along the synthesis chains. We had to implement math directly as UGens.

The Constant UGen generates a constant value as a signal.

The Summer UGen adds (sums) all incoming inputs.

The Multiplier UGen multiplies an incoming signal by an amplitude.

The Reciprocal UGen generates the reciprocal of the incoming signal. This can be useful when, for example, building a physical modelling instrument which is based on the length of a tube.

The Midi2Hz UGen generates the equivalent frequency in Hertz for an incoming signal given as a MIDI note number. The MIDI note number does not need to be an integer. This permits changes in pitch which are musical in nature.

These math UGens are also found in the JavaDocs for UGens at http://code.compartmental.net/minim-beta/javadoc/ddf/minim/ugens/package-summary.html.

Examples to look at

nonInstrSimpleExample
filterExample
constantExample
delayExample