Connection and Parameter

Perhaps the most important thing in the world of audio programming is connecting components and the precise control of parameter. This documentation describes how WAAX utilities can make the audio programming easy.

If you are not familiar with basic features in Web Audio API, this HTML5ROCKS article can help you.

Creating Web Audio API Nodes

For the starter, WAAX offers shorthands for node creators in Web Audio API. Here's the list:

WX.Gain              <=>      AudioContext.createGain
WX.OSC               <=>      AudioContext.createOscillator
WX.Delay             <=>      AudioContext.createDelay
WX.Filter            <=>      AudioContext.createBiquadFilter
WX.Comp              <=>      AudioContext.createDynamicsCompressor
WX.Convolver         <=>      AudioContext.createConvolver
WX.WaveShaper        <=>      AudioContext.createWaveShaper
WX.Source            <=>      AudioContext.createBufferSource
WX.Analyzer          <=>      AudioContext.createAnalyser
WX.Panner            <=>      AudioContext.createPanner
WX.PeriodicWave      <=>      AudioContext.createPeriodicWave
WX.Splitter          <=>      AudioContext.createChannelSplitter
WX.Merger            <=>      AudioContext.createChannelMerger
WX.Buffer            <=>      AudioContext.createBuffer

Making Connections

WAAX adds few methods to AudioNode and AudioParam in Web Audio API. Note that AudioNode is an atomic unit in Web Audio API such as oscillator, gain, filter. AudioParam is an object in AudioNode for user-controllable (and modulatable) parameter.

Here we create 1 oscillator node and 3 gain nodes.

var osc = WX.OSC();
var gain1 = WX.Gain();
var gain2 = WX.Gain();
var gain3 = WX.Gain();

For making connections from the oscillator to each gain node, we use .connect() method.

osc.connect(gain1);
osc.connect(gain2);
osc.connect(gain3);

This can be shortened with .to() method. This type of connection is often called 'fan-out.'

osc.to(gain1, gain2, gain3);

If you rather want to have a 'chain' than 'fan-out', you can also use .to() method to chain multiple nodes.

osc.to(gain1).to(gain2).to(gain3);

To cut a connection, use .cut() method. Note that selective disconnection is currently not supported in Web Audio API but it will be implemented in the near future as the spec change suggests.

osc.cut();

Parameter Control

The parameter control in Web Audio API is fairly complex compared to the other audio programming platform. This is primarily due to the sample-accurate scheduling mechanism. Technically, the place where you run your command is different with the place where things actually happen. It is a typical asynchronous scenario and not ideal situation for audio programming.

The bottom line is: to control parameter precisely we need to schedule it ahead. For that purpose, we have AudioParam object in Web Audio API. It allows us to do sample-accurate automation by scheduling events ahead. Here are default AudioParam methods.

AudioParam.setValueAtTime (value, startTime)
AudioParam.linearRampToValueAtTime (value, endTime)
AudioParam.exponentialRampToValueAtTime (value, endTime)
AudioParam.setTargetAtTime (target, startTime, timeConstant)
AudioParam.cancelScheduledValues (startTime)

WAAX unifies first 4 methods into a single one.

AudioParam.set(val, time, rampType)

rampType can be step(0), linear(1), expo(2), or target(3). When the rampType is 'target', the second argument will be an array of two time values. The following example create a pitch modulation from 440Hz to 880Hz, and then back to 440 in 1 second.

var osc = WX.OSC();
osc.frequency
    .set(440, 0.0, 'step')
    .set(880, 0.25, 1)
    .set(440, [0.25, 0.75], 3);

To cancel the scheduled value, simply call .cancel() method.

osc.frequency.cancel();