Tutorials Developer

Web Audio for Browser-Based Media Tools

Intermediate · ~20 min

Overview

Web Audio is one of the most capable APIs in the browser and one of the most underused. It is a full node-graph audio engine with real filters, analysis, and faster-than-real-time offline rendering, which makes genuinely useful audio tools possible entirely client-side. This guide covers the model, what it is good and bad at, and the practical obstacles (autoplay policy, latency, and mobile memory) that shape what you can ship.

What You Need

A browser, which is genuinely the whole toolchain for prototyping
An understanding of signal flow as a graph rather than a sequence
A user gesture to start audio, which the platform requires
AudioWorklet for any custom processing, rather than deprecated alternatives
Real mobile devices for testing memory and performance
Test material at the sample rates you intend to support

Steps

Think in graphs, not in steps

Web Audio connects source nodes through processing nodes to a destination. Signal flows along connections rather than through a sequence of function calls, and nodes run in the audio thread independently of your JavaScript. Getting this model right first makes everything else straightforward. Fighting it produces awkward code.

Start the context from a user gesture

Browsers block audio that begins without user interaction, so an AudioContext created on page load starts suspended and produces silence. Create or resume it inside a click or tap handler. This is the single most common reason a working local prototype produces nothing when deployed.

Automate parameters rather than setting them repeatedly

Audio parameters can be scheduled with ramps and curves that execute precisely in the audio thread. Setting values from JavaScript on a timer produces audible stepping and clicks, because your code does not run in sync with audio processing. Use the scheduling methods for anything that changes over time.

Use offline rendering for export

An offline context renders a graph faster than real time and gives you the resulting buffer to encode or download. This is how you export processed audio without making the user listen through it, and it is the basis of any browser tool that produces a file. The same graph should drive both preview and export so what users hear is what they get.

Put custom processing in an AudioWorklet

Anything you cannot build from the built-in nodes belongs in an AudioWorklet, which runs on the audio thread. The older script-processor approach ran on the main thread and produced glitches under load. Worklets have a stricter programming model and are the only viable option for real custom DSP.

Budget memory carefully on mobile

Decoded audio buffers are large, an hour of stereo audio at full float precision is substantial, and mobile browsers terminate tabs that allocate too much, with limits that are neither published nor consistent. Cap durations, render in sections where you can, and test on a mid-range phone rather than a desktop.

Pro Tips

Create or resume the AudioContext inside a user gesture. It is the most common deployment surprise.
Use parameter automation rather than JavaScript timers for anything that changes over time.
Drive preview and export from the same graph so what users hear is what they download.
Test memory on a real mid-range phone. Desktop tolerances are not representative.
Prefer built-in nodes where they exist. They run natively and are considerably faster than custom code.

Knowledge Base

What You'll Learn

Web Audio is a genuine audio engine rather than a playback API, and its constraints come from running in a browser. Below: what it is good and bad at, and the offline rendering pattern that makes export work.

What Web Audio Is Good At, and What It Is Not

It is genuinely good at synthesis, real-time processing, and analysis. The built-in nodes include proper resonant filters, dynamics processing, convolution for reverb, delays, waveshaping, and frequency analysis, all running natively rather than in JavaScript. Building a synthesiser, an effects chain, a metering tool, or a spectrum analyser is well within scope and performs well.

It is also good at precise scheduling. Parameter automation executes in the audio thread with sample accuracy, which is why sequenced and musical applications work reliably where a JavaScript timer would not.

It is not designed for encoding to compressed formats: you get raw samples and need something else to produce an MP3 or AAC, which is where WebCodecs or a library comes in. It is also poor at handling very long material in memory, since buffers are uncompressed and large.

And latency is not controllable to the degree native audio applications expect. For most tools this is irrelevant. For live monitoring while recording it is a real limitation.

The Offline Rendering Pattern

The pattern that makes browser audio tools genuinely useful is rendering the same graph offline to produce a file.

An offline context runs a node graph as fast as the machine allows rather than in real time, and hands you the resulting buffer when finished. A three-minute render might complete in a couple of seconds, which means a user can export processed audio without listening through it.

The important discipline is that preview and export should use the same graph construction. If the live preview is built one way and the export another, they will diverge, and the divergence is discovered by users reporting that the download does not match what they heard. Building one function that constructs the graph, used by both paths, prevents an entire class of bug.

Memory is the constraint. The rendered buffer is uncompressed floating-point audio, so a long render allocates a great deal at once. Capping duration based on available memory, or rendering in sections and assembling, is what makes this viable on mobile, where the tab is terminated rather than the allocation failing gracefully.

Where This Fits

This guide covers one specific part of building media applications. The wider picture, why media workloads break ordinary web architecture, and the upload, job, and toolchain patterns that handle them, is in Building Media Applications: A Developer Primer, which frames the discipline as a whole and links out to the detailed guides underneath it, including this one. If you are starting from scratch rather than solving a specific problem, read that first and come back here.

FAQ

Q: Why does my Web Audio code produce no sound when deployed?
A: Almost certainly autoplay policy. Browsers block audio that starts without user interaction, so an AudioContext created on page load begins suspended. Create or resume it inside a click or tap handler. It works locally in development because you have usually interacted with the page already.

Q: Can Web Audio export an MP3 or other compressed file?
A: Not on its own. It gives you raw samples. Render the graph in an offline context to get a buffer, then encode it with WebCodecs or an encoding library, or write it directly to WAV which needs no encoder. The rendering and the encoding are separate concerns.

Q: How do I do custom audio processing?
A: AudioWorklet, which runs on the audio thread. The older script-processor approach ran on the main thread and glitched under load. Worklets impose a stricter programming model but are the only viable option for real custom DSP. Prefer built-in nodes wherever they cover what you need, since they run natively.

Q: Why does my audio tool crash on phones?
A: Memory. Decoded audio buffers are uncompressed and large, and mobile browsers terminate tabs that allocate too aggressively, with limits that are neither published nor consistent. Cap durations, render long output in sections, and test on a mid-range device rather than a desktop or a flagship.