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

ブラウザーの互換性

BCD tables only load in the browser

関連情報