BaseAudioContext: createBuffer() メソッド

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.

createBuffer()BaseAudioContext インターフェイスのメソッドで、新しい空の AudioBuffer オブジェクトを生成するために使用されます。このオブジェクトにデータを代入し、AudioBufferSourceNode を介して再生することができます。

音声バッファーの詳細については、 AudioBuffer のリファレンスページを参照してください。

メモ: 以前は createBuffer() が圧縮されたデータを受け取り、デコードされたサンプルを返すことができましたが、デコードがすべてメインスレッドで行われるため createBuffer() が他のコードの実行をブロックするので、この機能は仕様書から削除されました。非同期メソッド decodeAudioData() は同じことをします。 MP3 ファイルのような圧縮された音声を受け取り、AudioBuffer を直接返します。そして AudioBufferSourceNode で再生することができるのです。 MP3 を再生するような単純な用途では、 decodeAudioData() を使用する必要があります。

構文

js
createBuffer(numOfChannels, length, sampleRate)

引数

メモ: 音声バッファーの仕組みと、これらの引数の意味についての詳しい説明は、基本概念ガイドの音声バッファー:フレーム、サンプル、チャンネルに書かれています。

numOfChannels

整数で、このバッファーが持つべきチャンネル数を表します。既定値は 1 で、すべてのユーザーエージェントは少なくとも 32 チャンネルに対応しなければなりません。

length

整数で、バッファーのサイズをサンプルフレーム単位で表します(各サンプルフレームは、バイト単位のサンプルのサイズに numOfChannels を掛けたものとなります)。特定の秒数の音声に使用する length を決定するには、 numSeconds * sampleRate を使用します。

sampleRate

線形音声データのサンプリングレート(1 秒あたりのサンプルフレーム数)です。すべてのブラウザーは、少なくとも 8,000Hz から 96,000Hz の範囲のサンプリングレートに対応する必要があります。

返値

指定されたオプションに基づいて構成された AudioBuffer です。

例外

NotSupportedError DOMException

1 つ以上のオプションが負の値であるか、あるいは無効な値である場合に発生します(例えば numberOfChannels が対応しているよりも大きいか、 sampleRate が公称範囲外である場合など)。

RangeError

バッファーを割り当てるのに十分なメモリーがない場合に発生します。

まず、引数の使い方を説明するために、簡単な例をいくつか挙げます。

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

この呼び出しを使用すると、ステレオバッファー(2 チャンネル)が得られ、 AudioContext が 44100Hz (とても一般的で、ほとんどの通常のサウンドカードはこのレートで動作します)で動作しているいる状態で再生すると、 0.5 秒間(22050 フレーム / 44100Hz = 0.5 秒)になります。

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

この呼び出しを使用した場合、モノラルバッファー(1 チャネル)が得られ、 AudioContext が 44100Hz で動作している状態で再生すると、自動的に*リサンプル*されて 44100Hz となり(すなわち 44100 フレームになる)、 1.0 秒間(44100 フレーム / 44100Hz = 1 秒)になります。

メモ: 音声のリサンプリングは、画像のリサイズにとても似ています。 16 x 16 の画像を持っていて、それを 32 x 32 の領域いっぱいにしたい場合、それをリサイズ(リサンプリング)します。結果は、(リサイズのアルゴリズムによっては、ぼやけたりエッジが立ったりして)品質が落ちますが、うまくいき、リサイズした画像はよりスペースが小さくなります。リサンプルされた音声も全く同じで、スペースは節約できますが、実際には高い周波数のコンテンツ(高音)を適切に再生することはできません。

次は少し複雑な createBuffer() の例を見てみましょう。 3 秒間のバッファーを生成し、ホワイトノイズを書き込み、 AudioBufferSourceNode で再生します。コメントでは、何が起こっているのかを明確に説明しています。 コードをライブで実行したり、ソースを表示したりすることができます。

js
const audioCtx = new (window.AudioContext || window.webkitAudioContext)();

// AudioContext のサンプリングレートで空の 3 秒のステレオバッファーを作成する
const myArrayBuffer = audioCtx.createBuffer(
  2,
  audioCtx.sampleRate * 3,
  audioCtx.sampleRate,
);

// バッファーにホワイトノイズを書き込む
// 単なる -1.0 から 1.0 の間の乱数の値
for (let channel = 0; channel < myArrayBuffer.numberOfChannels; channel++) {
  // データを格納した実際の ArrayBuffer が得られる.
  const nowBuffering = myArrayBuffer.getChannelData(channel);
  for (let i = 0; i < myArrayBuffer.length; i++) {
    // Math.random() は [0; 1.0] である
    // 音声は [-1.0; 1.0] である必要がある
    nowBuffering[i] = Math.random() * 2 - 1;
  }
}

// AudioBufferSourceNode を得る
// これは AudioBuffer を再生するときに使う AudioNode である
const source = audioCtx.createBufferSource();
// AudioBufferSourceNode にバッファーを設定する
source.buffer = myArrayBuffer;
// AudioBufferSourceNode を出力先に接続すると
// 音声が聞こえるようになる
source.connect(audioCtx.destination);
// 音源の再生を始める
source.start();

仕様書

Specification
Web Audio API
# dom-baseaudiocontext-createbuffer

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
createBuffer

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

関連情報