gibberish-dsp/docs/docs.md

Gibberish is designed to be an optimized API for audio synthesis using per-sample techniques.

# Gibberish

#### Methods ####
### gibberish.clear ###
Disconnects all ugens from the master bus and stops all sequencers from runnning.

### gibberish.init ###
The `init` method creates an `AudioContext` object, a `ScriptProcessor Node`, and connects the output of the node to the `destination` property of the AudioContext. This single line should be enough to start a Gibberish session (assuming the Gibberish library has been properly included from your HTML file).  

*** memorySize ***   *int*   Default:44100 * 60 * 20 (twenty minutes at 44.1 kHz). This determines the size of the memory block that Gibberish will use for all ugens. If you use a lot of samples (more than twenty minutes worth) you may want to increase this size.

### gibberish.print ###
Prints the current master audio callback to the console.

### gibberish.export ###
By default, the Gibberish library is contained within the global `Gibberish` object (or whatever variable you import it into using browserify / require.js etc). However, you can easily export the Gibberish namespace to another object (for example, the `window` object) for easier API access. 

*** target ***   *object*. The object to export the Gibberish namespace to.  
*** shouldExportGenish ***   *boolean*   Default:false. Determines whether or not the lower-level unit generators found in genish.js are also exported to the target object. Note that many variables names in genish and Gibberish are only differentiated by lowercase vs uppercase letters... for example, Gibberish has `Add`, `ADSR`, and `Mod` ugens, while genish has `add`, `adsr`, and `mod`. 

#### Propertie s####
### gibberish.debug ###
*boolean* Default:false. When this value is set to true, callbacks will be printed to the console whenever they are generated.
### gibberish.output ###
*Bus2* The master bus that all Gibberish ugens eventually feed into. This bus is created during calls to `Gibberish.init()`.


# Prototypes

ugen
----
*Gibberish.prototypes.ugen*

The ugen object is the primary prototype for all unit generators in Gibberish.js. All ugens with the exception of simple binop / monop math operations (add, mul, abs etc.) delegate to this prototype object. 

#### Methods ####
### ugen.print ###
Calls to `ugen.print()` will write a unit generators callback function to the `console` object.

### ugen.free ###
Frees the memory associated with a unit generator.

### ugen.connect ###

**ugen**   *object*   Optional. Another unit generator to connect to. If this arguement is undefined, the unit generator will create a default connection to `Gibberish.output`, which is essentially the master output bus.

**level**   *float*   Optional; default = 1. A scalar that is applied to the signal the unit generator sends to the connection.

This method works to connect instruments / oscillators to effects / filters, or to connect instruments / oscillators / filters and effects to busses. 

```javascript
syn = Gibberish.Synth()
syn.connect() // default connection to master bus

syn2 = Gibberish.Synth()
bus  = Gibberish.Bus2() // stereo bus
bus.connect() // connect to master bus
syn2.connect( bus ) // connect to bus

syn3 = Gibberish.Synth()
syn3.connect( bus, .5 ) // scale output to bus

// By default, effects accept a single input. However, we can easily
// connect multiple instruments to an effect using a bus as that input.
reverb = Gibberish.Freeverb({ input:Bus() }).connect()
syn.connect(  reverb.input, .25 )
syn2.connect( reverb.input, .25 )
syn3.connect( reverb.input, .25 )
```

### ugen.disconnect ###

**ugen**   *object*   Optional. The unit generator calling `disconnect` will be disconnected from this destination. If this argument is ommitted, the unit generator will be disconnected from all unit generators it is currently connected to.

effect
----
*Gibberish.prototypes.effect*  
*Prototype: [Gibberish.prototypes.ugen](#prototypes-ugen)*

This is the prototype for all effect unit generators. 

#### Properties ####
### effect.defaults ###
*Object* { bypass:false } These defaults are applied to all effects. Changing the bypass value of any effect to true will completely remove it from the audio callback. 

filter
----
*Gibberish.prototypes.filter*  
*Prototype: [Gibberish.prototypes.ugen](#prototypes-ugen)*

This is the prototype for all filters.

#### Properties ####
### filter.defaults ###
*Object* { bypass:false } These defaults are applied to all filters. Changing the bypass value of any filter to true will completely remove it from the audio callback. 

instrument
----
*Gibberish.prototypes.instrument*  
*Prototype: [Gibberish.prototypes.ugen](#prototypes-ugen)*

Monophonic instruments in Gibberish (such as Synth, FM, and Monosynth) delegate to this prototype for `note` and `trigger` methods, while polyphonic instruments use a mixin (polytemplate.js). 

#### Methods ####
### instrument.note( frequency  ) ###
**frequency**    *number*   The frequency for the new note to be played.

The `note` method assigns a new frequency to the instrument and re-triggers the instrument's envelope. For some percussion instruments that use fixed frequencies (Cowbell, Snare, and Hat) this method will trigger the instrument's envelope but the argument frequency will have no effect.

```javascript
fm = Gibberish.FM().connect()
fm.note( 330 )
```

### instrument.trigger( loudness  ) ###
**loudness**    *number*   A scalar applied to the gain envelope of the new note.

Trigger a note at the last used frequency with the provided `loudness` as a scalar.

```javascript
kick = Gibberish.Kick({ frequency: 80 }).connect()

Gibberish.Sequencer({ 
  target:kick, 
  key:'trigger', 
  values:[ .1,.2,.3,.5], 
  timings:[11025]
}).start()
```

# Mixins

polyinstrument
----
*Gibberish.mixins.polyinstrumentn*  

Polyphonic instruments in Gibberish (such as Synth, FM, and Monosynth) use this mixin for `note`, `trigger`, and `chord` methods. Note that polyphonic instruments also use `Bus` and `Bus2` objects as prototypes. 

#### Methods ####
### polyinstrument.chord( frequencies  ) ###
**frequency**    *array*   The frequencies of the chord to be played.

The `chord` method selects voices from the polyphonic instrument, assigns them new frequencies, and triggers their envelopes. The number of notes concurrently playable is determined by the instrument's `maxVoices` property. Using the `chord` method with three frequencies is functionally identical to calling `note` three times simultaneously.
 
```javascript
fm = Gibberish.PolyFM({ maxVoices:3, decay: 88200 * 2 }).connect()
fm.chord([ 330,440,550 ])
```
### polyinstrument.note( frequency  ) ###
**frequency**    *number*   The frequency for the new note to be played.

The `note` method selects a child voice from the polyphonic instrument, assigns it a new frequency, and triggers the instrument's envelope. The number of notes concurrently playable is determined by the instruments `maxVoices` property.
 
```javascript
fm = Gibberish.PolyFM({ maxVoices:3, decay: 88200 * 2 }).connect()
fm.note( 330 )
fm.note( 440 )
fm.note( 550 )
```

### polyinstrument.trigger( loudness  ) ###
**loudness**    *number*   A scalar applied to the gain envelope of the new note.

Trigger a note or chord at the last used frequency(ies) with the provided `loudness` as a scalar.

```javascript
syn = Gibberish.PolySynth({ attack:44, decay:22050 }).connect()
syn.chord([ 330,440,550 ])


Gibberish.Sequencer({ 
  target:syn, 
  key:'trigger', 
  values:[ .1,.2,.3,.5], 
  timings:[11025]
}).start()
```

# Instruments

Conga
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Conga` unit generator emulates the conga sound found on the Roland TR-808 drum machine. It consists of an impulse feeding a resonant filter scaled by an exponential decay.

```javascript
// run line by line
conga = Gibberish.Conga().connect()
conga.note( 440 )
conga.decay( .25 )
conga.note( 440 )
```

#### Properties ####
### conga.decay ###
*float* range: 0-1, default: .85 This value controls the decay length of each note.
### conga.gain ###
*float* default: .25 This value controls the loudness of each note.

Complex
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Complex` instrument provides an oscillator feeding a multi-stage wavefolder, accompanied by a filter and envelope. It gets its name from Bucla 259 Complex Waveform Generator, which was a classic sound of West Coast synthesis. In Buchla's oscillators, timbre is acheived through non-linear waveshaping / folding; this is different from subtractive synthesis, where you start with oscillators rich in harmonics and then remove harmonics using filtering. Another hallmark of West Coast synthesis is the LPG (low-pass gate) where exponential envelopes are tied directly to both filtering and amplitude. This is actually how the filters and envelopes work in all og Gibber's instruments, so you can think of the Complex instrument as being one (very) approximate recreation of the West Coast sound. 

The non-linear distortion in the wavefolding for this instrument is determined by a `pregain` property which boosts the oscillator level before folding. The `postgain` property can then be used to scale back the output of the folding before the signal is filtered. 

```javascript
// run all at once

complex = Gibberish.instruments.Complex({
  pregain:50, decay:44100, attack:44 
}).connect()

Gibberish.Sequencer({ 
  target:complex,
  key:'pregain',
  values:[ 5,10,25,50 ],
  timings:[44100]
}).start()


Gibberish.Sequencer({ 
  target:complex,
  key:'note',
  values:[ 2200 ],
  timings:[ 44100 ]
}).start()
```

#### Properties ####
### complex.pregain###
*float* default: 4. This controls the amount of gain applied to the instrument's oscillator before it is fed into the wavefolder. This is the primary driver of the oscillator's final timbre.
### complex.postgain###
*float* default: 1. This determines the amount of gain applied to the signal after folding and before filtering.
### complex.antialias ###
*boolean* default: false. If this property is true, both the carrier and modulator will use higher quality (and more computationally expensive) anti-aliasing oscillators.
### complex.panVoices ###
*boolean* default: false. If true, the synth will expose a pan property for stereo panning; otherwise, the synth is mono.
### complex.pan ###
*float* range: 0-1, default: .5. If the `panVoices` property of the synth is `true`, this property will determine the position of the synth in the stereo spectrum. `0` = left, `.5` = center, `1` = right. 
### complex.attack ###
*int* default: 44. The length of the attack portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. 
### complex.decay ###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
### complex.sustain ###
*int* default: 44100. The length of the sustain portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Note that the sustain will last until the synth's `synth.env.release()` method is triggered if the synth's `triggerRelease` property is set to `true`.
###complex.sustainLevel###
*float* default: .6. The gain stage of the sustain portion of the synth's envelope. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Sustain and release are only used if the `useADSR` property of the synth is set to be true.
### complex.release ###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
### complex.useADSR ###
*bool* default: false. Determines whether a synth uses a two stage (AD) or four-stage (ADSR) envelope.
### complex.triggerRelease ###
*bool* default: false. Assuming a synth's `useADSR` property is also set to `true`, a value of `true` on this property will continue the sustain stage of an ADSR indefinitely until the synth's envelope receives a release  message (i.e `synth.env.release()`)
### complex.gain ###
*float* default: 1. A scalar applied to the output of the synth. It is modulated by the synth's envelope.
### complex.carrierWaveform ###
*string* default: 'sine'. Controls the waveform of the carrier oscillator. Choose between 'sine','saw','square', and 'pwm'.
### complex.filterType ###
*int* default: 0. Select a filter type. `0` - no filter.  `1` - Zero-delay (aka virtual analog) 4-pole Moog-style ladder filter. `2` - Zero-delay (aka virtual analog) resonant diode filter, modeled after the TB-303. `3` - State variable filter with multiple modes. `4` - Biquad filter with multiple modes. `5` - 'classic' Gibberish 4-pole resonant filter.
### complex.filterMode ###
*int* default: 0. Select a filter mode. `0` - low pass. `1` - high pass, available for filter types 3, 4, and 5. `2` -
bandpass, available for filter types 3 and 4. `3` - notch, available efor filter type 4.
### complex.cutoff ###
*float* default: .5. Controls the cutoff frequncy of the filter, if enabled. Values are clamped to ranges between 0–1..
### complex.filterMult ###
*float* default: 2. Controls modulation applied to the cutoff frequency by the synth's envelope. For example, given a `cutoff` property of `.5` and a `filterMult` of `2`, the final cutoff frequency will vary between .5 and 1 as the envelope increases and decreases in value. Use low `cutoff` values and high `filterMult` values to create filter sweeps for each note that is played. 
### complex.Q ###
*float* default: .25 Controls the filter 'quality' (aka resonance), if the filter for the synth is enabled. Values are clamped between 0–1 to avoid blowing up the various filters.
### complex.saturation ###
*float* default: 1. For filter type 2 (modeled TB-303), this value controls a non-linear waveshaping (distortion) applied to the signal before entering the filter stage. A value of 1 means no saturation is added, higher values yield increasing distortion.

Cowbell
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Cowbell` unit generator emulates the cowbell sound found on the Roland TR-808 drum machine. It consists of an two tuned square waves feeding a resonant bandpass filter scaled by an exponential decay.

```javascript
// run line by line
conga = Gibberish.Conga().connect()
conga.trigger( .5 )
conga.decay( .05 )
conga.trigger( .75 )
```

#### Properties ####
### cowbell.decay ###
*float* range: 0-1, default: .5 This value controls the decay length of each note. 0 represents a decay of 0 samples (and thus no sound, don't do this) while a value of 1 represents two seconds.
### cowbell.gain ###
*float* default: .25 This value controls the loudness of each note.

FM
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `FM` unit generator provides two-operator FM synthesis with a choice of waveforms for both carrier and modulator, as well as a filter with selectable models (disabled by default). In addition to modulating the frequency of the carrier oscillator, the modulator may also modulate itself via a single sample feedback loop. The amount of feedback is determined both by the `index` property of the FM instance (which also controls how much the modulator affects the carrier frequency) and a separate `feedback` parameter which scales the amount of self-modulation. The envelopes of FM instances controls gain, modulation index, and filter cutoff (assuming an appropriate value for filterMult).

```javascript
// run all at once

fm = Gibberish.instruments.FM({
  modulatorWaveform:'square', // or saw, sine etc.
}).connect()

Gibberish.Sequencer({ 
  target:fm,
  key:'cmRatio',
  values:[ function() { return .15 + Math.random() * 10 } ],
  timings:[22050]
}).start()

Gibberish.Sequencer({ 
  target:fm,
  key:'index',
  values:[ function() { return .5 + Math.random() * 20 } ],
  timings:[22050]
}).start()

Gibberish.Sequencer({ 
  target:fm,
  key:'note',
  values:[ 440 ],
  timings:[ 44100 ]
}).start()
```

#### Properties ####
### fm.cmRatio ###
*float* default: 2. This controls the relationship between the carrier oscillator's frequency and the modulating oscillator's frequency. A value of `2` means that, given a carrier frequency of 440, the modulator frequency will be 880.
### fm.index ###
*float* default: 5. In canonical FM synthesis, the amplitude of the modulating oscillator is controlled by the frequency of the carrier on the 'modulation index' parameter. Given a carrier frequency of 440 and `index` property of `5`, the amplitude of the modulating oscillator will be `440 * 5 = 2200`.
### fm.feedback ###  
*float* default: 0. A scalar which determines how much the output of the modulating oscillator affects the frequency of the modulating oscillator via a single-sample feedback loop. Note: high values (>1) coupled with high index values can cause the algorithm to blow-up.
### fm.antialias ###
*boolean* default: false. If this property is true, both the carrier and modulator will use higher quality (and more computationally expensive) anti-aliasing oscillators.
### fm.panVoices ###
*boolean* default: false. If true, the synth will expose a pan property for stereo panning; otherwise, the synth is mono.
### fm.pan ###
*float* range: 0-1, default: .5. If the `panVoices` property of the synth is `true`, this property will determine the position of the synth in the stereo spectrum. `0` = left, `.5` = center, `1` = right. 
### fm.attack ###
*int* default: 44. The length of the attack portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. 
### fm.decay ###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
### fm.sustain ###
*int* default: 44100. The length of the sustain portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Note that the sustain will last until the synth's `synth.env.release()` method is triggered if the synth's `triggerRelease` property is set to `true`.
###fm.sustainLevel###
*float* default: .6. The gain stage of the sustain portion of the synth's envelope. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Sustain and release are only used if the `useADSR` property of the synth is set to be true.
### fm.release ###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
### fm.useADSR ###
*bool* default: false. Determines whether a synth uses a two stage (AD) or four-stage (ADSR) envelope.
### fm.triggerRelease ###
*bool* default: false. Assuming a synth's `useADSR` property is also set to `true`, a value of `true` on this property will continue the sustain stage of an ADSR indefinitely until the synth's envelope receives a release  message (i.e `synth.env.release()`)
### fm.gain ###
*float* default: 1. A scalar applied to the output of the synth. It is modulated by the synth's envelope.
### fm.carrierWaveform ###
*string* default: 'sine'. Controls the waveform of the carrier oscillator. Choose between 'sine','saw','square', and 'pwm'.
### fm.modulatorWaveform ###
*string* default: 'sine'. Controls the waveform of the modulating oscillator. Choose between 'sine','saw','square', and 'pwm'.
### fm.filterType ###
*int* default: 0. Select a filter type. `0` - no filter.  `1` - Zero-delay (aka virtual analog) 4-pole Moog-style ladder filter. `2` - Zero-delay (aka virtual analog) resonant diode filter, modeled after the TB-303. `3` - State variable filter with multiple modes. `4` - Biquad filter with multiple modes. `5` - 'classic' Gibberish 4-pole resonant filter.
### fm.filterMode ###
*int* default: 0. Select a filter mode. `0` - low pass. `1` - high pass, available for filter types 3, 4, and 5. `2` -
bandpass, available for filter types 3 and 4. `3` - notch, available efor filter type 4.
### fm.cutoff ###
*float* default: .5. Controls the cutoff frequncy of the filter, if enabled. Values are clamped to ranges between 0–1..
### fm.filterMult ###
*float* default: 2. Controls modulation applied to the cutoff frequency by the synth's envelope. For example, given a `cutoff` property of `.5` and a `filterMult` of `2`, the final cutoff frequency will vary between .5 and 1 as the envelope increases and decreases in value. Use low `cutoff` values and high `filterMult` values to create filter sweeps for each note that is played. 
### fm.Q ###
*float* default: .25 Controls the filter 'quality' (aka resonance), if the filter for the synth is enabled. Values are clamped between 0–1 to avoid blowing up the various filters.
### fm.saturation ###
*float* default: 1. For filter type 2 (modeled TB-303), this value controls a non-linear waveshaping (distortion) applied to the signal before entering the filter stage. A value of 1 means no saturation is added, higher values yield increasing distortion.

PolyFM
---
*Prototype: [Gibberish.Bus2](#miscellaneous-bus2)*  
*Mixin: [Gibberish.mixins.polyinstrument](#mixins-polyinstrument)*

`PolyFM` objects have the same properties as [FM objects](#instruments-fm); when you change one of these property values all the child voices have their same property modified. The `maxVoices` option, which can only be set upon instantiation, determines the number of voices. Whenever a note is played a voice is chosen and connected to the `PolyFM` ugen, which acts as a bus. When the envelope of the note is finished the associated voice is disconnected from the `PolyFM` ugen.

```javascript
a = PolyFM({ maxVoices:3 }).connect()
a.chord([ 330,440,550 ])
```

Hat
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Hat` unit generator emulates the hihat sound found on the Roland TR-808 drum machine. It consists of six tuned square waves feeding bandpass and highpass filters scaled by an exponential decay.

```javascript
// run line by line
hat = Gibberish.Hat().connect()
hat.trigger( .5 )
hat.decay = .25
hat.trigger( .5 )
hat.tune = .75
hat.trigger( .5 )
hat.decay = .8
hat.tune = .25
hat.trigger( .5 )
```

#### Properties ####
### hat.decay ###
*float* range: 0-1, default: .5 This value controls the decay length of each note. 0 represents a decay of 0 samples (and thus no sound, don't do this) while a value of 1 represents two seconds.
### hat.gain ###
*float* default: .25 This value controls the loudness of each note.
### hat.tune ###
*float* range:0-1, default: .5. This value controls both the frequencies of the squarewave oscillators used in the synth and the cutoff frequencies of its filters.

Karplus
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Karplus` unit generator uses the Karplus-Strong physical model to create a plucked string sound.
```javascript
// run line by line
pluck = Gibberish.Karplus().connect()
pluck.note( 440 )
pluck.decay = 4 // seconds
pluck.note( 440 )
```

#### Properties ####
### karplus.decay ###
*float* default: .5 This value controls the decay length of each note, measured in seconds.
### karplus.damping ###
*float* range: 0-1, default: .2. The amount of damping on the string.  
### karplus.gain ###
*float* range:0-1, default:1. The loudness of notes
### karplus.glide ###
*int* range:1-?, default:1. A portamento affect applied to frequency. Increasing this will cause notes to slide into each other, as opposed to using discrete frequencies.
### karplus.panVoices ###
*boolean* default: false. If true, the synth will expose a pan property for stereo panning; otherwise, the synth is mono.
### karplus.pan ###
*float* range: 0-1, default: .5. If the `panVoices` property of the synth is `true`, this property will determine the position of the synth in the stereo spectrum. `0` = left, `.5` = center, `1` = right. 

PolyKarplus
---
*Prototype: [Gibberish.Bus2](#miscellaneous-bus2)*  
*Mixin: [Gibberish.mixins.polyinstrument](#mixins-polyinstrument)*

`PolyKarplus` objects have the same properties as [Karplus objects](#instruments-karplus); when you change one of these property values all the child voices have their same property modified. The `maxVoices` option, which can only be set upon instantiation, determines the number of voices. Whenever a note is played a voice is chosen and connected to the `PolyKarplus` ugen, which acts as a bus. When the envelope of the note is finished the associated voice is disconnected from the `PolgyKarplus` ugen.

```javascript
a = PolyKarplus({ maxVoices:3 }).connect()
a.chord([ 330,440,550 ])
```

Kick
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Kick` unit generator emulates the kick sound found on the Roland TR-808 drum machine. It consists of an impulse feeding resonant bandpass and hipass filters scaled by an exponential decay.

```javascript
// run line by line
kick = Gibberish.instruments.Conga().connect()
kick.note( 90 )
kick.decay( .25 )
kick.note( 90 )
```

#### Properties ####
###kick.decay###
*float* range: 0-1, default: .9. This value controls the decay length of each note.
###kick.gain###
*float* default: .25. This value controls the loudness of each note.
###kick.tone###
*float* range: 0-1, default: .25. This value controls the high frequency content (the 'click') at the start of each kick drum trigger. 

Monosynth
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Monosynth` instrument provides a three-oscillator synth feeding a filter with selectable models. The envelopes of Monosynth instances controls gain and filter cutoff (assuming an appropriate value for filterMult).

```javascript
// run all at once

mono = Gibberish.instruments.Monosynth({
  waveform: 'saw',   // or saw, sine, pwm etc.
  filterType: 2,     // 4-pole "virtual analog" ladder filter
  filterMult: 1760,
  Q: 18,
  gain:.1
}).connect()

Gibberish.Sequencer({ 
  target:mono,
  key:'note',
  values:[ 110 ],
  timings:[ 44100 ]
}).start()
```

####Properties####

###monosynth.antialias###
*boolean* default: false. If this property is true, both the carrier and modulator will use higher quality (and more computationally expensive) anti-aliasing oscillators.

###monosynth.attack###
*int* default: 44. The length of the attack portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. 
###monosynth.decay###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
###monosynth.sustain###
*int* default: 44100. The length of the sustain portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Note that the sustain will last until the synth's `synth.env.release()` method is triggered if the synth's `triggerRelease` property is set to `true`.
###monosynth.sustainLevel###
*float* default: .6. The gain stage of the sustain portion of the synth's envelope. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Sustain and release are only used if the `useADSR` property of the synth is set to be true.
###monosynth.release###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
###monosynth.useADSR###
*bool* default: false. Determines whether a synth uses a two stage (AD) or four-stage (ADSR) envelope.
###monosynth.triggerRelease###
*bool* default: false. Assuming a synth's `useADSR` property is also set to `true`, a value of `true` on this property will continue the sustain stage of an ADSR indefinitely until the synth's envelope receives a release  message (i.e `synth.env.release()`)
###monosynth.gain###
*float* default: 1. A scalar applied to the output of the synth. It is modulated by the synth's envelope.
###monosynth.waveform###
*string* default: 'sine'. Controls the waveform of the three monosynth oscillators. Choose between 'sine','saw','square', and 'pwm'.
###monosynth.detune2###
*float* default: 1.01. Determines the frequency of the second oscillator by adding the frequency of the first multiplied by this value, or `osc2.frequency = osc1.frequency + ( osc1.frequency * detune2 )`.
###monosynth.detune3###
*float* default: 2,99. Determines the frequency of the third oscillator by adding the frequency of the first multiplied by this value, or `osc3.frequency = osc1.frequency + ( osc1.frequency * detune3 )`.
###monosynth.panVoices###
*boolean* default: false. If true, the synth will expose a pan property for stereo panning; otherwise, the synth is mono.
###monosynth.pan###
*float* range: 0-1, default: .5. If the `panVoices` property of the synth is `true`, this property will determine the position of the synth in the stereo spectrum. `0` = left, `.5` = center, `1` = right. 
### monosynth.filterType ###
*int* default: 0. Select a filter type. `0` - no filter.  `1` - Zero-delay (aka virtual analog) 4-pole Moog-style ladder filter. `2` - Zero-delay (aka virtual analog) resonant diode filter, modeled after the TB-303. `3` - State variable filter with multiple modes. `4` - Biquad filter with multiple modes. `5` - 'classic' Gibberish 4-pole resonant filter.
### monosynth.filterMode ###
*int* default: 0. Select a filter mode. `0` - low pass. `1` - high pass, available for filter types 3, 4, and 5. `2` -
bandpass, available for filter types 3 and 4. `3` - notch, available efor filter type 4.
### monosynth.cutoff ###
*float* default: .5. Controls the cutoff frequncy of the filter, if enabled. Values are clamped to ranges between 0–1..
### monosynth.filterMult ###
*float* default: 2. Controls modulation applied to the cutoff frequency by the synth's envelope. For example, given a `cutoff` property of `.5` and a `filterMult` of `2`, the final cutoff frequency will vary between .5 and 1 as the envelope increases and decreases in value. Use low `cutoff` values and high `filterMult` values to create filter sweeps for each note that is played. 
### monosynth.Q ###
*float* default: .25 Controls the filter 'quality' (aka resonance), if the filter for the synth is enabled. Values are clamped between 0–1 to avoid blowing up the various filters.
### monosynth.saturation ###
*float* default: 1. For filter type 2 (modeled TB-303), this value controls a non-linear waveshaping (distortion) applied to the signal before entering the filter stage. A value of 1 means no saturation is added, higher values yield increasing distortion.

PolyMono
---
*Prototype: [Gibberish.Bus2](#miscellaneous-bus2)*  
*Mixin: [Gibberish.mixins.polyinstrument](#mixins-polyinstrument)*

`PolyMono` objects have the same properties as [Monosynth objects](#instruments-monosynth); when you change one of these property values all the child voices have their same property modified. The `maxVoices` option, which can only be set upon instantiation, determines the number of voices. Whenever a note is played a voice is chosen and connected to the `PolyMono` ugen, which acts as a bus. When the envelope of the note is finished the associated voice is disconnected from the `PolgyMono` ugen.

```javascript
a = PolyMono({ maxVoices:3 }).connect()
a.chord([ 330,440,550 ])
```

Sampler
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Sampler` synth loads external audiofiles and plays them at variable rates. The sampler will begin playback at according to its `start` property value and end it according to its `end` property value.

```javascript
rhodes = Gibberish.instruments.Sampler({
  filename:'http://127.0.0.1:25000/playground/resources/audiofiles/rhodes.wav'
}).connect()

rhodes.onload = function() {
  rhodes.note( -4 ) // play sample in reverse at 4x speed.
}
```

####Properties####
###sampler.filename###
*string* This must be passed in the properties dictionary handed to the constructor and point to a file on a web server that you have access to or that permits CORS operations.
###sampler.loops###
*boolean* default: false. If this value is true, the sample will repeat playback continuously.
###sampler.gain###
*float* default: .25. This value controls the loudness of each note.
###sampler.start###
*int* default: 0. The sample offset to begin playback at.
###sampler.end###
*int* default: sample.length. The last sample to play in the audiofile.

Snare
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Snare` instrument emulates the snare sound found on the Roland TR-808 drum machine. It consists of an two resonant bandpass filters mixed with highpassed noise, all scaled by an exponential decay.

```javascript
// run line by line
snare = Gibberish.instruments.Snare().connect()
snare.trigger( .5 )
snare.decay( .25 )
snare.tune = -.25
snare.trigger( .5 )
```

####Properties####
###snare.decay###
*float* range: 0-1, default: .1. This value controls the decay length of each snare strike, ranging from 0 to 2 seconds.
###snare.gain###
*float* default: .25. This value controls the loudness of each note.
###snare.snappy###
*float* range: 0-?, default: 1. A scalar controlling the amount of noise in the overall snare output.
###snare.tune###
*float* range: -.5-2, default: 0. This value modifies the tuning of the two bandpass filters and the highpass filter used in the snare instrument.

Synth
----
*Prototype: [Gibberish.prototypes.instrument](#prototypes-instrument)*

The `Synth` instrument provides a single oscillator feeding a filter with selectable models. The envelopes of Synth instances controls gain and filter cutoff (assuming an appropriate value for filterMult).

```javascript
// run all at once

syn = Gibberish.instruments.Synth({
  waveform: 'saw',   // or saw, sine, pwm etc.
  filterType: 3,     // 303-style 'virtual analog' diode filter
  filterMult: 1760,
  Q: 9,
  attack:44, decay:11025,
  gain:.1
}).connect()

Gibberish.Sequencer({ 
  target:synth,
  key:'note',
  values:[ 110 ],
  timings:[ 22050 ]
}).start()
```

####Properties####

###synth.antialias###
*boolean* default: false. If this property is true, both the carrier and modulator will use higher quality (and more computationally expensive) anti-aliasing oscillators.
###synth.attack###
*int* default: 44. The length of the attack portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. 
###synth.decay###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
###synth.sustain###
*int* default: 44100. The length of the sustain portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Note that the sustain will last until the synth's `synth.env.release()` method is triggered if the synth's `triggerRelease` property is set to `true`.
###synth.sustainLevel###
*float* default: .6. The gain stage of the sustain portion of the synth's envelope. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled. Sustain and release are only used if the `useADSR` property of the synth is set to be true.
###synth.release###
*int* default: 22050. The length of the decay portion of the synth's envelope measured in samples. The envelope modulates amplitude, the index property, and the filter cutoff frequency (if the filter is enabled.
###synth.useADSR###
*bool* default: false. Determines whether a synth uses a two stage (AD) or four-stage (ADSR) envelope.
###synth.triggerRelease###
*bool* default: false. Assuming a synth's `useADSR` property is also set to `true`, a value of `true` on this property will continue the sustain stage of an ADSR indefinitely until the synth's envelope receives a release  message (i.e `synth.env.release()`)
###synth.gain###
*float* default: 1. A scalar applied to the output of the synth. It is modulated by the synth's envelope.
###synth.waveform###
*string* default: 'sine'. Controls the waveform of the three monosynth oscillators. Choose between 'sine','saw','square', and 'pwm'.
###synth.panVoices###
*boolean* default: false. If true, the synth will expose a pan property for stereo panning; otherwise, the synth is mono.
###synth.pan###
*float* range: 0-1, default: .5. If the `panVoices` property of the synth is `true`, this property will determine the position of the synth in the stereo spectrum. `0` = left, `.5` = center, `1` = right. 
### synth.filterType ###
*int* default: 0. Select a filter type. `0` - no filter.  `1` - Zero-delay (aka virtual analog) 4-pole Moog-style ladder filter. `2` - Zero-delay (aka virtual analog) resonant diode filter, modeled after the TB-303. `3` - State variable filter with multiple modes. `4` - Biquad filter with multiple modes. `5` - 'classic' Gibberish 4-pole resonant filter.
### synth.filterMode ###
*int* default: 0. Select a filter mode. `0` - low pass. `1` - high pass, available for filter types 3, 4, and 5. `2` -
bandpass, available for filter types 3 and 4. `3` - notch, available efor filter type 4.
### synth.cutoff ###
*float* default: .5. Controls the cutoff frequncy of the filter, if enabled. Values are clamped to ranges between 0–1..
### synth.filterMult ###
*float* default: 2. Controls modulation applied to the cutoff frequency by the synth's envelope. For example, given a `cutoff` property of `.5` and a `filterMult` of `2`, the final cutoff frequency will vary between .5 and 1 as the envelope increases and decreases in value. Use low `cutoff` values and high `filterMult` values to create filter sweeps for each note that is played. 
### synth.Q ###
*float* default: .25 Controls the filter 'quality' (aka resonance), if the filter for the synth is enabled. Values are clamped between 0–1 to avoid blowing up the various filters.
### synth.saturation ###
*float* default: 1. For filter type 2 (modeled TB-303), this value controls a non-linear waveshaping (distortion) applied to the signal before entering the filter stage. A value of 1 means no saturation is added, higher values yield increasing distortion.

PolySynth
---
*Prototype: [Gibberish.Bus2](#miscellaneous-bus2)*  
*Mixin: [Gibberish.mixins.polyinstrument](#mixins-polyinstrument)*

`PolySynth` objects have the same properties as [Synth objects](#instruments-synth); when you change one of these property values all the child voices have their same property modified. The `maxVoices` option, which can only be set upon instantiation, determines the number of voices. Whenever a note is played a voice is chosen and connected to the `Synth` ugen, which acts as a bus. When the envelope of the note is finished the associated voice is disconnected from the `Synth` ugen.

```javascript
a = PolySynth({ maxVoices:3 }).connect()
a.chord([ 330,440,550 ])
```

# Effects

Bitcrusher
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

The `BitCrusher` effect provides both bit-depth and sample-rate reduction to create distortion.
```javascript
syn = Gibberish.instruments.Synth({ attack:44 })

crush = Gibberish.effects.BitCrusher({ 
  input:synth,
  sampleRate:.15
}).connect()

syn.note( 220 )
```

####Properties####
###bitcrusher.input###
*ugen* The unit generator that feeds the effect. Assign a `Bus` or `Bus2` instance to this property if you want multiple unit generators to connect to this effect.
###bitcrusher.sampleRate###
*float* range: 0-1, default: .5. Re-samples the input unit generator at a lower rate. A value of .5 (the default) means that every other sample will be sampled and held; a value of .25 means that every fourth sample will be sampled and held.
###bitcrusher.bitCrusher###
*float* range:0-1, default: .5. Decreases the dynamic range of the incoming signal and truncates values outside of the range.

BufferShuffler
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

The `BufferShuffler` effect feeds an input into a delay line, which is then randomly read at different speeds for granular effects.


```javascript
syn = Gibberish.instruments.Synth({ attack:44, decay:1152 }).connect()
seq = Sequencer.make( [220,330,440,550], [5512], syn, 'note' ).start()

shuffle = Gibberish.fx.Shuffler({ 
  input:syn,
  rate:22050,
  reverseChance:.5,
  mix:1
}).connect()
```

####Properties####
###shuffler.rate###
*int* Default:22050. Determines how often the shuffler should potentially shuffle. 
###shuffler.chance###
*float* Default:.25. The likelihood that shuffling will occur for any given window.
*int* Default:22050. Determines how often the shuffler should potentially shuffle. 
###shuffler.reverseChance###
*float* Default:.5. The likelihood that the buffer will play in reverse when it is shuffling.
###shuffler.repitchChance###
*float* Default:.5. The likelihood that the buffer will play at a speed that isn't `1` (or `-1` if `reverseChance` is greater than `0`).
###shuffler.repitchMin###
*float* Default:.5. The minimum rate for buffer playback if repitching occurs.
###shuffler.repitchMax###
*float* Default:2. The maximum rate for buffer playback if repitching occurs.
###shuffler.mix###
*float* Default:.5. The mix between the dry and wet signal. a value of`0` means only the dry signal is outputted, a value of `1` means only the wet signal is outputted.

Chorus
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

The `Chorus` effect is modeled after the ensemble effect found in the [Arp Solina-5 String Ensemble](https://www.youtube.com/watch?v=9iqZg0LQTWg) (based on a [Csound opcode by Steven Yi](https://github.com/kunstmusik/libsyi/blob/master/solina_chorus.udo). In this model, six parabolic oscillators are used (twelve when the effect is used with a stereo input) to modulate three delay lines (six in stereo). Three of the six oscillators are running at a "slow" speed (roughly .1 - .5 Hz) with individual phase offsets, to gradually create pitch fluctuations over time. The other three are running at a "fast" speed (roughly 2 to 8 Hz), again with individual phase offsets, to create vibrato. You can adjust amplitude and frequency of the three "slow" oscillators using the `slowFrequency` and `slowGain` properties, while the vibrato can be adjusted via `fastFrequency` and `fastGain`.

```javascript
syn = PolySynth({ waveform:'square', attack:44100 / 2, decay:88200 * 1.5, antialias:true, gain:.25 })
chorus = Chorus({ input: syn, slowGain:2 }).connect()
verb = Freeverb({ input: chorus, roomSize: .9, damping:.5 }).connect()

baseChord = [55,110,220,330,440,520]

seq = Sequencer.make( 
  [ 
    baseChord, 
    baseChord.map( v=> v * 1.2 ), 
    baseChord.map( v=> v * .8  ), 
    baseChord.map( v=> v * .95 )
  ], 
  [88200 * 2],
  syn, 
  'chord' 
).start()

kick = Kick().connect()
kickseq = Sequencer.make( [110], [22050], kick, 'note' ).start()
```

####Properties####
###chorus.input###
*ugen* The unit generator that feeds the effect. Assign a `Bus` or `Bus2` instance to this property if you want multiple unit generators to connect to this effect.
###chorus.slowFrequency###
*float* Default: .18. The frequency of the phasor that modulates the read position of the three 'slow' delay lines, which create more gradual pitch fluctuations over time.
###chorus.slowAmp###
*float* Default: 1. Controls the amount of delay line modulation for the three 'slow' delay lines.
###chorus.fastFrequency###
*float* Default: .18. The frequency of the phasor that modulates the read position of the three 'fast' delay lines, which combine to create a vibrato effect. 
###chorus.fastAmp###
*float* Default: 1. Controls the amount of delay line modulation for the three 'fast' delay lines.

Delay
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

The `Delay` delays an incoming signal. It also provides a simple feedback control.
 
```javascript
syn = Gibberish.instruments.Synth({ attack:44 })

delay = Gibberish.effects.Delay({ 
  input:synth,
  delayTime: 5512,
  feedback: .9
}).connect()

syn.note( 220 )
```

####Properties####
###delay.input###
*ugen* The unit generator that feeds the effect. Assign a `Bus` or `Bus2` instance to this property if you want multiple unit generators to connect to this effect.
###delay.delayTime###
*int* default: 11025. The number of samples to delay the incoming signal by.
###delay.feedback###
*float* range:0-1, default: .925. The amount of delayed signal to be fed back into the delay line.
###delay.wetdry###
*float* range:0-1, default: .5. The ratio of immediate to delayed signal in the output. A value of `1` means only the delayed output is heard. 
 
Distortion
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

A port of the hyperbolic tangent distortion found in Csound: https://csound.github.io/docs/manual/distort1.html

This is a non-linear distortion that can react dramatically differently to different sounds. The primary driver of the distortion is the `pregain` property,
while the `shape1` and `shape2` properties control whether hard-clipping or soft-clipping is used. A post-effect scalar, `postgain`, can be used to tame out-of-control signals.

```javascript
syn = Gibberish.instruments.Karplus({ attack:44 })

dist = Gibberish.effects.Distortion({ 
  input:syn,
  pregain:100,
  postgain:.25,
}).connect()

syn.note( 440 )
```

####Properties####
###distortion.input###
*ugen* The unit generator that feeds the effect. Assign a `Bus` or `Bus2` instance to this property if you want multiple unit generators to connect to this effect. 
###distortion.pregain###
*float* range: 0-max, default: 5. A scalar applied to the input signal as part of the distortion formula. Increasing this value will increase the amount of distortion; however, you may also need to turn down the `postgain` property to avoid loud signals.  
###distortion.postgain###
*float* range:0-max, default: .5. A scalar applied to the output signal. 
###distortion.shape1###
*float* range:0-max, default: 0. A zero-value indicates hard-clipping will be used on the positive axis of the waveshaping; small positive values will use soft-clipping. 
###distortion.shape2###
*float* range:0-max, default: 0. A zero-value indicates hard-clipping will be used on the negative axis of the waveshaping; small positive values will use soft-clipping. 

Flanger
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

The `Flanger` creates a modulated delay line, with adjustable feedback.
 
```javascript
syn = Gibberish.instruments.Synth({ attack:44 })

delay = Gibberish.effects.Flanger({ 
  input:synth,
  delayTime: 5512,
  feedback: .9
}).connect()

syn.note( 220 )
```

####Properties####
###flanger.input###
*ugen* The unit generator that feeds the effect. Assign a `Bus` or `Bus2` instance to this property if you want multiple unit generators to connect to this effect.
###flanger.frequency###
*ugen* The frequency of the sine oscillator that modulates the read position of the delay line.
###flanger.offset###
*float* range: 0-1, default: .25. Controls the center offset of the modulated delay line. Larger values will result in wider pitch fluctuations.
###flanger.feedback###
*float* range:0-1, default: .925. The amount of delayed signal to be fed back into the delay line.

Freeverb
----
*Prototype: [Gibberish.prototypes.effect](#prototypes-effect)*

The `Freeverb` effect is based on the Schroeder-Moorer model of reverberation. One of its main strengths is easy control via two primary properties: `roomSize` to set the amount of reverberation and `damping` to attenuate high frequencies. 

```javascript
syn = Gibberish.instruments.Synth({ attack:44 })

verb = Gibberish.effects.Freeverb({ 
  input:synth,
  roomSize:.95
}).connect()

syn.note( 220 )
```

####Properties####
###freeverb.input###
*ugen* The unit generator that feeds the effect. Assign a `Bus` or `Bus2` instance to this property if you want multiple unit generators to connect to this effect.
###freeverb.roomSize###
*float* range: 0-1, default: .84. This is an important control of the overall reverberation time. Technically, it controls the amount of feedback used by the comb filters that are part of the Freeverb algorithm.
###freeverb.damping###
*float* range:0-1, default: .5. This value attenuates high-frequency signals in the reverberation by low-pass filtering from one sample to the next in the comb filters. Low values simulate reflective walls.
###freeverb.dry###
*float* range: 0-1, default: .5. Controls the amount of non-reverberated signal sent to the output.
###freeverb.wet1###
*float* range: 0-1, default: 1. Controls the amount of reverberated signal sent to the left output. When this value is significantly different from the `wet2` property, there w