AudioContext
The AudioContext interface inherits from BaseAudioContext.
It is responsible for supervising and managing audio-processing graph.
Constructor
constructor(options?: AudioContextOptions)
AudioContextOptions
| Parameter | Type | Default | |
|---|---|---|---|
sampleRate Optional | number | - | The preferred sample rate for the context. |
latencyHint Optional | 'interactive' | 'balanced' | 'playback' | 'interactive' | What the context should optimize its output stream for. interactive requests the lowest latency the platform offers; balanced and playback trade output latency for a deeper buffer, which favours glitch-free sustained playback. |
androidOutputProfile Optional | 'media' | 'voiceCommunication' | 'media' | How Android classifies the context's output stream, which decides its volume stream, routing and audio processing. 'media' plays as music. 'voiceCommunication' marks it as speech in a call, so Android applies its call routing and echo cancellation; use it for interactive voice calls. |
Errors
| Error type | Description |
|---|---|
NotSupportedError | sampleRate is outside the supported range [3000, 768000]. |
Properties
| Name | Type | Description | |
|---|---|---|---|
baseLatency | number | Processing latency in seconds incurred by the AudioContext passing audio from the AudioDestinationNode to the audio subsystem. Does not include hardware output latency or audio graph processing time. Equals the render callback duration (callbackFrames / sampleRate). Returns 0 when the context is not running. | Read only |
outputLatency | number | Estimated output latency in seconds — the interval between when the audio system is given a buffer and when the first sample is played by the output device. Can change when the audio route changes; re-query before sync-sensitive work. Returns 0 when the context is not running. On iOS backed by AVAudioSession.outputLatency; on Android sampled via Oboe timestamps. | Read only |
Inherits all properties from BaseAudioContext.
Methods
Inherits all methods from BaseAudioContext.
createMediaElementSource
Creates MediaElementAudioSourceNode, routing media playback into the audio graph.
| Parameter | Type | Description |
|---|---|---|
mediaElement | HTMLMediaElement (web) | AudioTagHandle (native) | Media element to route into the graph. On native, wait for onLoad on <Audio> before calling. |
Returns MediaElementAudioSourceNode.
close
Closes the audio context, releasing any system audio resources that it uses.
Returns Promise<undefined>.
suspend
Suspends time progression in the audio context. It is useful when your application will not use audio for a while.
Returns Promise<undefined>.
resume
Resumes a previously suspended audio context.
Returns Promise<undefined>.
Events
Inherits onstatechange from BaseAudioContext; close, suspend and resume each fire it once their returned promise has resolved.
onerror
Sets (or removes, when null is assigned) a callback fired when the live output stream fails natively and cannot keep rendering — for example after the audio device disconnects or the OS audio service dies while the context is running.
Typical recovery is to call resume from the handler (or recreate the context). A short delay before resume gives the OS audio server time to recover from some errors, e.g. hardware errors, and prevents rapid retry loops.
const audioContext = new AudioContext();
audioContext.onerror = () => {
console.error('Audio output failed');
setTimeout(() => {
void audioContext.resume();
}, 2000);
};
Remarks
Asynchronous methods
suspend, resume and close return promises, but a context runs them one at a time, in the order they were called. A later call never overtakes an earlier one, so audioContext.suspend(); await audioContext.resume(); leaves the context running. Await a call only when you need to observe the state it leaves behind. AudioRecorder orders its lifecycle promises the same way.