README
web-audio-assembler
This is not even alpha software. It's an exploration of an idea
The aim of this project is answer the question: how to convert the highly imperative web audio api into something more compatible with a functional programming approach? In fact, the first purpose of this project is to access Web Audio API from Elm lang.
The idea it's old and popular: instead of use the API, create an object with the description of what you want and let web-audio-assembler
to do the work.
Requirements:
- The node graph descriptor must be JSON serializable
- Create Web Audio API modules delcaratively
- Connect modules to modules or audio params
- Update and schedule updates of those node graphs
- Allow other software (for example, audio user interfaces) to discover properties and capabilities of node graph
You can see the Live Examples or read the generated API documentation
How-to
Assemble audio nodes
Create simple nodes
Use the assemble
function to create a function that returns a node:
var ac = new AudioContext()
var Assembler = require('web-audio-assembler')
var Osc = Assembler.assemble({
node: 'oscillator',
type: 'sine',
frequency: 400,
connect: '$context'
})
var osc = Osc(ac)
osc.start()
Create more complex node graphs
You can create a complex node graph by using an object. Also you can use the connect
property to connect one node to the other:
var Synth = Assembler.assemble({
name: 'microsynth',
amp: {
node: 'gain',
connect: '$context'
},
filter: {
node: 'filter',
type: 'lowpass',
frequency: '500',
connect: 'amp'
},
osc: {
node: 'oscillator',
type: 'sine'
connect: 'filter'
}
})
var synth = Synth(ac)
synth.osc.start(ac.currentTime)
// or
Assembler.start(synth, ac.currentTime) // start all startable nodes (oscillators, audio sources, envelopes)
Assembler.stop(synth, ac.currentTime) // stop all stoppable nodes
Assembler.dispoase(synth) // dispose all nodes
Schedule updates
There's a way to schedule updates in the node. You pass an array with update objects with the form { target: <node.path>, time: <relative time in secs>, ...}
:
Assembler.schedule(synth, ac.currentTime, [
{ target: 'filter.frequency', value: 400, time: 0 },
{ target: 'osc', trigger: 'start', time: 0 },
{ target: 'filter.frequency', value: 400, time: 1 }
])
Notice the time
value of the update events are relative to the time passed to the schedule
function.
TODO
- Currently only Oscillator, Gain, BiquadFilter and Delay nodes are implemented.
- Use custom nodes generators (envelopes, for example)
- Combine node graphs
- Describe node graphs (to generate synth UIs for example)
- Add yours...
Run tests and examples
Clone this repository and run npm install && npm test
. You can open the .html files of the examples
directory directly (no server required).
References, links and related projects
- Web Audio API, of course: https://www.w3.org/TR/webaudio/
- clojure.spec (I'm thinking in a kind of spec of web audio)
- A standardized framework for building and including Web Audio API instrument/effect "patches": https://github.com/h5bp/lazyweb-requests/issues/82
- Flocking uses a similar approach to build synths: https://github.com/colinbdclark/flocking
- https://github.com/charlieroberts/genish.js
License
MIT License