BaseAudioContext: decodeAudioData() method
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.
The decodeAudioData() method of the BaseAudioContext
Interface is used to asynchronously decode audio file data contained in an
ArrayBuffer that is loaded from fetch(),
XMLHttpRequest, or FileReader. The decoded
AudioBuffer is resampled to the AudioContext's sampling
rate, then passed to a callback or promise.
This is the preferred method of creating an audio source for Web Audio API from an audio track. This method only works on complete file data, not fragments of audio file data.
This function implements two alternative ways to asynchronously return the audio data or error messages: it returns a Promise that fulfills with the audio data, and also accepts callback arguments to handle success or failure. The primary method of interfacing with this function is via its Promise return value, and the callback parameters are provided for legacy reasons.
Syntax
// Promise-based syntax returns a Promise:
decodeAudioData(arrayBuffer)
// Callback syntax has no return value:
decodeAudioData(arrayBuffer, successCallback)
decodeAudioData(arrayBuffer, successCallback, errorCallback)
Parameters
arrayBuffer-
An ArrayBuffer containing the audio data to be decoded, usually grabbed from
fetch(),XMLHttpRequestorFileReader. successCallbackOptional-
A callback function to be invoked when the decoding successfully finishes. The single argument to this callback is an
AudioBufferrepresenting the decodedData (the decoded PCM audio data). Usually you'll want to put the decoded data into anAudioBufferSourceNode, from which it can be played and manipulated how you want. errorCallbackOptional-
An optional error callback, to be invoked if an error occurs when the audio data is being decoded.
Return value
A Promise object that fulfills with the decodedData. If you are using the
XHR syntax you will ignore this return value and use a callback function instead.
Examples
In this section we will first cover the promise-based syntax and then the callback syntax.
Promise-based syntax
In this example loadAudio() uses fetch() to retrieve an audio file and decodes it into an AudioBuffer. It then caches the audioBuffer in the global buffer variable for later playback.
Note: You can run the full example live, or view the source.
let audioCtx;
let buffer;
let source;
async function loadAudio() {
try {
// Load an audio file
const response = await fetch("viper.mp3");
// Decode it
buffer = await audioCtx.decodeAudioData(await response.arrayBuffer());
} catch (err) {
console.error(`Unable to fetch the audio file. Error: ${err.message}`);
}
}
Callback syntax
In this example loadAudio() uses fetch() to retrieve an audio
file and decodes it into an AudioBuffer using the callback-based version of decodeAudioData(). In the callback, it plays the decoded buffer.
Note: You can run the full example live, or view the source.
let audioCtx;
let source;
function playBuffer(buffer) {
source = audioCtx.createBufferSource();
source.buffer = buffer;
source.connect(audioCtx.destination);
source.loop = true;
source.start();
}
async function loadAudio() {
try {
// Load an audio file
const response = await fetch("viper.mp3");
// Decode it
audioCtx.decodeAudioData(await response.arrayBuffer(), playBuffer);
} catch (err) {
console.error(`Unable to fetch the audio file. Error: ${err.message}`);
}
}
Specifications
| Specification |
|---|
| Web Audio API # dom-baseaudiocontext-decodeaudiodata |
Browser compatibility
| desktop | mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
decodeAudioData
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns a
Promise
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support