BaseAudioContext.createBuffer

The createBuffer() method of the BaseAudioContext Interface is used to create a new, empty AudioBuffer object, which can then be populated by data, and played via an AudioBufferSourceNode

For more details about audio buffers, check out the AudioBuffer reference page.

Syntax

var buffer = baseAudioContext.createBuffer(numOfchannels, length, sampleRate);

Parameters

numOfChannels

An integer representing the number of channels this buffer should have. The default value is 1, and all user agents must support at least 32 channels.

length

An integer representing the size of the buffer in sample-frames (where each sample-frame is the size of a sample in bytes multiplied by numOfChannels). To determine the length to use for a specific number of seconds of audio, use numSeconds * (sampleRate * numberOfChannels).

sampleRate

The sample rate of the linear audio data in sample-frames per second. All browsers must support sample rates in at least the range 8,000 Hz to 96,000 Hz.

Returns

An AudioBuffer configured based on the specified options.

Exceptions

NotSupportedError

One or more of the options are negative or otherwise has an invalid value (such as numberOfChannels being higher than supported, or a sampleRate outside the nominal range).

RangeError

There isn't enough memory available to allocate the buffer.

Examples

First, a couple of simple trivial examples, to help explain how the parameters are used:

var audioCtx = new AudioContext();
var buffer = audioCtx.createBuffer(2, 22050, 44100);

If you use this call, you will get a stereo buffer (two channels), that, when played back on an AudioContext running at 44100Hz (very common, most normal sound cards run at this rate), will last for 0.5 seconds: 22050 frames / 44100Hz = 0.5 seconds.

var audioCtx = new AudioContext();
var buffer = audioCtx.createBuffer(1, 22050, 22050);

If you use this call, you will get a mono buffer (one channel), that, when played back on an AudioContext running at 44100Hz, will be automatically *resampled* to 44100Hz (and therefore yield 44100 frames), and last for 1.0 second: 44100 frames / 44100Hz = 1 second.

Now let's look at a more complex createBuffer() example, in which we create a two second buffer, fill it with white noise, and then play it via an AudioBufferSourceNode. The comment should clearly explain what is going on. You can also run the code live, or view the source.

var audioCtx = new (window.AudioContext || window.webkitAudioContext)();

// Create an empty three-second stereo buffer at the sample rate of the AudioContext
var myArrayBuffer = audioCtx.createBuffer(2, audioCtx.sampleRate * 3, audioCtx.sampleRate);

// Fill the buffer with white noise;
// just random values between -1.0 and 1.0
for (var channel = 0; channel < myArrayBuffer.numberOfChannels; channel++) {
  // This gives us the actual ArrayBuffer that contains the data
  var nowBuffering = myArrayBuffer.getChannelData(channel);
  for (var i = 0; i < myArrayBuffer.length; i++) {
    // Math.random() is in [0; 1.0]
    // audio needs to be in [-1.0; 1.0]
    nowBuffering[i] = Math.random() * 2 - 1;
  }
}

// Get an AudioBufferSourceNode.
// This is the AudioNode to use when we want to play an AudioBuffer
var source = audioCtx.createBufferSource();
// set the buffer in the AudioBufferSourceNode
source.buffer = myArrayBuffer;
// connect the AudioBufferSourceNode to the
// destination so we can hear the sound
source.connect(audioCtx.destination);
// start the source playing
source.start();

Specifications

Browser compatibilityUpdate compatibility data on GitHub

See also

• Using the Web Audio API