JavaScript library for music and audio programming on Chrome (r5)
The newer version of library (r12) will be pushed around the early October and it will include various enhancements and extra elements: Web MIDI API support, Polymer-powered musical UI widgets, and a couple of impressive examples. Stay tuned!
The information below is for the previous revision (r5) and will be deprecated with the release of the newer revision (r12) since it is a major update of library including several fundamental changes. Sorry for your inconvineince!
// creating units
var saw = new WX.Oscil({ type:"sawtooth" }),
sqr = new WX.Oscil({ type:"square" }),
lpf = new WX.ModLPF({ cutoff:2500, Q:12 }),
env = new WX.ADSR({ a:0.001, d:0.002, s:0.3, r:0.1 }),
vrb = new WX.ConVerb({ source:"ir/hall.wav", mix:0.3 });
// building an audiograph
WX.link(saw, lpf, env, vrb, WX.DAC);
// connecting units
sqr.to(lpf);
WAAX is an experimental JavaScript library built on top of Web Audio API in Chrome. With music creation and production in mind, it is designed to offer the higher level of functionality than basic building blocks of Web Audio API.
The goal of this project is 1) to facilitate experiments and iterations of web-based audio programming and 2) to hide audio-specific chores from web developers who are not familiar with audio programming. This library is designed to be used with other JavaScript APIs available on modern web browsers.
The facade of API is strongly inspired by THREE.js and ChucK: Three.js is one of WebGL JavaScript libraries widely being used for web-based 3D graphics. ChucK is an experimental audio programming language being actively developed and used by computer music communities such as PLOrk(Princeton Laptop Orchestra) and SLOrk(Stanford Laptop Orchestra).
As this library is in early stages of development, it currently demonstrates minimum set of features, however, it will embrace more elements as it grows: ready-made instruments, comprehensive timebase system (in conjunction with Web MIDI API), and musical interconnection between multiple Chrome clients.
FireFox has recently started implementing Web Audio API and it's partially available in the Nightly Build. Safari also has the implementation of Web Audio API but it is slightly outdated compared to the one in Chrome.)
Requirements: Google Chrome 20+ on any platform (Win/OSX/Linux). You can check the availability of the API in different web browsers here.
- mini-IDE (which includes all the examples below)
- Hello WAAX
- WAAX does THX
- Acidic Bassline
- Simple Drum Sampler
- Take the I train
- Custom Visualizer
- WAAX GUI (pilot)
Adjust your volume setting before clicking. It might be loud!
// creating a sampler and a compressor units
var kick = new WX.Sampler({ source: "kd.wav", basePitch: 60 }),
comp = new WX.Comp();
Like the node in Web Audio API, WAAX has its own atomic object called unit. It is conceptually identical to the 'unit generator' of other audio programming environments. A unit can be created with initial parameters, or it can be set with default parameters when created with no argument.
// connecting units with .to() method
kick.to(comp).to(WX.DAC);
// equivalent to the above
WX.link(kick, comp, WX.DAC);
As shown above, the connection between several WAAX units can be achieved by chaining .to()
methods. Alternatively, the WX.link()
method can be used to build an audiograph out of multiple units. WX.DAC
is the master output of WAAX system.
// native Web Audio API node
var node = myAudioContext.createGain();
// unit => node
kick.connect(node);
// node => unit
node.connect(comp._inlet);
The connection from a WAAX unit to Web Audio API node can be done by .connect()
method, which is the same method in Web Audio API, but the connection from a node to a unit should be done manually with ._inlet
node from a unit. This enables to use the library in conjunction with plain Web Audio API codes.
note: this will be changed in the next revision.
comp.threshold = -12;
comp.ratio = 8.0;
kick.params = { source:"kd2.wav", basePitch:48 };
console.log(kick.source);
>>> "kd2.wav"
console.log(kick.params);
>>> { source:"kd2.wav", basePitch:48 }
All the parameters of a unit is accessible by simply setting or getting values. Alternatively, passing a javascript object literal with parameters into .params
is also possible. Getting available parameters from a unit can be done by printing out .params
as well.
Visualization : Example
// creating waveform display with target canvas ID
var wf = new WX.Waveform({ canvas:"CANVAS-ID" });
// connecting compressor unit to waveform visualizer
comp.to(wf);
// draw waveform
wf.draw();
Using a set of units called Analyzers, visualizing waveforms and spectrum can be achieved instantly. The visual content will be automatically resized according to the size of the target canvas DOM element.
// playNote function
function playNote(next) {
adsr.noteOn(next);
adsr.noteOff(next + 1.0);
}
// looping playNote() infinitely every 3 seconds
var myLoop = new WX.Loop(playNote, 0, 3.0);
myLoop.start();
Triggering events with super-accurate timing is a quite involved task on the web browsers due to the nature of setTimeout()
or setInterval()
function. However, the WX.Loop()
object provides the sample-accurate looping mechanism. The API for sample-accurate event management is the key objective of this library and it will be expanded to accommodate more complex musical forms. (The detailed description of the scheduling mechanism can be found here.)
GUI : Example
// div for UI panel
var panel = document.getElementById("wx-uipanel");
// a knob
var ka = new WX.UIKnob({
targetDiv:panel, label:"Attack",
x:250, y:485, offset: 0.001, scale: 0.5, value: 0.2
});
// targeting an attack parameter in an ADSR unit
ka.setTargetValue(adsr, "a");
The basic GUI interaction is implemented in the current revision (r5): vertical/horizontal slider, and a knob. WAAX units have "modulation targets" that can be controlled by various modulation sources such as GUI components or even other units simply by putting a single line of code.
As WAAX is in early stages of development, there are several components (which are yet to be released publicly) to be incorporated into this library in the near future. I am currently expanding its sonic vocabulary by adding more units to the library. The followings are a basic set of units as the first milestone. A detailed documentation for various units will be available soon.
WX.Oscil
WX.Noise
WX.Sampler
WX.LFO
WX.ImpTrain
WX.ADSR
WX.ModLPF
WX.LPF
WX.TwinDelay
WX.ConVerb
WX.Comp
WX.C2
WX.Waveform
WX.Spectrum
WX.Visualizer
WX.UISliderH
WX.UISliderV
WX.UIKnob
WX.random2
WX.random2f
WX.db2lin
WX.lin2db
WX.pitch2freq
WX.freq2pitch
This project is initiated and managed by hoch(Hongchan Choi) at CCRMA/Stanford University. Please refer LICENSE file (MIT License) for more info.