Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const ctx = new AudioContext();
const osc = ctx.createOscillator();
osc.connect(ctx.destination);
osc.start();

Try it

JS Render a tone silently with OfflineAudioContext

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Play a short beep with a button

Syntax

JavaScript
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.