Instruments

View the source. Import with require('v1/instruments');

Oscillator

The Oscillator class provides a basic sound wave. You can play the resulting sound directly, or, more likely, process the sound with another class in the library, such as Filter, Envelope, or Mixer.

Constants

• Oscillator.SINE Wave type. Smooth sine waveform.

• Oscillator.SQUARE Wave type. Square waveform.

• Oscillator.SAWTOOTH Wave type. Sawtooth waveform.

• Oscillator.TRIANGLE Wave type. Triangle waveform.

• Oscillator.NOISE Wave type. Random samples between -1 and 1.

Wave types: https://en.wikipedia.org/wiki/Waveform

Constructor

Arguments

Usage: new Oscillator({type: Oscillator.SQUARE});

• type: Optional. Default Oscillator.SINE. The type of sound wave to generate. Accepts any wave type constant.

• frequency: Optional. Default 440. Number, or a function that takes a time parameter and returns a frequency. The time argument specifies how long the oscillator has been running.

• amplitude: Optional. Default 1. Number, or a function that takes a time parameter and returns an amplitude multiplier. Not in dB's. the time argument specifies how long the oscillator has been running.

• phase: Optional. Default 0. Number, or a function that takes a time parameter and returns a phase shift. the time argument specifies how long the oscillator has been running. This is an advanced parameter and can probably be ignored in most cases.

Returns

A Mixable. An instance-like closure that wraps the values passed at instantiation. This follows the (time) -> sample convention for use in play() and buildSample().

instance.setFrequency(frequency)

Arguments

Either:

• A number value indicating frequency in Hz.
• Or a function that accepts a time parameter and returns a number value indicating frequency in Hz.

Returns

The frequency argument

instance.getFrequency()

Arguments

None

Returns

The last-rendered frequency value in Hz. If frequency is a function, this calculates the last value and returns the result.

instance.setPhase(phase)

Arguments

Either:

• A number value indicating phase shift in radians.
• Or a function that accepts a time parameter and returns a number value indicating phase shift in radians.

Returns

The phase argument

instance.getPhase()

Arguments

None

Returns

The last-rendered phase shift in radians. If phase is a function, this calculates the last value and returns the result.

instance.setAmplitude(amplitude)

Arguments

Either:

• A number value specifying the amplitude coefficient (not dB gain).
• Or a function that accepts a time parameter and returns the amplitude coefficient.

Returns

The amplitude argument.

instance.getAmplitude()

Arguments

None

Returns

The last-rendered amplitude value. If amplitude is a function, this calculates the last value and returns the result.

Usage

Basic Wave

require('v1/instruments');
var oscillator = new Oscillator({frequency: A_3});
var buildSample = function(time){
   return oscillator(time);
}

Basic Triangle Wave

require('v1/instruments');
var oscillator = new Oscillator({frequency: A_3, type: Oscillator.TRIANGLE});
var buildTrack = function(){
   this.play(oscillator);
}

Basic Square Wave

require('v1/instruments');
var oscillator = new Oscillator({frequency: A_3, type: Oscillator.SQUARE, amplitude: 0.7});
var envelope = new Envelope();
var buildTrack = function(){
   this.play(envelope.process(oscillator));
}

Vibrato

require('v1/instruments');
var phaseModulation = function(time){ return 0.2 * Math.sin(TWO_PI * time * 5); }
var oscillator = new Oscillator({frequency: A_3, phase: phaseModulation});
var buildTrack = function(){
   this.play(oscillator);
}

Hi Hat

require('v1/instruments');
var oscillator = new Oscillator({frequency: A_3, type: Oscillator.NOISE});
var filter = new Filter({type: Filter.HIGH_PASS, frequency: 12000});
var envelope = new Envelope({decayTime: 0.3});
var buildTrack = function(){
   this.play(envelope.process(filter.process(oscillator)));
}

Change Frequency

require('v1/instruments');
var oscillator = new Oscillator({frequency: A_3});
var buildTrack = function(){
   this.play(oscillator);
   this.after(3, function(){
     oscillator.setFrequency(C_5);
   });
}

Envelope

Shapes the sound wave passed into process().

Constants

• Envelope.AD: Attack Decay envelope type. Only the attackTime and decayTime parameters are used.

  AD Envelope - Amplitude:
    /\         1
   /  \
  /    \       0
  
  |-|          Attack phase
     |-|       Decay phase
  

• Envelope.ADSR Attack Decay Sustain Release envelope type. All constructor parameters are used.

  ADSR Envelope - Amplitude:
    /\         1
   /  \____    sustainLevel
  /        \   0

  |-|          Attack phase
    |-|        Decay phase
      |---|    Sustain phase
          |-|  Release phase

Constructor

Usage:

new Envelope({
  type:         Envelope.ADSR,
  attackTime:   0.1,
  decayTime:    0.1,
  sustainTime:  1,
  releaseTime:  1,
  sustainLevel: 0.5
});

Arguments

• type: Optional. Default Envelope.AD. Accepts any envelope type.
• attackTime: Optional. Default 0.03. Value in seconds.
• decayTime: Optional. Default 1.0. Value in seconds.
• sustainTime: Optional. Default 0. Value in seconds. Ignored unless envelope type is Envelope.ADSR.
• releaseTime: Optional. Default 0. Value in seconds. Ignored unless envelope type is Envelope.ADSR.
• sustainLevel: Optional. Default 0. Value in seconds. Ignored unless envelope type is Envelope.ADSR.

instance.process(mixable)

Arguments

A Mixable. A single instance of Oscillator, or the return value from another process() call.

Returns

A Mixable. An object that can be passed into play(), used in buildSample(), or passed into another process() method. More precisely process() returns a closure in the format of (time) -> sample.

Usage

Simple AD Envelope

require('v1/instruments');
var o = new Oscillator;
var e = new Envelope;
var processor = e.process(o);
var buildSample = function(time) {
  return processor(time);
}

Simple AD Envelope (buildTrack version)

require('v1/instruments');
var o = new Oscillator;
var e = new Envelope;
var buildTrack = function() {
  this.play(e.process(o));
}

ADSR Envelope

require('v1/instruments');
var o = new Oscillator;
var e = new Envelope({type: Envelope.ADSR, sustainTime: 1, releaseTime: 1, sustainLevel: 0.5});
var buildTrack = function() {
  this.play(e.process(o));
}

Mixer

A mixer primarily does two things: adjust the volume of a signal, and add multiple signals together into one.

Most process() methods only allow a single argument. If you'd like to process multiple signals, you can combine them using this class.

Constants

None

Constructor

Usage: new Mixer({gain: -8.0});

Arguments

• gain: Gain amount in dB. Optional. Default -7.0. Float value.

Returns

An object with a process() method, ready to accept multiple oscillators, or any results of calls to other process() methods.

instance.process(mixable1, mixable2, ...)

Arguments

One or more Mixables. Instances of Oscillator or the returned values from other process() calls.

Returns

A Mixable. An object that can be passed into play(), used in buildSample(), or passed into another object's process() method. More precisely, process() returns a closure in the format of (time) -> sample.

Usage

Mix Two Oscillators

var oscillator1 = new Oscillator();
var oscillator2 = new Oscillator({frequency: A_4});
var mixer = new Mixer({ gain: -5.0 });
var processor = mixer.process(oscillator1, oscillator2);
var buildSample = function(time){
  return processor(time);
}

Mix Two Oscillators (buildTrack version)

var oscillator1 = new Oscillator();
var oscillator2 = new Oscillator({frequency: A_4});
var envelope = new Envelope();
var mixer = new Mixer({ gain: -5.0 });
var processor = envelope.process(mixer.process(oscillator1, oscillator2));
var buildTrack = function(){
  this.play(processor);
}

Filter

Utility class to attenuate the different frequency components of a signal.

For example white noise (e.g.: (t) -> Math.random() * 2 - 1), contains a wide range of frequencies. By filtering this noise you can shape the resulting sound. This is best understood through experimentation.

This class implements a Biquad filter, a workhorse for general-purpose signal processing.

Filters are complex. It's not always intuitive how a parameter value will affect the filter's frequency response. It may be helpful to use a frequency response calculator like this one, which is really nice: http://www.earlevel.com/main/2013/10/13/biquad-calculator-v2/

Constants

• Filter.LOW_PASS: Filter type. Let low frequencies through.
• Filter.HIGH_PASS: Filter type. Let high frequencies through.
• Filter.BAND_PASS_CONSTANT_SKIRT: Filter type. Let a range of frequencies through. Optionally uses the band width parameter (filter.setBW(width)).
• Filter.BAND_PASS_CONSTANT_PEAK: Filter type. Let a range of frequencies through. Optionally uses the band width parameter (filter.setBW(width)).
• Filter.NOTCH: Filter type. Remove a narrow range of frequencies.
• Filter.ALL_PASS: Filter type. Let all frequencies through.
• Filter.PEAKING_EQ: Filter type. Boost frequencies around a specific value. Optionally uses the setDbGain value.
• Filter.LOW_SHELF: Filter type. Boost low-frequency sounds. Optionally uses the setDbGain value.
• Filter.HIGH_SHELF: Filter type. Boost high-frequency sounds. Optionally uses the setDbGain value.

Constructor

Usage: new Filter({type: Filter.LOW_PASS, frequency: 300})

Arguments

• type: Optional. Default Filter.LOW_PASS. Accepts any filter type.
• frequency: Optional. Default 300. A value in Hz specifying the midpoint or cutoff frequency of the filter.

Returns

An object with a process() method, ready to accept multiple oscillators, or any results of calls to other process() methods.

instance.getFrequncy()

Arguments

None

Returns

The midpoint frequency in Hz.

instance.setFrequncy(frequency)

Sometimes referred to as the center frequency, midpoint frequency, or cutoff frequency, depending on filter type.

Arguments

Number value representing center frequency in Hz. Default 300.

Returns

The frequency argument.

instance.getQ()

Arguments

None

Returns

The Biquad Q factor.

instance.setQ(value)

Arguments

Number value representing the filter's Q factor. Only used in some filter types. To see the impact Q has on the filter's frequency response, use the calculator at: http://www.earlevel.com/main/2013/10/13/biquad-calculator-v2/

Returns

The argument.

instance.getBW()

Arguments

None

Returns

The band width.

instance.setBW(bandWidth)

Arguments

A number representing the band width. You may want to view the library source to understand how this affects the filter.

Returns

The argument.

instance.process(mixable)

Arguments

A Mixable. A single instance of Oscillator or the returned value from another process() call (such as Mixer).

Returns

A Mixable. An object that can be passed into play(), used in buildSample(), or passed into another object's process() method. More precisely, process() returns a closure in the format of (time) -> sample.

Usage

Basic Filter

  require('v1/instruments');
  var oscillator = new Oscillator({type: Oscillator.SQUARE, frequency: 55})
  var filter = new Filter();
  var processor = filter.process(oscillator);
  var buildSample = function(time){
    return processor(time);
  }

Basic Filter (buildTrack version)

  require('v1/instruments');
  var oscillator = new Oscillator({frequency: A_3, type: Oscillator.NOISE});
  var filter = new Filter({type: Filter.HIGH_PASS, frequency: 10000});
  var envelope = new Envelope();
  var buildTrack = function(){
   this.play(envelope.process(filter.process(oscillator)));
  }