AudioWorkletGlobalScope

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.

ウェブオーディオ API の AudioWorkletGlobalScope インターフェイスは、独自の AudioWorkletProcessor の派生クラスを定義するユーザーコードのグローバル実行コンテキストを表します。

それぞれの BaseAudioContext は audioWorklet プロパティに 1 個の AudioWorklet を持ち、これがコードを 1 個の AudioWorkletGlobalScope で実行します。

グローバル実行コンテキストは現在の BaseAudioContext で共通なので、AudioWorkletProcessor の派生クラスを定義するだけでなく、他の変数を定義するなど、ワークレットでできることはなんでもできます。

WorkletGlobalScope AudioWorkletGlobalScope

インスタンスプロパティ

このインターフェイスは、親インターフェイスの WorkletGlobalScope で定義されたプロパティも継承します。

currentFrame 読取専用

処理されている音声ブロックの現在のサンプルフレームを表す、単調増加の整数を返します。この値は、各音声ブロックを処理するごとに 128 (render quantum のサイズ) 増えます。

currentTime 読取専用

処理中の音声ブロックのコンテキスト時刻を表す単調増加の double 値を返します。ワークレットが属している BaseAudioContext の currentTime プロパティと同じ値です。

sampleRate 読取専用

属している BaseAudioContext のサンプルレートを表す float 値を返します。

インスタンスメソッド

このインターフェイスは、親インターフェイスの WorkletGlobalScope からもメソッドを継承します。

registerProcessor()

AudioWorkletProcessor インターフェイスの派生クラスを登録します。これにより、登録したクラスが登録した名前を指定することで AudioWorkletNode の生成に使用できるようになります。

例

この例では、独自の AudioWorkletProcessor のコンストラクターで、すべてのグローバルプロパティをコンソールに出力します。

まず、処理器を定義して登録する必要があります。これは別のファイルで行うことに注意してください。

js
// test-processor.js で定義された AudioWorkletProcessor
class TestProcessor extends AudioWorkletProcessor {
  constructor() {
    super();

    // 生成時のサンプルフレームと時刻を記録する。
    // これらの値には AudioWorkletGlobalScope からアクセスできる。
    console.log(currentFrame);
    console.log(currentTime);
  }

  // process メソッドは必須である。
  // (最初から入っている) 無音を出力する。
  process(inputs, outputs, parameters) {
    return true;
  }
}

// サンプルレートを記録する。
// これは BaseAudioContext の読み取り専用プロパティであり、
// 生成時にのみ設定されるので、変化しない。
console.log(sampleRate);

// 任意の変数を宣言し、処理器で利用できる。
// たとえば、波形テーブルが入った ArrayBuffer を宣言できる。
const usefulVariable = 42;
console.log(usefulVariable);

registerProcessor("test-processor", TestProcessor);

次に、メインスクリプトファイルで処理器をロードし、処理器の名前を渡して AudioWorkletNode のインスタンスを生成し、生成したノードを音声グラフに接続します。コンソールに console.log() の呼び出しによる出力が出るはずです。

js
const audioContext = new AudioContext();
await audioContext.audioWorklet.addModule("test-processor.js");
const testNode = new AudioWorkletNode(audioContext, "test-processor");
testNode.connect(audioContext.destination);

仕様書

Specification
Web Audio API
# AudioWorkletGlobalScope

ブラウザーの互換性

BCD tables only load in the browser

関連情報