JavaScript Reference ยท Browser and Web APIs
The Web Audio API
Reference for the Web Audio API: AudioContext, OscillatorNode, GainNode, connecting nodes, autoplay rules, scheduling and rendering offline with OfflineAudioContext.
The Web Audio API builds sound from a graph of nodes. A source node produces audio (an oscillator, a decoded file, a microphone), effect nodes change it (gain, filters, delay, panning), and the graph ends at context.destination, which is the speakers. You create an AudioContext, make nodes with its factory methods, and join them with connect().
All timing is done on the context's own clock, context.currentTime, in seconds. That clock is far more precise than setTimeout(), so you schedule sounds ahead of time with methods like osc.start(time) and gain.gain.setValueAtTime(). For reading and writing audio files and streaming <audio> elements, see the media elements; Web Audio is for synthesis, effects and analysis.
const ctx = new AudioContext(); const osc = ctx.createOscillator(); osc.connect(ctx.destination); osc.start();
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
const ctx = new AudioContext(options) const node = ctx.createGain() // also createOscillator(), createBiquadFilter(), ... sourceNode.connect(destinationNode) sourceNode.disconnect() ctx.resume() ctx.close()
| Member | Description |
|---|---|
ctx.state |
"suspended", "running" or "closed". |
ctx.currentTime |
Seconds since the context started. Only moves while running. |
ctx.sampleRate |
Samples per second, commonly 44100 or 48000. |
ctx.destination |
The final output node (speakers). |
ctx.decodeAudioData(arrayBuffer) |
Decodes a file into an AudioBuffer. Returns a promise. |
AudioParam (such as gain.gain, osc.frequency) |
Has value plus scheduling methods: setValueAtTime(), linearRampToValueAtTime(), exponentialRampToValueAtTime(), setTargetAtTime(). |
Common nodes: OscillatorNode (type sine, square, sawtooth, triangle), GainNode, BiquadFilterNode, DelayNode, StereoPannerNode, AnalyserNode (for visualizers), AudioBufferSourceNode (plays a decoded buffer), MediaElementAudioSourceNode.
Return values: connect() returns the destination node, which allows chaining. start() and stop() return undefined. Exceptions: calling start() twice on one source throws InvalidStateError; exponentialRampToValueAtTime() throws RangeError for a target value of 0.
Usage notes
- Autoplay policy. Browsers keep a context
"suspended"until the user has interacted with the page. Create or resume it inside a click handler. - Source nodes are one-shot. An oscillator or buffer source can be started once; create a new one for each sound. They are cheap.
- Avoid clicks. Jumping a gain from 1 to 0 instantly makes a pop. Ramp over a few milliseconds instead.
- Exponential ramps cannot reach 0. Ramp to a tiny value such as
0.001. - Schedule with
currentTime, not timers, for rhythm and sequences. - Free resources. Disconnect unused nodes and call
ctx.close()when finished. Browsers limit the number of live contexts. - Latency and permissions: nothing here needs a permission prompt; microphone input does, through
getUserMedia().
Browser support
AudioContext and the core nodes are supported in all current browsers. Some browsers still need the older webkitAudioContext name for very old versions, and newer nodes such as AudioWorklet vary, so check a compatibility table.