Web Audio API ( 日本語訳 )

W3C Candidate Recommendation, 11 June 2020

この文書は、W3Cの文書 "Web Audio API, W3C Candidate Recommendation 11 June 2020" の日本語訳です。

この翻訳は既に新しい版に置き換えられています。

最新版はこちら:
「Web Audio API」( 日本語訳 )

旧版はこちら:
「Web Audio API」 W3C Candidate Recommendation 18 September 2018 ( 日本語訳 )
「Web Audio API」 W3C Working Draft 19 June 2018 ( 日本語訳 )
「Web Audio API」 W3C Working Draft 08 December 2015 ( 日本語訳 )
「Web Audio API」 W3C Working Draft 10 October 2013 ( 日本語訳 )

Web Audio API の正式な文書は英語版のみであり、日本語訳には翻訳に起因する誤りが含まれている場合があります。 英語版の正式な文書はW3Cのサイト : http://www.w3.org/TR/webaudio/にあります。

この翻訳の元となる文書は現在、勧告候補 (Candidate Recommendation, CR)です。今後も更新される可能性がある事に注意してください。

日本語訳GitHub : https://github.com/g200kg/web-audio-api-ja/
日本語訳公開URL : https://g200kg.github.io/web-audio-api-ja/

Tatsuya Shinyagaito @ g200kg
誤りその他があれば GitHub 経由などで連絡をお願いいたします。
https://www.g200kg.com/

2020年6月24日


Web Audio API

W3C Candidate Recommendation,

このバージョン:
https://www.w3.org/TR/2020/CR-webaudio-20200611/
最新の公開バージョン:
https://www.w3.org/TR/webaudio/
エディターズドラフト:
https://webaudio.github.io/web-audio-api/
以前のバージョン:
フィードバック:
public-audio@w3.org with subject line “[webaudio] … message topic …” (archives)
テストスイート:
https://github.com/web-platform-tests/wpt/tree/master/webaudio
イシュートラッキング:
GitHub
編集者:
(Mozilla (https://www.mozilla.org/))
(Google (https://www.google.com/))
以前の編集者:
Raymond Toy (until Oct 2018)
Chris Wilson (Until Jan 2016)
Chris Rogers (Until Aug 2013)

要約

この仕様は Web アプリケーションにおけるオーディオの処理および合成に関する高レベルの JavaScript API について記述します。 その基本的な枠組みとなっているのはオーディオのルーティンググラフであり、多数の AudioNode オブジェクトが互いに接続される事で最終的なオーディオ出力が定義されます。 実際の処理は基本的に下層にある実装 ( 典型的には最適化されたアセンブリ言語 / C / C++ コード ) で行われますが、直接的なスクリプトによる処理と合成 もサポートされています。

序文 セクションではこの仕様の背後にある動機についても取り上げます。

この API は他の API や Web プラットフォームの要素、特に : ( responseTyperesponse 属性を使った ) XMLHttpRequest[XHR] と共に使われるように設計されています。 ゲームやインタラクティブなアプリケーションでは、canvas 2D [2dcontext] および WebGL [WEBGL] 3D グラフィックス API と共に使われる事が予想されます。

この文書の位置付け

このセクションは、この文書の公開時における状況を記述したものです。他の文書がこの文書に取って代わるかもしれません。現在の W3C の刊行物およびこの技術レポートの最新改訂版のリストは、http://www.w3.org/TR/ にある W3C 技術レポートインデックス から見つけることができます。

この文書は Web Audio ワーキンググループ によって、勧告候補として作成されました。この文書は W3C 勧告となる事を目指しています。この文書は、広範囲のレビューの機会を得るために、少なくともまでは、候補勧告のままになります。

このドキュメントに関する意見があれば、仕様のリポジトリにイシューを登録するか、public-audio@w3.org ( subscribearchives ) に送ってください。

勧告候補としての公開は W3C メンバーによる承認を意味するものではありません。これは草案文書であり、いつでも他の文書によって改訂、置き換えあるいは廃止される可能性があります。この文書を作業中のもの以外として引用する事は不適切です。

暫定のインプリメンテーション報告があります。

この文書は W3C Patent Policy の基に運用されるグループによって作成されました。W3C はグループの成果物から作成された 特許開示リスト を管理しています; また、このページは特許開示の方法についても提示しています。特許について実際の知識を持ち、それが 基本的な請求事項 を含むと考える者は、 W3C Patent Policy 6節 に従って情報を開示しなくてはなりません。

この文書は 2019年3月1日 W3C Process Document によって管理されます。

前回のドラフト以降の変更については、「変更履歴」セクションを参照してください。

序文

これまでの Web 上のオーディオはかなり未発達なもので、ごく最近まで Flash や QuickTime のようなプラグインを通して配信しなくてはなりませんでした。HTML5 での audio 要素の導入は、基本的なストリーミング・オーディオ再生を可能にする重要なものです。しかし、より複雑なオーディオアプリケーションを扱うには、それだけではまだ充分に強力ではありません。洗練された Web ベースのゲームやインタラクティブ・アプリケーションのためには別の解決策が必要とされます。この仕様では、近年のデスクトップ・オーディオ制作アプリケーションに見られるミキシング、プロセシング、フィルタリング処理に加え、近年のゲームオーディオエンジンに見られるような機能も持たせる事を目標とします。

この API はさまざまな使用例 [webaudio-usecases] を考慮して設計されています。理想的にはすべての使用例が、JavaScript から制御される最適化された C++ エンジンを使って無理なく実装でき、ブラウザーで動作するようにサポートされなくてはなりません。とは言っても、近年のデスクトップ・オーディオソフトウェアは極めて高度な機能を持ち、それらの一部はこのシステムを使ったとしても構築する事が困難か不可能と考えられます。Apple 社の Logic Audio がそのようなアプリケーションの 1 つであり、外部 MIDI コントローラー、任意のプラグイン・オーディオエフェクトやシンセサイザー、高度に最適化されたオーディオファイルのディスクへの読み込み/書き出し、密に統合されたタイムストレッチなどなどをサポートしています。それでもなお、ここで提案するシステムは、音楽に関するものを含めて、かなり複雑なゲームやインタラクティブ・アプリケーションの広い範囲を充分にサポートする事が可能です。またそれは、WebGL によってもたらされる、より高度なグラフィックスの機能をよく引き立たせる事が可能です。このAPIはより高度な機能を後から追加できるように設計されています。

機能

この API は、これらの基本機能をサポートします:

モジュラールーティング

モジュラールーティングによって異なる AudioNode オブジェクト同士を任意に接続できます。それぞれのノードは入力および出力を持っています。 ソースノードは入力は持たず、ひとつの出力を持ちます。 デスティネーションノードはひとつの入力を持ち、出力は持っていません。フィルターなどの他のノードはソースとデスティネーションの間に配置することができます。2 つのオブジェクトが互いに接続している場合、低レベルのストリーム形式の詳細について開発者が煩わされる事なく、適正な処理が行われます。 例えばもしモノラルの音声ストリームがステレオの入力に接続されていても、左右のチャンネルに 適正 にミックスされます。

最も単純な例は、ひとつの音声ソースを出力に直接接続したものです。すべての接続は単一の AudioDestinationNode を持つ AudioContext 内部で行われます:

modular routing
モジュラールーティングの単純な例

この単純なルーティングを図示します。この例では単一の音を再生しています:

const context = new AudioContext();
 
 function playSound() {
   const source = context.createBufferSource();
   source.buffer = dogBarkingBuffer;
   source.connect(context.destination);
   source.start(0);
 }
 

これはもっと複雑な例で、3 つのソースとコンボリューションリバーブが最終出力段にあるダイナミックコンプレッサーを介して送られます:

modular routing2
モジュラールーティングのより複雑な例
let context;let compressor;let reverb;let source1, source2, source3;let lowpassFilter;let waveShaper;let panner;let dry1, dry2, dry3;let wet1, wet2, wet3;let masterDry;let masterWet;function setupRoutingGraph () {  context = new AudioContext();  // Create the effects nodes.  lowpassFilter = context.createBiquadFilter();  waveShaper = context.createWaveShaper();  panner = context.createPanner();  compressor = context.createDynamicsCompressor();  reverb = context.createConvolver();  // Create master wet and dry.  masterDry = context.createGain();  masterWet = context.createGain();  // Connect final compressor to final destination.  compressor.connect(context.destination);  // Connect master dry and wet to compressor.  masterDry.connect(compressor);  masterWet.connect(compressor);  // Connect reverb to master wet.  reverb.connect(masterWet);  // Create a few sources.  source1 = context.createBufferSource();  source2 = context.createBufferSource();  source3 = context.createOscillator();  source1.buffer = manTalkingBuffer;  source2.buffer = footstepsBuffer;  source3.frequency.value = 440;  // Connect source1  dry1 = context.createGain();  wet1 = context.createGain();  source1.connect(lowpassFilter);  lowpassFilter.connect(dry1);  lowpassFilter.connect(wet1);  dry1.connect(masterDry);  wet1.connect(reverb);  // Connect source2  dry2 = context.createGain();  wet2 = context.createGain();  source2.connect(waveShaper);  waveShaper.connect(dry2);  waveShaper.connect(wet2);  dry2.connect(masterDry);  wet2.connect(reverb);  // Connect source3  dry3 = context.createGain();  wet3 = context.createGain();  source3.connect(panner);  panner.connect(dry3);  panner.connect(wet3);  dry3.connect(masterDry);  wet3.connect(reverb);  // Start the sources now.  source1.start(0);  source2.start(0);  source3.start(0);}

モジュラールーティングはまた AudioNode の出力を 別の AudioNode の動きを制御する AudioParam パラメーターに接続する事もできます。この場合は、ノードからの出力は 入力信号ではなくモジュレーション信号として働きます。

modular routing3
モジュラールーティングによってオシレーターの出力で別のオシレーターの周波数を変調する図
function setupRoutingGraph() {  const context = new AudioContext();  // Create the low frequency oscillator that supplies the modulation signal  const lfo = context.createOscillator();  lfo.frequency.value = 1.0;  // Create the high frequency oscillator to be modulated  const hfo = context.createOscillator();  hfo.frequency.value = 440.0;  // Create a gain node whose gain determines the amplitude of the modulation signal  const modulationGain = context.createGain();  modulationGain.gain.value = 50;  // Configure the graph and start the oscillators  lfo.connect(modulationGain);  modulationGain.connect(hfo.detune);  hfo.connect(context.destination);  hfo.start(0);  lfo.start(0);}

API の概要

定義されているインターフェースは次のとおりです:

また非推奨ですがまだ削除されておらず、置き換えの実装が予定されているいくつかの Web Audio API があります。

1. オーディオ API

1.1. BaseAudioContext インターフェース

このインターフェースは AudioNode オブジェクトのセットとそれらの接続を表します。それによって AudioDestinationNode に任意の信号をルーティングする事を可能にします。ノードはコンテキストから作成され、お互いに 接続 されます。

BaseAudioContext は直接的にはインスタンス化されず、代わりに AudioContext (リアルタイムレンダリングの場合)と OfflineAudioContext (オフラインレンダリングの場合)が拡張された具体的なインターフェースとなっています。

BaseAudioContext は、初期状態では空のプロミスの順序付きリストである [[pending promises]] という内部スロットによって作成されます。
enum AudioContextState {
   "suspended",
   "running",
   "closed"
 };
 
列挙値の説明
"suspended" このコンテキストは現在中断 ( コンテキストの時間は進まず、オーディオハードウェアはパワーダウン / 解放 ) してる可能性があります。
"running" オーディオは処理状態にあります。
"closed" このコンテキストは解放され、もうオーディオ処理に使用できません。すべてのシステムオーディオリソースは解放されました。
callback DecodeErrorCallback = void (DOMException error);
 
 callback DecodeSuccessCallback = void (AudioBuffer decodedData);
 
 [Exposed=Window]
 interface BaseAudioContext : EventTarget {
   readonly attribute AudioDestinationNode destination;
   readonly attribute float sampleRate;
   readonly attribute double currentTime;
   readonly attribute AudioListener listener;
   readonly attribute AudioContextState state;
   [SameObject, SecureContext]
   readonly attribute AudioWorklet audioWorklet;
   attribute EventHandler onstatechange;
 
   AnalyserNode createAnalyser ();
   BiquadFilterNode createBiquadFilter ();
   AudioBuffer createBuffer (unsigned long numberOfChannels,
                             unsigned long length,
                             float sampleRate);
   AudioBufferSourceNode createBufferSource ();
   ChannelMergerNode createChannelMerger (optional unsigned long numberOfInputs = 6);
   ChannelSplitterNode createChannelSplitter (
     optional unsigned long numberOfOutputs = 6);
   ConstantSourceNode createConstantSource ();
   ConvolverNode createConvolver ();
   DelayNode createDelay (optional double maxDelayTime = 1.0);
   DynamicsCompressorNode createDynamicsCompressor ();
   GainNode createGain ();
   IIRFilterNode createIIRFilter (sequence<double> feedforward,
                                  sequence<double> feedback);
   OscillatorNode createOscillator ();
   PannerNode createPanner ();
   PeriodicWave createPeriodicWave (sequence<float> real,
                                    sequence<float> imag,
                                    optional PeriodicWaveConstraints constraints = {});
   ScriptProcessorNode createScriptProcessor(
     optional unsigned long bufferSize = 0,
     optional unsigned long numberOfInputChannels = 2,
     optional unsigned long numberOfOutputChannels = 2);
   StereoPannerNode createStereoPanner ();
   WaveShaperNode createWaveShaper ();
 
   Promise<AudioBuffer> decodeAudioData (
     ArrayBuffer audioData,
     optional DecodeSuccessCallback? successCallback,
     optional DecodeErrorCallback? errorCallback);
 };
 

1.1.1. 属性

audioWorklet, AudioWorklet 型, readonly

[worklets-1]AudioWorklet のアルゴリズムにより定義された AudioWorkletProcessor クラスのスクリプトをインポート可能な Worklet オブジェクトへのアクセスを行います。

currentTime, double 型, readonly

コンテキストのレンダリンググラフで最後に処理されたオーディオブロックの最後のサンプルフレームの次のサンプルの秒で表した時刻です。もしコンテキストのレンダリンググラフがまだオーディオブロックを処理していない場合 currentTime は 0 になります。

currentTime の時間軸で 0 はグラフで処理される最初のブロックの最初のサンプルフレームに対応します。このシステムの経過時間は BaseAudioContext が生成するオーディオストリームの経過時間に対応し、それはシステム内の他の時計には同期しないかも知れません。( OfflineAudioContext では、ストリームはどのデバイスでも能動的に再生されないため、実時間とはまったく違う進み方になります )

Web Audio API のすべてのスケジュールされた時刻は currentTime に対する相対値になります。

BaseAudioContext が "running" 状態にあるとき、この属性の値は単調増加し、レンダリングスレッドにより 1 レンダリング量子 に対応する均一な増分で更新されます。そのため動作中のコンテキストでは、currentTime はシステムがオーディオブロックを処理するに従って徐々に増加し、常に次に処理されるオーディオブロックの先頭の時刻を表します。それはまた現在の状態に対する変更が効力を持つ最も早い時刻でもあります。

currentTime は制御スレッドが戻るまでに アトミック に読み取られなくてはなりません ( MUST )。

destination, AudioDestinationNode 型, readonly

AudioDestinationNode は単一の入力を持ち、すべてのオーディオの最終的な出口を表しています。通常これは実際のオーディオハードウェアを表します。動作中のすべての AudioNode は直接または間接的にこの destination に接続されます。

listener, AudioListener 型, readonly

AudioListener は 3D 空間音響 で使用されます。

onstatechange, EventHandler

BaseAudioContext に AudioContext の状態が変化したとき ( 例えば、対応する Promise がリゾルブされたときなど ) にディスパッチされるイベントの EventHandler を設定するために使用されるプロパティです。 AudioContext の状態を直接問い合わせる事ができる Event 型のイベントがイベントハンドラーに発行されます。 新たに作成された AudioContextは 常に suspended 状態から開始し、状態の変化イベントは異なる状態への遷移の度に発行されます。このイベントは oncomplete イベントが発行される前に発行されます。

sampleRate, float 型, readonly

BaseAudioContext が扱うオーディオのサンプルレート ( 1 秒あたりのサンプルフレーム数 ) です。コンテキスト内のすべての AudioNode はこのレートで動作する事を想定しています。これを想定するため、サンプレートコンバータや " 可変速 " 処理はリアルタイム処理内ではサポートされません。 ナイキスト周波数 はこのサンプルレートの半分の値となります。

state, AudioContextState 型, readonly

AudioContext の現在の状態を表します。その値は制御スレッドの状態と同じです。

1.1.2. メソッド

createAnalyser()

AnalyserNodeファクトリーメソッド です。

パラメーターなし
戻り値: AnalyserNode
createBiquadFilter()

いくつかの一般的なフィルタータイプに設定可能な 2 次フィルターを表す BiquadFilterNodeファクトリーメソッド です。

パラメーターなし
戻り値: BiquadFilterNode
createBuffer(numberOfChannels, length, sampleRate)

与えられたサイズの AudioBuffer を作成します。バッファ内のデータは 0 ( 無音 ) で初期化されます。もし、引数のどれかが負、0 または範囲外の場合、NotSupportedError 例外を発生します ( MUST )。

BaseAudioContext.createBuffer() メソッドの引数。
パラメーター Null可 省略可 説明
numberOfChannels unsigned long バッファが持つチャンネル数を指定します。実装は少なくとも 32 チャンネルをサポートしなくてはなりません ( MUST )。
length unsigned long バッファのサイズをサンプルフレーム数で指定します。これは少なくとも1でなくてはなりません ( MUST )。
sampleRate float バッファ内のリニア PCM オーディオデータのサンプルレートを秒あたりのサンプルフレーム数で表します。実装は少なくとも 8000 から 96000 の範囲をサポートしなくてはなりません ( MUST )。
戻り値: AudioBuffer
createBufferSource()

AudioBufferSourceNodeファクトリーメソッド です。

パラメーターなし
戻り値: AudioBufferSourceNode
createChannelMerger(numberOfInputs)

チャンネルマージャーを表す ChannelMergerNodeファクトリーメソッド です。numberOfInputs が 1 より小さいかサポートされる数より大きい場合は IndexSizeError 例外を発生します ( MUST )。

BaseAudioContext.createChannelMerger(numberOfInputs) メソッドの引数。
パラメーター Null可 省略可 説明
numberOfInputs unsigned long 入力の数を指定します。値は 32 までサポートされなくてはなりません ( MUST )。もし指定されない場合は 6 となります。
戻り値: ChannelMergerNode
createChannelSplitter(numberOfOutputs)

チャンネルスプリッターを表す ChannelSplitterNodeファクトリーメソッド です。numberOfOutputs が 1 より小さいかサポートされる数より大きい場合は、IndexSizeError 例外を発生します ( MUST )。

BaseAudioContext.createChannelSplitter(numberOfOutputs) メソッドの引数。
パラメーター Null可 省略可 説明
numberOfOutputs unsigned long 出力の数を指定します。値は 32 までサポートされなくてはなりません ( MUST )。もし指定されない場合は 6 となります。
戻り値: ChannelSplitterNode
createConstantSource()

ConstantSourceNodeファクトリーメソッド です。

パラメーターなし
戻り値: ConstantSourceNode
createConvolver()

ConvolverNodeファクトリーメソッド です。

パラメーターなし
戻り値: ConvolverNode
createDelay(maxDelayTime)

DelayNodeファクトリーメソッド です。初期化時のデフォルト遅延時間は 0 秒です。

BaseAudioContext.createDelay(maxDelayTime) メソッドの引数。
パラメーター Null可 省略可 説明
maxDelayTime double 遅延機能の遅延時間の最大値を秒で指定します。指定する場合は、その値は 0 よりも大きく 3 分よりも小さくなければなりません ( MUST )。そうでない場合 NotSupportedError 例外を発生します ( MUST )。 指定しない場合は 1 となります。
戻り値: DelayNode
createDynamicsCompressor()

DynamicsCompressorNodeファクトリーメソッド です。

パラメーターなし
戻り値: DynamicsCompressorNode
createGain()

GainNodeファクトリーメソッド です。

パラメーターなし
戻り値: GainNode
createIIRFilter(feedforward, feedback)
BaseAudioContext.createIIRFilter() メソッドの引数。
パラメーター Null可 省略可 説明
feedforward sequence<double> IIR フィルターの伝達関数のフィードフォワード ( 分子 ) の係数の配列です。この配列の最大の長さは 20 です。もしすべての値が 0 の場合、InvalidStateError 例外を発生します ( MUST )。 配列の長さが 0 または 20 より大きい場合は NotSupportedError 例外を発生します ( MUST )。
feedback sequence<double> IIR フィルターの伝達関数のフィードバック ( 分母 ) の係数の配列です。この配列の最大の長さは20です。もし配列の最初の要素が 0 の場合、InvalidStateError 例外を発生します ( MUST )。 もし配列の長さが 0 または 20 より大きい場合は NotSupportedError 例外を発生します ( MUST )。
戻り値: IIRFilterNode
createOscillator()

OscillatorNodeファクトリーメソッド です。

パラメーターなし
戻り値: OscillatorNode
createPanner()

PannerNodeファクトリーメソッド です。

パラメーターなし
戻り値: PannerNode
createPeriodicWave(real, imag, constraints)

PeriodicWave を作成する ファクトリーメソッド です。

このメソッドを呼び出したとき、以下の手順が実行されます:
  1. もし realimag が同じ長さでない場合、IndexSizeError が発生します ( MUST )。

  2. oPeriodicWaveOptions 型の新しいオブジェクトとします。

  3. このファクトリーメソッドに各々渡された real および imag パラメーターを、o の同じ名前の属性として設定します。

  4. odisableNormalization 属性を、ファクトリーメソッドに渡された constraints 属性の disableNormalization の値に設定します。

  5. このファクトリーメソッドが呼ばれた BaseAudioContext を最初の引数とし、o を渡して新しい PeriodicWave p を作成します。

  6. p を返します。

BaseAudioContext.createPeriodicWave() メソッドの引数。
パラメーター Null可 省略可 説明
real sequence<float> コサインパラメーターの数値列です。詳細の説明についてはコンストラクタの引数 real を参照してください。
imag sequence<float> サインパラメーターの数値列です。詳細の説明についてはコンストラクタの引数 imag を参照してください。
constraints PeriodicWaveConstraints 指定されていない場合は、波形は正規化されます。そうでない場合、波形は constraints に与えられた値に従って正規化されます。
戻り値: PeriodicWave
createScriptProcessor(bufferSize, numberOfInputChannels, numberOfOutputChannels)

ScriptProcessorNodeファクトリーメソッド です。このメソッドは廃止予定 ( DEPRECATED ) で、AudioWorkletNode で置き換えられます。 スクリプトによるオーディオデータ直接処理のための ScriptProcessorNode を作成します。 bufferSize または numberOfInputChannels または numberOfOutputChannels が範囲外の場合、 IndexSizeError 例外を発生します ( MUST )。

numberOfInputChannelsnumberOfOutputChannels の両方を 0 にはできません。この場合、IndexSizeError 例外を発生します ( MUST )。

BaseAudioContext.createScriptProcessor(bufferSize, numberOfInputChannels, numberOfOutputChannels) メソッドの引数。
パラメーター Null可 省略可 説明
bufferSize unsigned long bufferSize パラメーターはサンプルフレーム数でバッファのサイズを指定します。もしそれが渡されない場合、または値が 0 である場合、実装はノードのライフタイムを通して一定な、動作環境に最適な2の累乗のバッファサイズを選択します。それ以外の場合は明示的にバッファサイズを指定します。それは次の値のどれかでなければなりません: 256、512、1024、2048、4096、8192、16384 ( MUST )。この値は onaudioprocess イベントが発生する頻度とそれぞれの呼び出しでどれだけのサンプルフレームを処理する必要があるかを制御します。bufferSize が小さい値ならば レイテンシー は低く ( 良く ) なります。オーディオが途切れ、グリッジ が発生する事を避けるには大きな値が必要となります。レイテンシー とオーディオ品質の間のバランスを取るためには、プログラマーはこのバッファサイズを指定せず、実装に最適なバッファサイズを選択させる事が推奨されます。もしこのパラメーターの値が上に示した許された2の累乗の値でない場合、IndexSizeError 例外を発生します ( MUST )。
numberOfInputChannels unsigned long このパラメーターはこのノードの入力チャンネル数を指定します。デフォルトの値は 2 です。32 チャンネルまでの値がサポートされなくてはなりません。チャンネル数がサポート外の場合、NotSupportedError 例外を発生します。
numberOfOutputChannels unsigned long このパラメーターはこのノードの出力チャンネル数を指定します。デフォルトの値は 2 です。32 チャンネルまでの値がサポートされなくてはなりません。チャンネル数がサポート外の場合、NotSupportedError 例外を発生します。
戻り値: ScriptProcessorNode
createStereoPanner()

StereoPannerNodeファクトリーメソッド です。

パラメーターなし
戻り値: StereoPannerNode
createWaveShaper()

非線形な歪み効果を表す WaveShaperNodeファクトリーメソッド です。

パラメーターなし
戻り値: WaveShaperNode
decodeAudioData(audioData, successCallback, errorCallback)

ArrayBuffer 内にあるオーディオファイルのデータを非同期にデコードします。ArrayBuffer は、例えば XMLHttpRequestresponseType"arraybuffer" を指定した場合の response 属性としてロードされます。オーディオファイルデータは audio 要素でサポートされるどのフォーマットでも構いません。decodeAudioData() に渡されるバッファは [mimesniff] で説明される手順で判定されるコンテントタイプを持ちます。

この関数の基本的なインターフェースの手段は戻り値の promise ではありますが、歴史的な理由からコールバックのパラメーターも提供されています。

decodeAudioData が呼ばれたとき、制御スレッド上では次の手順を実行します ( MUST ):
  1. promise を新しい promise とします。

  2. もし audioData に対する、IsDetachedBuffer ([ECMASCRIPT] で説明されています) が false の場合、次の手順を実行します:

    1. promise[[pending promises]] に追加します。

    2. audioData ArrayBuffer Detach します。この操作は [ECMASCRIPT] で説明されています。もしこの操作に失敗した場合はステップ 3 にジャンプします。

    3. 別のスレッドで実行されるデコード処理をキューにいれます。

  3. そうでなければ、次の手順を実行します:

    1. errorDataCloneError とします。

    2. promiseerror でリジェクトし、[[pending promises]]から削除します。

    3. errorCallbackerror で呼び出すタスクをキューに入れます。

  4. promise を返します。

制御スレッド でも レンダリングスレッド でもない、デコーディングスレッドと呼ばれる別のスレッドで実行されるデコード処理がキューに入れられるとき、次の手順が発生します ( MUST )。

注 : 複数回の decodeAudioData の呼び出しを処理するため、複数のデコーディングスレッドが並列して走る事もあります。

  1. can decode を初期状態が true のブーリアンフラグとします。

  2. MIME Sniffing §6.2 Matching an audio or video type pattern を用いて、audioData の MIME タイプの決定を試みます。もしオーディオまたはビデオのパターンマッチングアルゴリズムが undefined を返した場合 can decodefalse に設定します。

  3. もし can decodetrue の場合、エンコードされている audioDataリニア PCM にデコードを試みます。もし失敗した場合は can decodefalse に設定します。

  4. もし can decodefalse の場合制御スレッド

    のイベントループで次のステップを実行するためのタスクをキューに入れます:
    1. errorEncodingError という名前の DOMException とします。

      1. promiseerrorでリジェクトし、[[pending promises]]から削除します。

    2. もし errorCallback が存在している場合は errorCallbackerror で呼び出します。

  5. そうでなければ:

    1. デコードされたリニア PCM の結果を得て、AudioContext のサンプルレートがaudioDataのサンプルレートと異なっていたらリサンプルを行います。

    2. 制御スレッドのイベントループで次のステップを実行するためのタスクをキューに入れます:

      1. buffer を最終的な結果 ( 必要ならサンプルレート変換を行った後 ) を保持した AudioBuffer とします。

      2. promisebuffer を持ってリゾルブします。

      3. もしsuccessCallbackが存在していればsuccessCallbackbufferを持って呼び出します。

BaseAudioContext.decodeAudioData() メソッドの引数。
パラメーター Null可 省略可 説明
audioData ArrayBuffer 圧縮されたオーディオデータを含む ArrayBuffer です。
successCallback DecodeSuccessCallback? デコードが完了したときに呼び出されるコールバック関数です。コールバック関数の引数は 1 つでデコードされた PCM オーディオデータをあらわす AudioBuffer になります。
errorCallback DecodeErrorCallback? オーディオファイルをデコード中にエラーが起こった場合に呼び出されるコールバック関数です。
戻り値: Promise<AudioBuffer>

1.1.3. コールバック DecodeSuccessCallback() パラメーター

decodedData, AudioBuffer 型

デコードしたオーディオデータを保持する AudioBuffer。

1.1.4. コールバック DecodeErrorCallback() パラメーター

error, DOMException 型

デコード中に発生したエラー。

1.1.5. ライフタイム

AudioContext は一度作成された後、これ以上再生する音がなくなるまで、あるいはページを移動するまで再生を続けます。

1.1.6. 内部検査やシリアライゼーションの基本機能の欠如

Web Audio API は音源のスケジューリングに fire-and-forget アプローチを取っています。つまり、音源ノード は、AudioContext のライフタイムの間のひとつひとつの音に対応して作成され、明示的にグラフからの削除は行いません。これはシリアライゼーション API とは互換性がなく、そのためシリアライズ可能な固定的なノードのセットもありません。

さらに、内部検査のための API を持つためにはスクリプトの中身のガベージコレクションの監視が必要になります。

1.1.7. BaseAudioContext サブクラスに関連付けられるシステムリソース

サブクラス、AudioContextOfflineAudioContext はコストの高いオブジェクトと考えるべきです。これらのオブジェクトの作成には、高プライオリティのスレッドまたは低レイテンシーのシステムオーディオを含み、どちらも消費電力への影響があります。通常は、1 つのドキュメント内に 1 つ以上の AudioContext を作成する事は不必要です。

BaseAudioContext のサブクラスの作成または再開は、そのコンテキストがシステムリソースを取得する事を含みます。このためには AudioContext としてはシステムオーディオのストリームを作成する事も必要です。これらの動作はコンテキストが関連するオーディオグラフから出力の生成を開始する際に処理を戻します。

なお、ユーザーエージェントは実装で定められた最大数の AudioContext を持つ事ができ、それ以上の新しい AudioContext の作成は失敗して、throwing NotSupportedError 例外を発生します。

プログラマーは suspend および close を使う事で、スレッド、プロセスおよびオーディオストリームを含むシステムリソースの解放を行う事ができます。BaseAudioContext をサスペンドする事で、実装は一部のリソースを解放して後で resume を呼び出したときに再開できるようにします。 AudioContext のクローズによって、実装はすべてのリソースを解放し、再度使用したり再開したりはできなくなります。

注 : これは例えば、定期的なコールバックの呼び出しを待つ事やハードウェアが処理可能になるのを待つ事も含みます。

1.2. AudioContext インターフェース

このインターフェースは、その AudioDestinationNode がデバイスへのリアルタイム出力によって直接ユーザーに信号が届くオーディオグラフを表します。多くの場合、1 つのドキュメントにつき 1 つの AudioContext が使用されます。

enum AudioContextLatencyCategory {
     "balanced",
     "interactive",
     "playback"
 };
 
列挙値の説明
"balanced" オーディオ出力のレイテンシーと安定性/消費電力のバランスを取ります。
"interactive" オーディオ出力のレイテンシーをグリッジが発生しない最小値にする。これがデフォルトになります。
"playback" オーディオ出力のレイテンシーよりも再生の途切れを起こさない事を優先します。消費電力は最も低くなります。
[Exposed=Window]
 interface AudioContext : BaseAudioContext {
   constructor (optional AudioContextOptions contextOptions = {});
   readonly attribute double baseLatency;
   readonly attribute double outputLatency;
   AudioTimestamp getOutputTimestamp ();
   Promise<void> resume ();
   Promise<void> suspend ();
   Promise<void> close ();
   MediaElementAudioSourceNode createMediaElementSource (HTMLMediaElement mediaElement);
   MediaStreamAudioSourceNode createMediaStreamSource (MediaStream mediaStream);
   MediaStreamTrackAudioSourceNode createMediaStreamTrackSource (
     MediaStreamTrack mediaStreamTrack);
   MediaStreamAudioDestinationNode createMediaStreamDestination ();
 };
 

ユーザーエージェントがコンテキストの状態を "suspended"から "running"に移行できる場合、AudioContextスタート可能であると言います。 ユーザーエージェントは、AudioContext関連するグローバルオブジェクトスティッキーアクティベーションを持っている場合にのみ許可するために、この初期遷移を遅延させることができます。

AudioContext は内部にスロットを持っている :

[[suspended by user]]

コンテキストがユーザーのコードによって中断されているかどうかを表すブーリアンフラグ。 初期値は false です。

1.2.1. コンストラクター

AudioContext(contextOptions)

現在の設定オブジェクト対応するドキュメント完全にアクティブない場合は InvalidStateError を発生して、次の手順を中止します。

AudioContext を作成する際は、以下の手順を実行します:
  1. AudioContext 上の 制御スレッドの状態suspended に設定します。

  2. AudioContext 上のレンダリングスレッドの状態suspended に設定します。

  3. [[pending resume promises]]をこの AudioContext 上のスロットとし、初期状態を空の promise のリストとします。

  4. もし contextOptions が与えられていれば、オプションを適用します:

    1. この AudioContext の内部レイテンシーを latencyHint の項に書かれているように、contextOptions.latencyHint に従って設定します。

    2. もし contextOptions.sampleRate が指定されていれば、この AudioContextsampleRate をその値に設定します。 そうでなければ、デフォルト出力デバイスのサンプルレートを使用します。 もし選択されたサンプルレートが出力デバイスのサンプルレートと異なる場合、この AudioContext はオーディオ出力を出力デバイスのサンプルレートに合うようにリサンプリングしなくてはなりません ( MUST )。

      注 : もしリサンプリングが必要とされる場合、AudioContext のレイテンシーに大きな影響があるかも知れません。

  5. もし AudioContext が スタート可能ならば、処理を開始するための制御メッセージを送ります。

  6. この AudioContext オブジェクトを返します。

処理を開始するための 制御メッセージ を送るには次の手順を実行します:
  1. システムリソースの取得 を試みます。もし失敗した場合は以降の手順を中止します。

  2. AudioContextレンダリングスレッドの状態running に設定します。

  3. 制御スレッド のイベントループで以下の手順を実行するためのタスクをキューに入れます:

    1. AudioContextstate 属性を "running" に設定します。

    2. AudioContextstatechange という名前のシンプルイベントを発行するためのタスクをキューに入れます

注 : 残念ながら、AudioContext の作成の失敗についてプログラム上の通知をすることはできません。ユーザーエージェントは、デベロッパーツールコンソールのようなログメカニズムにアクセスできる場合、これを知らせるメッセージをログに記録することをお勧めします。

AudioContext.constructor(contextOptions) メソッドの引数。
パラメーター Null可 省略可 説明
contextOptions AudioContextOptions AudioContext をどのように作成するかをユーザーが指定するオプション。

1.2.2. 属性

baseLatency, double 型, readonly

これは AudioContextAudioDestinationNode からオーディオサブシステムにオーディオを渡す処理で発生するレイテンシーの秒数を表します。これには AudioDestinationNode の出力とオーディオハードウェアの間で発生するかも知れないその他の処理による追加のレイテンシーは含まれず、特にオーディオグラフ自体に発生するレイテンシーは含まれません。

例えばもし、オーディオコンテキストが 44.1 kHz で動作しており、AudioDestinationNode の実装が内部でダブルバッファリングによる レンダリング量子 の出力処理を行う場合、処理のレイテンシーは、約 \((2\cdot128)/44100 = 5.805 \mathrm{ ms}\) となります。

outputLatency, double 型, readonly

オーディオ出力処理のレイテンシーの秒数の見積もり。つまり、UA がホストシステムにバッファを再生を要求した時間から、バッファ内の最初のサンプルが実際にオーディオ出力デバイスで処理される時間までの間隔。この後者の時間は、スピーカーやヘッドフォンのような音の信号を発生するデバイスがサンプルの音を発生する時間を指します。

outputLatency 属性の値はプラットフォームと接続されているオーディオ出力デバイスに依存します。outputLatency 属性の値は接続されているオーディオ出力デバイスが同じである限り、コンテキストのライフタイムを通じて変化する事はありません。もしオーディオ出力デバイスが変化したならば、outputLatency 属性の値もそれに従ってアップデートされます。

1.2.3. メソッド

close()

AudioContext をクローズし、使用中の システムリソースを解放 します。これは、AudioContext が作成したすべてのオブジェクトを自動的に開放はしませんが、AudioContextcurrentTime の進行を止め、オーディオデータの処理を停止します。

close が呼ばれたとき、以下の手順が実行されます:
  1. promise を新しい Promise とします。

  2. もし AudioContext制御スレッドの状態 フラグが closed であった場合、promise を InvalidStateError でリジェクトし、これらの手順を中断して promise を返します。

  3. AudioContext制御スレッドの状態 フラグを closed に設定します。

  4. AudioContext をクローズするための制御メッセージをキューに入れます

  5. promise を返します。

AudioContext をクローズするための 制御メッセージ を実行する事は、レンダリングスレッド で、以下の手順を実行する事を意味します:
  1. システムリソースの解放 を試みます。

  2. レンダリングスレッドの状態suspended に設定します。

    これによりレンダリングは停止します。
  3. もしこの 制御メッセージ がドキュメントがアンロードされる事に対する反応として実行されているなら、このアルゴリズムを中止します。

    この場合、制御スレッドへの通知は必要ありません。
  4. 制御スレッド のイベントループで以下の手順を実行する タスクをキューに入れます :

    1. promise をリゾルブします。

    2. もし AudioContextstate 属性が既に "closed" でない場合:

      1. AudioContextstate 属性を "closed" に設定します。

      2. AudioContextstatechange という名前のシンプルイベントを発行するための タスクをキューに入れます

AudioContext がクローズされた場合、AudioContext に接続されているすべての MediaStreamHTMLMediaElement はその出力を無視されます。 つまり、これらはもうスピーカーなどの出力デバイスに出力されなくなります。より柔軟な挙動のためには、 HTMLMediaElement.captureStream() の使用を検討してください。

注 : AudioContext がクローズされるとき、実装はサスペンドの場合よりも積極的に多くのリソースを解放する事ができます。

パラメーターなし
戻り値: Promise<void>
createMediaElementSource(mediaElement)

指定された HTMLMediaElement から MediaElementAudioSourceNode を作成します。 このメソッドの呼び出しにより、HTMLMediaElement からのオーディオの再生は AudioContext の処理グラフに再ルーティングされるようになります。

AudioContext.createMediaElementSource() メソッドの引数。
パラメーター Null可 省略可 説明
mediaElement HTMLMediaElement 再ルーティングされるメディアエレメントです。
戻り値: MediaElementAudioSourceNode
createMediaStreamDestination()

MediaStreamAudioDestinationNode を作成します。

パラメーターなし
戻り値: MediaStreamAudioDestinationNode
createMediaStreamSource(mediaStream)

MediaStreamAudioSourceNode を作成します。

AudioContext.createMediaStreamSource() メソッドの引数。
パラメーター Null可 省略可 説明
mediaStream MediaStream 音源となるメディアストリームです。
戻り値: MediaStreamAudioSourceNode
createMediaStreamTrackSource(mediaStreamTrack)

MediaStreamTrackAudioSourceNode を作成します。

AudioContext.createMediaStreamTrackSource() メソッドの引数。
パラメーター Null可 省略可 説明
mediaStreamTrack MediaStreamTrack 音源となる MediaStreamTrack です。 その kind 属性は "audio" でなくてはならず、そうでない場合は、InvalidStateError 例外を発生します ( MUST )。
戻り値: MediaStreamTrackAudioSourceNode
getOutputTimestamp()

コンテキストのオーディオストリームについて、2 つの関連する位置情報を含む新しい AudioTimestamp インスタンスを返します: contextTime メンバーには、オーディオ出力デバイスによって現在レンダリングされているサンプルフレームの時間 ( つまり出力されているオーディオストリームの位置 ) が含まれます。これにはコンテキストの currentTime と同じ単位と起点を使用します。 そして performanceTime メンバーには、contextTime に格納された値に対応するサンプルフレームが performance.now() ( [hr-time-2] で説明されています ) と同じ単位および起点で、オーディオ出力デバイスによってレンダリングされる瞬間を推定する時間が含まれます 。

コンテキストのレンダリンググラフがまだオーディオブロックを処理していないときに getOutputTimestamp を呼び出すと、両方のメンバーが 0 である AudioTimestamp インスタンスを返します。

コンテキストのレンダリンググラフがオーディオブロックの処理を開始すると、その currentTime 属性の値は常に getOutputTimestamp メソッドの呼び出しで取得される contextTime 値より大きくなります。

getOutputTimestamp メソッドから返された値は、コンテキストの時刻のわずかに後になるパフォーマンスの時刻の見積もりを得るのに使用できます:
function outputPerformanceTime(contextTime) {
   const timestamp = context.getOutputTimestamp();
   const elapsedTime = contextTime - timestamp.contextTime;
   return timestamp.performanceTime + elapsedTime * 1000;
 }
 

上の例での見積もりの精度は、引数の値が現在の出力オーディオストリームの位置にどれほど近いかによって決まります: つまり与えられた contextTimetimestamp.contextTime に近いほど、得られた推定の精度は良くなります。

注 : コンテキストの currentTimegetOutputTimestamp メソッドの呼び出しから得られた contextTime の値の差は、currentTime が不均一な時間間隔で増加する可能性があるため、信頼できる出力レイテンシーの見積もりとみなす事はできず、代わりに outputLatency 属性を使用する必要があります。

パラメーターなし
戻り値: AudioTimestamp
resume()

AudioContextcurrentTime の進行が停止している場合、再開させます。

resume が呼ばれた時、以下のステップが実行されます :
  1. promiseを新しい Promise とします。

  2. もし AudioContext制御スレッドの状態closed であれば promise は InvalidStateError でリジェクトされ、これらのステップは中止して promise を返します。

  3. [[suspended by user]]false に設定します。

  4. もしこのコンテキストが スタート可能 でない場合 promise[[pending promises]][[pending resume promises]] に加え、これらのステップを中止して promise を返します。

  5. AudioContext制御スレッドの状態running に設定します。

  6. AudioContext を再開するための 制御メッセージをキューに入れます

  7. promise を返します。

AudioContext を再開するための 制御メッセージ を実行するとは、次のステップを レンダリングスレッド で実行する事を意味します:
  1. システムリソースの取得 を試みます。

  2. AudioContextレンダリングスレッドの状態running に設定します。

  3. オーディオグラフのレンダリング を開始します。

  4. 失敗した場合は 制御スレッド で以下を実行してこれらのステップを中止します :

    1. [[pending resume promises]] から全ての promise を順番にリジェクトして [[pending resume promises]] を空にします。

    2. さらに、これらの promise を [[pending promises]] から削除します。

  5. 制御スレッド のイベントループ上でこれらのステップを実行するためのタスクをキューに入れます :

    1. [[pending resume promises]] を空にします。さらに、これらの promise を [[pending promises]] から削除します。

    2. promise をリゾルブします。

    3. もし AudioContextstate 属性が既に "running" でない場合 :

      1. AudioContextstate 属性を "running" に設定します。

      2. AudioContextstatechange という名前のシンプルイベントを発行するためのタスクをキューに入れます。

パラメーターなし
戻り値: Promise<void>
suspend()

AudioContextcurrentTime の進行を中断し、デスティネーションで再生するために既に処理を終えた現在のコンテキストの処理ブロックを再生し、その後システムがオーディオハードウェアの占有を解放できるようにします。 これは一般的に、アプリケーションがしばらくの間 AudioContext を必要とせず、一時的に AudioContext に関連付けられた システムリソースを解放 したいことがアプリケーションに分かっているときに役に立ちます。この promise は、フレームバッファが空のとき ( ハードウェアに渡されたとき )、またはコンテキストがすでに suspended 状態のときは即座に ( 副作用なしで ) リゾルブされます。コンテキストがクローズされた場合、promise はリジェクトされます。

suspend が呼び出された場合、以下の手順を実行します:
  1. promise を新しい Promise とします。

  2. もし AudioContext制御スレッドの状態closed の場合、promise を InvalidStateError でリジェクトし、これらの手順を中止して promise を返します。

  3. promise[[pending promises]] に追加します。

  4. [[suspended by user]]true に設定します。

  5. AudioContext制御スレッドの状態suspended に設定します。

  6. AudioContext をサスペンドするための 制御メッセージをキューに入れます

  7. promise を返します。

AudioContext をサスペンドするための 制御メッセージ を実行する、とは レンダリングスレッド で、以下の手順を実行する事を意味します:
  1. システムリソースの解放 を試みます。

  2. AudioContextレンダリングスレッドの状態suspended に設定します。

  3. 制御スレッド のイベントループで以下の手順を実行する タスクをキューに入れます:

    1. promise をリゾルブします。

    2. もし AudioContextstate 属性が既に "suspended" でない場合:

      1. AudioContextstate 属性を "suspended" に設定します。

      2. AudioContextstatechange という名前のシンプルイベントを発行する タスクをキューに入れます

AudioContext がサスペンドされている間 MediaStream の出力は無視されます。つまり、メディアストリームのリアルタイム性によって、データは失われます。HTMLMediaElement も同様に、システムが再開されるまでその出力は無視されます。AudioWorkletNode および ScriptProcessorNode は、サスペンド中は処理ハンドラーの呼び出しが止まりますが、コンテキストがリジュームされると再開します。AnalyserNode では、ウィンドウ関数の目的そのものにより、データは連続ストリームとみなされます。つまり、resume()/suspend() によって AnalyserNode のデータストリームに無音は発生しません。特に、AudioContext がサスペンドされているときに AnalyserNode の関数を繰り返し呼び出した際は、同じデータが返されなければなりません ( MUST )。

パラメーターなし
戻り値: Promise<void>

1.2.4. AudioContextOptions

AudioContextOptions ディクショナリは AudioContext のユーザー指定のオプションを決めるために使用されます。

dictionary AudioContextOptions {
   (AudioContextLatencyCategory or double) latencyHint = "interactive";
   float sampleRate;
 };
 
1.2.4.1. ディクショナリー AudioContextOptions メンバー
latencyHint, (AudioContextLatencyCategory または double) 型, デフォルト値は "interactive"

オーディオ出力のレイテンシーと消費電力の間のトレードオフに影響を与える、再生のタイプを指示します。

latencyHint の値は、AudioContextLatencyCategory から選択する事が推奨されます。ただし、レイテンシーと消費電力をより細かくバランスを取るために、レイテンシーの秒数を double 型で指定することもできます。数値を適切に解釈するのはブラウザーの裁量に委ねられています。実際に使用されるレイテンシーは、AudioContext の baseLatency 属性によって与えられます。

sampleRate, float

作成される AudioContextsampleRate をこの値に設定します。サポートされている値は AudioBuffer のサンプルレートと同じです。指定されたサンプルレートがサポートされていない場合は NotSupportedError 例外を発生します ( MUST )。

もし sampleRate が指定されていない場合、この AudioContext の出力デバイスが推奨するサンプルレートが使用されます。

1.2.5. AudioTimestamp

dictionary AudioTimestamp {
   double contextTime;
   DOMHighResTimeStamp performanceTime;
 };
 
1.2.5.1. ディクショナリー AudioTimestamp メンバー
contextTime, double

BaseAudioContext の currentTime の時間軸内の時刻を表します。

performanceTime, DOMHighResTimeStamp

Performance インターフェースの実装における時間軸内の時刻を表します ( [hr-time-2] で説明されています )。

1.3. OfflineAudioContext インターフェース

OfflineAudioContext は、レンダリング/ミックスダウンのための特殊なタイプの BaseAudioContext で、( 潜在的には ) リアルタイムよりも高速に動作します。これはオーディオハードウェアに対してレンダリングせず、可能な限り高速にレンダリングした結果を AudioBuffer に格納して promise を返します。

[Exposed=Window]
 interface OfflineAudioContext : BaseAudioContext {
   constructor(OfflineAudioContextOptions contextOptions);
   constructor(unsigned long numberOfChannels, unsigned long length, float sampleRate);
   Promise<AudioBuffer> startRendering();
   Promise<void> resume();
   Promise<void> suspend(double suspendTime);
   readonly attribute unsigned long length;
   attribute EventHandler oncomplete;
 };
 

1.3.1. コンストラクター

OfflineAudioContext(contextOptions)

もし 現在の設定オブジェクト対応するドキュメント完全にアクティブない場合 InvalidStateError を発生しこれらのステップを中止します。

c を新しい OfflineAudioContext オブジェクトとします。c を次のように初期化します:
  1. c制御スレッドの状態"suspended" とします。

  2. cレンダリングスレッドの状態"suspended" とします。

  3. channelCountcontextOptions.numberOfChannels とした AudioDestinationNode を作成します。

OfflineAudioContext.constructor(contextOptions) メソッドの引数。
パラメーター Null可 省略可 説明
contextOptions このコンテキストを作成する際に必要な初期化パラメーター
OfflineAudioContext(numberOfChannels, length, sampleRate)

OfflineAudioContext は AudioContext.createBuffer と同じ引数で作成できます。もし引数のどれかが負、0、または範囲外の場合は NotSupportedError 例外を発生します ( MUST )。

OfflineAudioContext は、次の呼び出し

new OfflineAudioContext({
     numberOfChannels: numberOfChannels,
     length: length,
     sampleRate: sampleRate
 })
 

が行われたのと同じように作成されます。

OfflineAudioContext.constructor(numberOfChannels, length, sampleRate) メソッドの引数。
パラメーター Null可 省略可 説明
numberOfChannels unsigned long バッファが持つチャンネルの数を指定します。サポートされているチャンネル数については、 createBuffer() を参照してください。
length unsigned long バッファのサイズをサンプルフレーム数で指定します。
sampleRate float バッファ内の リニア PCM オーディオデータのサンプルレートをサンプルフレーム / 秒で記述します。有効なサンプルレートについては、createBuffer() を参照してください。

1.3.2. 属性

length, unsigned long 型, readonly

サンプルフレーム数で表したバッファのサイズです。これは、コンストラクタの length パラメーターの値と同じです。

oncomplete, EventHandler

OfflineAudioCompletionEvent 型の EventHandler です。これは OfflineAudioContext で最後に発行されるイベントです。

1.3.3. メソッド

startRendering()

現在の接続と変化のスケジュールが与えられると、オーディオのレンダリングが開始されます。

レンダリングされたオーディオデータを取得する主な方法は、promise の戻り値を経由する方法ですが、インスタンスは歴史的な理由により、complete という名前のイベントも発生させます。

[[rendering started]] をこの OfflineAudioContext の内部スロットとします。 このスロットは false に初期化されます。

startRendering が呼び出されたとき、制御スレッド で次の手順を実行しなくてはなりません ( MUST ) :

  1. OfflineAudioContext[[rendering started]] スロットが true の場合、InvalidStateError でリジェクトした promise を返し、これらの手順を中止します。
  2. OfflineAudioContext[[rendering started]] スロットを true に設定します。
  3. promise を新しい Promise とします。
  4. contextOptions パラメーターでこのインスタンスのコンストラクタに渡された numberOfChannelslength、および sampleRate の値にそれぞれ等しいチャンネル数、長さ、およびサンプルレートを持つ、新しい AudioBuffer を作成します。このバッファを OfflineAudioContext の内部スロット [[rendered buffer]] に割り当てます。
  5. 前項の AudioBuffer コンストラクタ呼び出し中に例外が発生した場合、この例外を持って promise をリジェクトします。
  6. そうでなく、バッファが正常に作成された場合は、オフラインレンダリングを開始 します。
  7. promise[[pending promises]] に追加します。
  8. promise を返します。
オフラインレンダリングを開始 するには、その際に作成された レンダリングスレッド で次の手順が実行されなくてはなりません ( MUST )。
  1. 現在の接続と変化のスケジュールが与えられたら、length 長のオーディオのサンプルフレームを [[rendered buffer]] にレンダリングし始めます。
  2. レンダリング量子 ごとにチェックを行い、必要ならば サスペンド します。
  3. もしサスペンドされていたコンテキストが再開された場合、バッファへのレンダリングを継続します。
  4. レンダリングが完了したら、制御スレッド のイベントループで次の手順を実行する タスクをキューに入れます:
    1. startRendering() によって作成された promise[[rendered buffer]] をもってリゾルブします。
    2. OfflineAudioCompletionEvent のインスタンスの renderedBuffer プロパティに [[rendered buffer]] を設定し、complete という名前のイベントを発行する タスクをキューに入れます
パラメーターなし
戻り値: Promise<AudioBuffer>
resume()

OfflineAudioContext がサスペンドされていた場合、その currentTime の進行を再開します。

resumte が呼び出された場合これらのステップを実行します。
  1. promise を新しい Promise とします。

  2. 次の条件が真となった場合、これらのステップを中止し promiseInvalidStateError でリジェクトします :

  3. OfflineAudioContext制御スレッドの状態 フラグを running に設定します。

  4. OfflineAudioContext を再開させるための 制御メッセージをキューに入れます

  5. promise を返します。

OfflineAudioContext を再開する 制御メッセージ を実行するとは、これらのステップを レンダリングスレッド で実行する事を意味します :
  1. OfflineAudioContext制御スレッドの状態running に設定します。

  2. オーディオグラフのレンダリング を開始します。

  3. 失敗した場合は 制御スレッドpromise をリジェクトする 制御メッセージ をキューに入れ、これらのステップを中止します :

  4. 制御スレッド のイベントループで、これらのステップを実行するタスクをキューに入れます :

    1. promise をリゾルブします。

    2. もし OfflineAudioContextstate 属性が既に "running" でない場合 :

      1. OfflineAudioContextstate 属性を "running" に設定します。

      2. OfflineAudioContext 上で statechange という名前のシンプルイベントを発行するためのタスクをキューに入れます。

パラメーターなし
戻り値: Promise<void>
suspend(suspendTime)

指定された時刻にオーディオコンテキストの時間進行の停止をスケジュールし、promise を返します。これは一般的に、OfflineAudioContext でオーディオグラフを同期して操作する場合に有用です。

サスペンドの最大の精度は レンダリング量子 のサイズであり、指定されたサスペンドの時刻は最も近い レンダリング量子 の境界に丸められることに注意してください。このため、同じ量子化されたフレーム内で複数のサスペンドをスケジュールすることはできません。また精度の高いサスペンドを確実に行うには、コンテキストが動作中でない間にスケジューリングを行う必要があります。

OfflineAudioContext.suspend() メソッドの引数。
パラメーター Null可 省略可 説明
suspendTime double 指定された時刻にレンダリングのサスペンドをスケジューリングします。時刻は レンダリング量子 のサイズで量子化されて丸められます。 量子化されたフレーム番号が
  1. 負の値、または
  2. 現在の時刻より小さいか同じ、または
  3. レンダリング全体の長さより大きいか同じ、または
  4. 同じ時刻に別のサスペンドがスケジュールされている
の場合、promise は InvalidStateError でリジェクトされます。
戻り値: Promise<void>

1.3.4. OfflineAudioContextOptions

これは OfflineAudioContext の作成の際に使用するオプションを指定します。

dictionary OfflineAudioContextOptions {
   unsigned long numberOfChannels = 1;
   required unsigned long length;
   required float sampleRate;
 };
 
1.3.4.1. ディクショナリー OfflineAudioContextOptions メンバー
length, unsigned long

サンプルフレーム数で表したレンダリングされる AudioBuffer の長さ。

numberOfChannels, unsigned long 型, デフォルトは 1

この OfflineAudioContext のチャンネル数。

sampleRate, float

この OfflineAudioContext のサンプルレート。

1.3.5. OfflineAudioCompletionEvent インターフェース

これは、歴史的な理由から OfflineAudioContext に発行される Event オブジェクトです。

[Exposed=Window]
 interface OfflineAudioCompletionEvent : Event {
   constructor (DOMString type, OfflineAudioCompletionEventInit eventInitDict);
   readonly attribute AudioBuffer renderedBuffer;
 };
 
1.3.5.1. 属性
renderedBuffer, AudioBuffer 型, readonly

レンダリングしたオーディオデータを保持する AudioBuffer です。

1.3.5.2. OfflineAudioCompletionEventInit
dictionary OfflineAudioCompletionEventInit : EventInit {
   required AudioBuffer renderedBuffer;
 };
 
1.3.5.2.1. ディクショナリー OfflineAudioCompletionEventInit メンバー
renderedBuffer, AudioBuffer

イベントの renderedBuffer 属性に割り当てる値。

1.4. AudioBuffer インターフェース

このインターフェースは、メモリー上にあるオーディオデータを表します。そのフォーマットはノンインタリーブな 32 ビットの浮動小数点の リニア PCM で、通常は \([-1, 1]\) の範囲になりますが、値はこの範囲に限定はされません。これは 1 つまたは複数のチャンネルを持つことができます。通常、PCM データの長さはかなり短く ( 通常は 1 分未満 ) と想定されています。音楽サウンドトラックなどのより長いサウンドの場合、audio 要素と MediaElementAudioSourceNode によるストリーミングを使うべきです。

AudioBuffer は、1 つ以上の AudioContext によって使用され、OfflineAudioContextAudioContext の間で共有する事もできます。

AudioBuffer には 4 つの内部スロットがあります:

[[number of channels]]

この AudioBuffer のオーディオチャンネルの数、符号なし long 型です。

[[length]]

この AudioBuffer の各チャンネルの長さ、符号なし long 型です。

[[sample rate]]

Hz で表した AudioBuffer のサンプルレート、float 型です。

[[internal data]]

オーディオのサンプルデータを保持する データブロック です。

[Exposed=Window]
 interface AudioBuffer {
   constructor (AudioBufferOptions options);
   readonly attribute float sampleRate;
   readonly attribute unsigned long length;
   readonly attribute double duration;
   readonly attribute unsigned long numberOfChannels;
   Float32Array getChannelData (unsigned long channel);
   void copyFromChannel (Float32Array destination,
                         unsigned long channelNumber,
                         optional unsigned long bufferOffset = 0);
   void copyToChannel (Float32Array source,
                       unsigned long channelNumber,
                       optional unsigned long bufferOffset = 0);
 };
 

1.4.1. コンストラクター

AudioBuffer(options)
  1. options の値のいずれかが公称範囲外にある場合は、NotSupportedError 例外を発生し、以下の手順を中止します。

  2. b を新しい AudioBuffer オブジェクトとします。

  3. コンストラクタで渡された AudioBufferOptions の属性 numberOfChannelslengthsampleRate の値をそれぞれ内部スロット [[number of channels]][[length]][[sample rate]] に割り当てます。

  4. この AudioBuffer の内部スロット [[internal data]] CreateByteDataBlock([[length]] * [[number of channels]]) を呼び出した結果に設定します。

    注 : これは、下層にある記憶域をゼロに初期化します。

  5. b を返します。

AudioBuffer.constructor(options) メソッドの引数。
パラメーター Null可 省略可 説明
options AudioBufferOptions AudioBufferOptions はこの AudioBuffer のプロパティを決定します。

1.4.2. 属性

duration, double 型, readonly

PCM オーディオデータの長さで、単位は秒です。

これは [[sample rate]]AudioBuffer[[length]] から計算され、[[length]][[sample rate]] で割る事で求められます。

length, unsigned long 型, readonly

サンプルフレーム数で表した PCM オーディオデータの長さです。これは [[length]] の値を返さなければなりません ( MUST )。

numberOfChannels, unsigned long 型, readonly

個別のオーディオチャンネルの数です。これは [[number of channels]] の値を返さなければなりません ( MUST )。

sampleRate, float 型, readonly

サンプル / 秒で表した PCM オーディオデータのサンプルレートです。これは、[[sample rate]] の値を返さなければなりません ( MUST )。

1.4.3. メソッド

copyFromChannel(destination, channelNumber, bufferOffset)

copyFromChannel() メソッドは、AudioBuffer の指定されたチャンネルからサンプルを destination の配列にコピーします。

buffer を \(N_b\) フレームの AudioBuffer とし、\(N_f\) を destination 配列の要素数とし、\(k\) を bufferOffset の値とします。このとき、 buffer から destination にコピーされるフレームの数は \(\max(0, \min(N_b - k, N_f))\) となります。もしこれが \(N_f\) より小さい場合、destination の残りの要素は変更されません。

AudioBuffer.copyFromChannel() メソッドの引数。
パラメーター Null可 省略可 説明
destination Float32Array チャンネルデータがコピーされる配列です。
channelNumber unsigned long データをコピーするチャンネルのインデックスです。channelNumberAudioBuffer のチャンネル数と同じか大きい場合、IndexSizeError 例外を発生します ( MUST )。
bufferOffset unsigned long オプションのオフセットで、デフォルトは 0 です。AudioBuffer のこのオフセットから始まるデータが destination にコピーされます。
戻り値: void
copyToChannel(source, channelNumber, bufferOffset)

copyToChannel() メソッドは、source 配列から AudioBuffer の指定されたチャンネルにサンプルをコピーします。

もし、source がバッファにコピーできない場合は UnknownError を発生する事があります。

buffer を \(N_b\) フレームの AudioBuffer とし \(N_f\) を source 配列の要素数とし、\(k\) を bufferOffset の値とします。このとき、source から buffer にコピーされるフレームの数は \(\max(0, \min(N_b - k, N_f))\) となります。これが \(N_f\) より小さい場合、buffer の残りの要素は変更されません。

AudioBuffer.copyToChannel() メソッドの引数。
パラメーター Null可 省略可 説明
source Float32Array チャンネルデータがコピーされる元の配列です。
channelNumber unsigned long データをコピーする先のチャンネルのインデックスです。もし channelNumberAudioBuffer のチャンネル数より大きいか同じ場合、IndexSizeError を発生します ( MUST )。
bufferOffset unsigned long データをコピーする先を示すオプションのオフセットで、デフォルトは 0 です。source からのデータが AudioBuffer のこのオフセットから始まる場所にコピーされます。
戻り値: void
getChannelData(channel)

コンテンツの取得 で説明されているルールに従って、新しい Float32Array[[internal data]] に格納されているバイトの 参照を取得 または バイトの コピーを取得 します。

もし、[[internal data]] (訳注: の読み出し) または新しい Float32Array の作成ができなかった場合は、UnknownError を発生する事があります。

AudioBuffer.getChannelData() メソッドの引数。
パラメーター Null可 省略可 説明
channel unsigned long このパラメーターは、データを取得する特定のチャンネルを表すインデックスです。インデックス値 0 は最初のチャンネルを表します。このインデックス値は [[number of channels]] より小さくなくてはならず ( MUST )、そうでない場合は IndexSizeError 例外を発生します ( MUST )。
戻り値: Float32Array

注 : copyToChannel()copyFromChannel() メソッドはより大きな配列のビューである Float32Array を渡す事で配列の一部だけを埋めるのに使用できます。 AudioBuffer のチャンネルからデータを読み取ってまとめて処理する場合、不要なメモリの割り当てとコピーを回避するため、getChannelData() を呼び出して結果の配列にアクセスするよりも、copyFromChannel()をお勧めします。

APIの実装が AudioBuffer の内容が必要になったとき、AudioBuffer の内容の取得という内部処理が起動されます。この処理は呼び出し元に変更不能なチャンネルデータを返します。

AudioBuffer内容の取得 処理が発生した場合は次の手順で実行されます:
  1. AudioBufferArrayBuffer の一部でも IsDetachedBuffer 処理に対して true を返した場合、これらの手順を中止し、呼び出し元に長さ 0 のチャンネルデータバッファを返します。

  2. この AudioBuffergetChannelData() によってこれまでに返された配列のすべての ArrayBufferデタッチ します。

    注 : AudioBuffercreateBuffer() または AudioBuffer コンストラクターを介してのみ作成できるため、これは例外を起こしません。

  3. これらの ArrayBuffer の下層にある [[internal data]] を保持したまま、それらへの参照を呼び出し側に返します。

  4. AudioBuffer のデータのコピーを保持する ArrayBuffer をアタッチして次回の getChannelData() の呼び出しで返せるようにします。

AudioBuffer の内容の取得 処理は、次の場合に呼び出されます:

注 :これは copyToChannel() は現在 AudioNodeAudioBuffer の内容を取得 して使用中の AudioBuffer の内容を変更するためには使えない事を意味します。AudioNode は以前に取得したデータを使い続けます。

1.4.4. AudioBufferOptions

これは AudioBuffer の作成に使用するオプションを指定します。 lengthsampleRate メンバーは必須です。

dictionary AudioBufferOptions {
   unsigned long numberOfChannels = 1;
   required unsigned long length;
   required float sampleRate;
 };
 
1.4.4.1. ディクショナリー AudioBufferOptions メンバー

このディクショナリのメンバーが取れる値には制約があります。createBuffer() を参照してください。

length, unsigned long

サンプルフレーム数で表されるバッファの長さです。制約については length を参照してください。

numberOfChannels, unsigned long 型, デフォルトは 1

バッファのチャンネル数です。制約については numberOfChannels を参照してください。

sampleRate, float

Hz で表されるバッファのサンプルレートです。制約については sampleRate を参照してください。

1.5. AudioNode インターフェース

AudioNodeAudioContext を構成するブロックです。このインターフェースは、音源、音の出力先、および中間の処理モジュールを表しています。これらのモジュールは互いに接続されて、音をオーディオハードウェアに出力するための 処理グラフ を形成します。それぞれのノードは 入力出力 を持つ事ができます。ソースノード は入力を持たず、単一の出力を持ちます。フィルターのようなほとんどの処理ノードは、1 つの入力と 1 つの出力を持ちます。それぞれのタイプの AudioNode はどのようにオーディオを処理したり合成するのかの詳細が異なっています。しかし一般的に AudioNode は ( 持っていれば ) 入力を処理し、( 持っていれば ) その出力にオーディオ信号を送り出します。

それぞれの出力は 1 つ以上のチャンネルを持っています。正確なチャンネル数はそれぞれの AudioNode の詳細に依存します。

出力は 1 つ以上の AudioNode の入力に接続でき、つまり ファンアウト がサポートされています。入力は初期状態では接続されていません。しかし、1 つ以上の AudioNode の出力から接続する事ができ、即ち、ファンインがサポートされています。AudioNode の出力を AudioNode の入力に接続するため connect() メソッドが呼ばれたとき、それをその入力への 接続 と呼びます。

AudioNode入力 はその時々で特定のチャンネル数を持ちます。この数はその入力への 接続 によって変化します。もし入力が接続を持っていない場合、チャンネル数は 1 で無音となります。

AudioNode は 各々の 入力 について、その入力へのすべての接続のミキシングを行います。この詳細な基準となる要件については § 4 チャンネルのアップミックスとダウンミックス セクションを参照してください。

AudioNode の入力および内部の処理は、そのノードが出力を接続されているか、またそれらの出力が AudioContextAudioDestinationNode に最終的に到達しているかどうかに関わらず、AudioContext の時刻を踏まえて継続的に行われます。

[Exposed=Window] interface AudioNode : EventTarget {
   AudioNode connect (AudioNode destinationNode,
                      optional unsigned long output = 0,
                      optional unsigned long input = 0);
   void connect (AudioParam destinationParam, optional unsigned long output = 0);
   void disconnect ();
   void disconnect (unsigned long output);
   void disconnect (AudioNode destinationNode);
   void disconnect (AudioNode destinationNode, unsigned long output);
   void disconnect (AudioNode destinationNode,
                    unsigned long output,
                    unsigned long input);
   void disconnect (AudioParam destinationParam);
   void disconnect (AudioParam destinationParam, unsigned long output);
   readonly attribute BaseAudioContext context;
   readonly attribute unsigned long numberOfInputs;
   readonly attribute unsigned long numberOfOutputs;
   attribute unsigned long channelCount;
   attribute ChannelCountMode channelCountMode;
   attribute ChannelInterpretation channelInterpretation;
 };
 

1.5.1. AudioNode の作成

AudioNode の作成には 2 つの方法があります: 特定のインターフェースのコンストラクタを使用する方法、と BaseAudioContext または AudioContextファクトリーメソッド を使用する方法です。

AudioNode のコンストラクタの最初の引数として渡される BaseAudioContext は、作成される AudioNode関連する BaseAudioContext と呼ばれます。同様に、ファクトリーメソッドを使用する場合、AudioNode関連する BaseAudioContext は このファクトリーメソッドが呼び出される BaseAudioContext です。

BaseAudioContext c 上の ファクトリーメソッド の呼び出しにより、特定のタイプ n の新しい AudioNode を作成するには、次の手順を実行します:
  1. node を型 n の新しいオブジェクトとします。

  2. option を、このファクトリーメソッドに 関連付け られたインターフェースに 関連付け られた型のディクショナリーとします。

  3. ファクトリーメソッドに渡される各パラメーターについて、option 内の名前が一致するディクショナリメンバーをこのパラメーターの値に設定します。

  4. node の作成のために coption を引数として n の コンストラクターを呼び出します。

  5. node を返します。

AudioNode から継承したオブジェクト o初期化 する事は、このインターフェースのコンストラクタに引数 contextdict を渡して、次のステップを実行することを意味します。
  1. contexto が関連付けられた BaseAudioContext とします。

  2. numberOfInputsnumberOfOutputschannelCountchannelCountModechannelInterpretation の値を、各 AudioNode のセクションで説明するそれぞれのインターフェースのデフォルト値に設定します。

  3. 渡されたdictのそれぞれのメンバーについて、k をメンバーのキー、v をその値として以下の手順を実行します。手順の実行の際に何らかの例外が発生した場合は反復処理を中止し、例外をアルゴリズムの呼び出し元 ( コンストラクターまたはファクトリーメソッド ) に伝えます。

    1. k がこのインターフェースの AudioParam の名前である場合、この AudioParamvalue 属性を v に設定します。

    2. そうでなく、k がこのインターフェースの属性の名前である場合、この属性に関連付けられたオブジェクトを v に設定します。

ファクトリーメソッドに 関連するインターフェース は、このメソッドから返されるオブジェクトのインターフェースです。インターフェースに 関連するオプションオブジェクト は、このインターフェースのコンストラクタに渡すことができるオプションオブジェクトです。

AudioNode[DOM] で説明されているように EventTarget です。つまり、他の EventTarget がイベントを受け入れるのと同じ方法で、イベントを AudioNode にディスパッチすることができます。

enum ChannelCountMode {
   "max",
   "clamped-max",
   "explicit"
 };
 

ChannelCountMode は、ノードの channelCount および channelInterpretation の値と組み合わせて、ノードへの入力をどのようにミックスするかを制御する computedNumberOfChannels を決定するために使用されます。computedNumberOfChannels は次のように決定されます。ミックスがどのように行われるかの詳細については、§ 4 チャンネルのアップミックスとダウンミックス を参照してください。

列挙値の説明
"max" computedNumberOfChannels は入力となっている全接続のチャンネル数の最大値になります。このモードでは channelCount は無視されます。
"clamped-max" computedNumberOfChannels は "max" のときと同じように計算されますが、指定された channelCount を上限に制限されます。
"explicit" computedNumberOfChannels の値は channelCount によって指定された値そのものになります。
enum ChannelInterpretation {
   "speakers",
   "discrete"
 };
 
列挙値の説明
"speakers" アップミックス式 または ダウンミックス式 を使用します。チャンネル数がスピーカーの基本レイアウトに合致しない場合は、"discrete" に戻します。
"discrete" アップミックスの場合は、チャンネルを使い切るまで順に埋めて行き、余っているチャンネルには 0 を出力します。ダウンミックスでは、可能な限りチャンネルを順に埋め、余ったチャンネルは捨てられます。

1.5.2. AudioNode Tail-Time

AudioNodeテールタイム を持つことができます。 これは AudioNode に無音が供給されている場合でも、出力が無音では無い可能性があることを意味します。

AudioNode は過去の入力が将来の出力に影響するような内部処理状態を持っている場合、非ゼロのテールタイムを持っています。 AudioNode は、入力が音のある状態から無音に移行した後でも、計算されたテールタイムの間、音を出力し続ける場合があります。

1.5.3. AudioNode のライフタイム

AudioNode は次のいずれかの条件が満たされている場合、レンダリング量子 の間 アクティブに処理 を続けます。

注 : これは AudioNodeテールタイム を持つ事を考慮に入れます。

アクティブに処理 を行っていない AudioNode は 1 チャンネルの無音を出力します。

1.5.4. 属性

channelCount, unsigned long

channelCount はノードへの入力の接続におけるアップミックスおよびダウンミックスの際に使用されるチャンネル数です。値が別途定められている特定のノードを除いて、デフォルトは 2 です。この属性は入力を持たないノードでは意味を持ちません。もしこの値が 0、あるいは実装のチャンネル数の最大値より大きい値にセットされた場合、NotSupportedError 例外を発生します ( MUST )。

さらに、一部のノードではこれに加えて チャンネル数の制約 があります:

AudioDestinationNode

この動作は、接続先のデスティネーションノードが AudioContextOfflineAudioContext かによって異なります:

AudioContext

チャンネル数は 1 から maxChannelCount の間でなければなりません ( MUST )。この範囲外の値を設定しようとすると、IndexSizeError 例外を発生します ( MUST )。

OfflineAudioContext

チャンネル数を変更することはできません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

AudioWorkletNode

§ 1.32.3.3.2 AudioWorkletNodeOptions によるチャンネルの設定」 でのチャンネル設定を参照してください。

ChannelMergerNode

チャンネル数を変更することはできません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

ChannelSplitterNode

チャンネル数を変更することはできません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

ConvolverNode

チャンネル数は 2 より大きくできません。2 より大きい値を設定しようとすると NotSupportedError 例外を発生します ( MUST )。

DynamicsCompressorNode

チャンネル数は 2 より大きい値にはできません。2 より大きい値に変更しようとすると NotSupportedError 例外を発生します ( MUST )。

PannerNode

チャンネル数は 2 より大きくすることはできません。2 より大きな値に変更しようとすると NotSupportedError 例外を発生します ( MUST )。

ScriptProcessorNode

チャンネル数は変更することができません。変更しようとすると NotSupportedError 例外を発生します ( MUST )。

StereoPannerNode

チャンネル数は 2 より大きくすることはできません。2 より大きな値に変更しようとすると NotSupportedError 例外を発生します ( MUST )。

この属性の詳細については、§ 4 チャンネルのアップミックスとダウンミックス を参照してください。

channelCountMode, ChannelCountMode

channelCountMode は、ノードの入力への接続をアップミックスおよびダウンミックスするときに、チャンネルがどのようにカウントされるかを決定します。デフォルト値は "max" です。この属性は、入力のないノードには影響しません。

さらに、一部のノードでは、チャンネル数モードが取れる値について channelCountMode の制約 があります。

AudioDestinationNode

AudioDestinationNodeOfflineAudioContextdestination ノードである場合、チャンネル数モードは変更できません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

ChannelMergerNode

チャンネル数モードは "explicit" から変更できません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

ChannelSplitterNode

チャンネル数モードは "explicit" から変更できません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

ConvolverNode

チャンネル数モードは "max" に設定する事はできません。値を "max" に設定しようとすると NotSupportedError 例外を発生します ( MUST )。

DynamicsCompressorNode

チャンネル数モードは "max" に設定する事はできません。値を "max" に設定しようとすると NotSupportedError 例外を発生します ( MUST )。

PannerNode

チャンネル数モードは "max" に設定する事はできません。値を "max" に設定しようとすると NotSupportedError 例外を発生します ( MUST )。

ScriptProcessorNode

チャンネル数モードは "explicit" から変更できません。値を変更しようとすると NotSupportedError 例外を発生します ( MUST )。

StereoPannerNode

チャンネル数モードは "max" に設定する事はできません。値を "max" に設定しようとすると NotSupportedError 例外を発生します ( MUST )。

この属性の詳細については、§ 4 チャンネルのアップミックスとダウンミックス を参照してください。

channelInterpretation, ChannelInterpretation

channelInterpretation は、ノードの入力への接続をアップミックスまたはダウンミックスするときに、個々のチャンネルをどのように扱うかを決定します。デフォルト値は "speakers" です。この属性は、入力のないノードには影響しません。

さらに、一部のノードでは、チャンネルの解釈として取れる値に追加の channelInterpretation の制約 があります。

ChannelSplitterNode

チャンネルの解釈は "discrete" から変更することはできません。値を変更しようとすると InvalidStateError 例外を発生します ( MUST )。

この属性の詳細については、§ 4 チャンネルのアップミックスとダウンミックス を参照してください。

context, BaseAudioContext 型, readonly

この AudioNode. を所有する BaseAudioContext です。

numberOfInputs, unsigned long 型, readonly

この AudioNode の入力の数です。ソースノードではこれは 0 になります。この属性は多くの AudioNode のタイプであらかじめ決められていますが、ChannelMergerNodeAudioWorkletNode のようないくつかの AudioNode では入力の数は可変です。

numberOfOutputs, unsigned long 型, readonly

この AudioNode から出る出力の数です。この属性はいくつかの AudioNode ではあらかじめ決められた値ですが、ChannelSplitterNodeAudioWorkletNode などでは可変になります。

1.5.5. メソッド

connect(destinationNode, output, input)

あるノードの特定の出力から別のノードの特定の入力への接続は 1 つだけ存在できます。同じ端子間の複数回の接続は無視されます。

例えば:
nodeA.connect(nodeB);
nodeA.connect(nodeB);
 

は次のものと同じ効果になります。

nodeA.connect(nodeB);
 

このメソッドは、destinationAudioNode オブジェクトを返します。

AudioNode.connect(destinationNode, output, input) メソッドの引数。
パラメーター Null可 省略可 説明
destinationNode destination パラメーターは接続先の AudioNode です。もし destination が他の AudioContext によって作成された AudioNode の場合、InvalidAccessError 例外を発生します ( MUST )。つまり AudioNode は複数の AudioContext 間で共有する事はできません。「チャンネルのアップミックスとダウンミックス」で説明されているように複数の AudioNode が同じ AudioNode に接続する事はできます。
output unsigned long output パラメーターは AudioNode のどの出力から接続するかを指定するインデックスです。もしこのパラメーターが範囲外の場合、IndexSizeError 例外を発生します ( MUST )。 connect() を複数回呼び出して AudioNode の出力から複数の入力に接続する事は可能です。つまり、"ファンアウト"がサポートされています。
input input パラメーターは接続先の AudioNode のどの入力に接続するかを指定するインデックスです。もしこのパラメーターが範囲外の場合、IndexSizeError 例外を発生します ( MUST )。 ある AudioNode から他の AudioNode循環を作るような接続を行う事も可能です: つまりある AudioNode から、最初の AudioNode の入力か AudioParam に接続を行っている別の AudioNode に対して接続を行う事ができます。
戻り値: AudioNode
connect(destinationParam, output)

AudioNodeAudioParam に接続し、パラメーターの値を a-rate の信号で制御します。

connect() を複数回呼び出す事で、1 つの AudioNode の出力を複数の AudioParam に接続する事が可能です。即ち "ファンアウト"がサポートされています。

connect() を複数回呼び出す事で、複数の AudioNode を 1 つの AudioParam に接続する事が可能です。即ち"ファンイン"がサポートされています。

AudioParam はそれに接続されている すべての AudioNode の出力からレンダリングされたオーディオデータを取り出し、それがモノラルでなければ、ダウンミックスによって モノラルに変換 します。そして接続されている各出力をミックスし、さらに最終的にパラメーターが持っているタイムラインの変化スケジュールを含む固有値 ( AudioParam に何も接続されていない状態での value ) とミックスします。

モノラルへのダウンミックスは、channelCount = 1、channelCountMode = "explicit"、および channelInterpretation = "speakers" の AudioNode のダウンミックスに相当します。

特定のノードの出力と特定の AudioParam の間の接続は 1 つのみ存在できます。同じ終端点を持つ複数の接続は無視されます。

例えば:
nodeA.connect(param);
nodeA.connect(param);
 

は次のものと同じ効果になります。

nodeA.connect(param);
 
AudioNode.connect(destinationParam, output) メソッドの引数。
パラメーター Null可 省略可 説明
destinationParam AudioParam destination パラメーターは接続先の AudioParam です。このメソッドは destinationAudioParam オブジェクトを返しません。 destinationParam が属する AudioNode を作成した BaseAudioContext と、このメソッドが呼び出された AudioNode を作成した BaseAudioContext が異なる場合、InvalidAccessError 例外を発生します ( MUST )。
output unsigned long output パラメーターは AudioNode のどの出力から接続するかを指定するインデックスです。もし parameter が範囲外の場合、IndexSizeError 例外を発生します ( MUST )。
戻り値: void
disconnect()

AudioNode から出るすべての接続を切断します。

パラメーターなし
戻り値: void
disconnect(output)

AudioNode の 1 つの出力から他の AudioNode または AudioParam オブジェクトへの接続をすべて切断します。

AudioNode.disconnect(output) メソッドの引数。
パラメーター Null可 省略可 説明
output unsigned long このパラメーターは接続を切る AudioNode の出力のインデックスです。これは与えられた出力から出るすべての接続を切断します。もしこのパラメーターが範囲外の場合、IndexSizeError 例外を発生します ( MUST )。
戻り値: void
disconnect(destinationNode)

AudioNode のすべての出力から特定の接続先となる AudioNode に繋がる接続を切断します。

AudioNode.disconnect(destinationNode) メソッドの引数。
パラメーター Null可 省略可 説明
destinationNode destinationNode パラメーターは切断する AudioNode です。これは与えられた destinationNode に対するすべての接続を切断します。もし destinationNode に対する接続がない場合、InvalidAccessError 例外を発生します ( MUST )。
戻り値: void
disconnect(destinationNode, output)

AudioNode の特定の出力から特定の接続先 AudioNode 入力への接続を切断します。

AudioNode.disconnect(destinationNode, output) メソッドの引数。
パラメーター Null可 省略可 説明
destinationNode destinationNode パラメーターは切断する AudioNode です。もし与えられた出力から destinationNode に対する接続がない場合、InvalidAccessError 例外を発生します ( MUST )。
output unsigned long output パラメーターは接続を切る AudioNode の出力を表すインデックスです。もしこのパラメーターが範囲外の場合は IndexSizeError 例外を発生します ( MUST )。
戻り値: void
disconnect(destinationNode, output, input)

AudioNode の特定の出力から 接続先 AudioNode の特定の入力への接続を切断します。

AudioNode.disconnect(destinationNode, output, input) メソッドの引数。
パラメーター Null可 省略可 説明
destinationNode destinationNode パラメーターは切断する AudioNode です。 もし与えられた出力から destinationNode への接続が存在しない場合、InvalidAccessError 例外を発生します ( MUST )。
output unsigned long output パラメーターは切断する AudioNode の出力のインデックスです。もしこのパラメーターが範囲外の場合、IndexSizeError 例外を発生します ( MUST )。
input input パラメーターは切断する接続先 AudioNode の入力のインデックスです。もしこのパラメーターが範囲外の場合、IndexSizeError 例外を発生します ( MUST )。
戻り値: void
disconnect(destinationParam)

特定の接続先 AudioParam に繋がる AudioNode のすべての出力を切断します。この操作によって、この AudioNode からパラメーター値の計算への寄与は 0 となります。パラメーターの固有値はこの操作に影響されません。

AudioNode.disconnect(destinationParam) メソッドの引数。
パラメーター Null可 省略可 説明
destinationParam AudioParam destinationParam パラメーターは切断する AudioParam です。もし destinationParam に対する接続がない場合は InvalidAccessError 例外を発生します ( MUST )。
戻り値: void
disconnect(destinationParam, output)

AudioNode の特定の出力から特定の AudioParam への接続を切断します。この操作によって、この AudioNode からパラメーター値の計算への寄与は 0 となります。パラメーターの固有値はこの操作に影響されません。

AudioNode.disconnect(destinationParam, output) メソッドの引数。
パラメーター Null可 省略可 説明
destinationParam AudioParam destinationParam パラメーターは切断される AudioParam です。もし destinationParam への接続が存在しない場合、InvalidAccessError 例外を発生します ( MUST )。
output unsigned long output パラメーターは切断される AudioNode の出力のインデックスです。もし parameter が範囲外の場合、IndexSizeError 例外を発生します ( MUST )。
戻り値: void

1.5.6. AudioNodeOptions

これは、すべての AudioNode の生成の際に使用できるオプションを指定します。すべてのメンバーはオプションです。ただし、それぞれのノードで使われる値は、実際のノードに依存します。

dictionary AudioNodeOptions {
   unsigned long channelCount;
   ChannelCountMode channelCountMode;
   ChannelInterpretation channelInterpretation;
 };
 
1.5.6.1. ディクショナリー AudioNodeOptions メンバー
channelCount, unsigned long

channelCount 属性に要求するチャンネル数です。

channelCountMode, ChannelCountMode

channelCountMode 属性に要求するモードです。

channelInterpretation, ChannelInterpretation

channelInterpretation 属性に要求するモードです。

1.6. AudioParam インターフェース

AudioParamAudioNode の例えば音量のような個別の機能をコントロールします。パラメーターは value 属性を使って特定の値に即時にセットする事ができます。あるいは ( AudioContextcurrentTime 属性の時間軸で ) 非常に高い時間精度で値の変化のスケジュールを組む事ができ、エンベロープ、音量のフェード、LFO、フィルタースイープ、グレイン窓、などに応用する事ができます。このような方法で任意のタイムラインベースのオートメーション曲線をすべての AudioParam に対して設定する事が可能です。またさらに、AudioNode からの出力の音声信号を AudioParam に接続する事ができ、個別に持っているパラメーターの固有値に加算する事ができます。

いくつかの合成や処理の AudioNode は、オーディオサンプル単位で反映されなくてはならない ( MUST ) AudioParam 型の属性を持っています。その他の AudioParam はサンプル単位の精度は重要ではなく、その値の変化はより粗く取り込まれます。各 AudioParama-rate パラメーターつまりサンプル単位で反映される ( MUST )か、それ以外の k-rate パラメーターかが指定されます。

実装はそれぞれの AudioNode について、1 レンダリング量子 ごとのブロック単位の処理を行わなくてはなりません ( MUST )。

それぞれの レンダリング量子 に対して、k-rate パラメーターは最初のサンプルのタイミングで取り込まれ、その値はブロック全体に対して使用されなくてはなりません ( MUST )。a-rate パラメーターはブロック内のサンプルフレームごとに取り込まれなくてはなりません ( MUST )。 AudioParam によっては、automationRate 属性を "a-rate" または "k-rate" のいずれかに設定することによって、レートを制御できます。詳細については、個々の AudioParam の説明を参照してください。

AudioParamminValue および maxValue 属性を持っており、それがパラメーターの単純な公称範囲となっています。実際のパラメーターの値は \([\mathrm{minValue}, \mathrm{maxValue}]\) の範囲に制限されます。詳細は、「§ 1.6.3 値の計算」 を参照してください。

多くの AudioParam では、minValuemaxValue は可能な最大限の範囲に設定されています。この場合、maxValue は、最も正の単精度浮動小数点値 ( 3.4028235e38 ) となります。( ただし、JavaScript では IEEE-754 倍精度浮動小数点値のみをサポートするため、これは 3.4028234663852886e38 と書かなくてはなりません ) 同様に、minValue最も負の単精度浮動小数点値、つまり 最も正の単精度浮動小数点値 の符号を負にしたもの: -3.4028235e38 となります。( 同様に、これは JavaScript では -3.4028234663852886e38 として記述する必要があります )。

AudioParam は、0 個以上の オートメーションイベント のリストを保持しています。各オートメーションイベントは、AudioContextcurrentTime 属性の時間軸における オートメーションイベント時刻 に関連して、特定の時間範囲にわたるパラメーター値の変更を指定します。オートメーションイベントのリストは、オートメーションイベント時刻の昇順で管理されます。

オートメーションイベントの振る舞いは、AudioContext の現在の時刻とこのイベントのオートメーションイベント時刻とリスト内に隣接するイベントの関数になります。以下の オートメーションメソッド は、そのメソッドに固有のタイプの新しいイベントをイベントリストに追加し、変更します:

これらのメソッドが呼ばれるとき、次の規則が適用されます:

注 : AudioParam の属性は、value 属性を除いて、読み取り専用です。

AudioParam のオートメーションレートは、automationRate 属性を次のいずれかの値で設定して選択できます。ただし、一部の AudioParam では、オートメーションレートを変更できるかどうかについて制約があります。

enum AutomationRate {
   "a-rate",
   "k-rate"
 };
 
列挙値の説明
"a-rate" この AudioParam は、a-rate での処理に設定されます。
"k-rate" この AudioParam は、k-rate での処理に設定されます。

AudioParam には内部スロット [[current value]] があり、AudioParamdefaultValue に初期設定されています。

[Exposed=Window]
 interface AudioParam {
   attribute float value;
   attribute AutomationRate automationRate;
   readonly attribute float defaultValue;
   readonly attribute float minValue;
   readonly attribute float maxValue;
   AudioParam setValueAtTime (float value, double startTime);
   AudioParam linearRampToValueAtTime (float value, double endTime);
   AudioParam exponentialRampToValueAtTime (float value, double endTime);
   AudioParam setTargetAtTime (float target, double startTime, float timeConstant);
   AudioParam setValueCurveAtTime (sequence<float> values,
                                   double startTime,
                                   double duration);
   AudioParam cancelScheduledValues (double cancelTime);
   AudioParam cancelAndHoldAtTime (double cancelTime);
 };
 

1.6.1. 属性

automationRate, AutomationRate

AudioParam のオートメーションの速度です。デフォルト値は実際の AudioParam に依存します。デフォルト値についてはそれぞれの AudioParam の説明を参照してください。

いくつかのノードには、次のような追加の オートメーション速度の制約 があります:

AudioBufferSourceNode

AudioParamplaybackRatedetune は "k-rate" でなくてはなりません ( MUST )。速度が "a-rate" に変更された場合は、InvalidStateError が発生します。

DynamicsCompressorNode

AudioParamthresholdkneeratioattack、および release は、"k-rate" でなければなりません ( MUST )。速度が "a-rate" に変更された場合、 InvalidStateError が発生します。

PannerNode

panningModel が "HRTF" の場合、PannerNode のすべての AudioParam に対する automationRate の設定は無視されます。同様に、AudioListener のすべての AudioParamautomationRate の設定は無視されます。この場合、AudioParam は、automationRate が "k-rate" に設定されているかのように動作します。

defaultValue, float 型, readonly

value 属性の初期値です。

maxValue, float 型, readonly

パラメーターが取ることができる名目上の最大値です。minValue と組み合わせて、これはこのパラメーターの 公称範囲 となります。

minValue, float 型, readonly

パラメーターが取ることができる名目上の最小値です。maxValue と組み合わせて、これはこのパラメーターの 公称範囲 となります。

value, float

パラメーターの浮動小数点の値です。この属性の初期値は defaultValue となります。

この属性を読み取ると、[[current value]] スロットの内容が返されます。返される値のアルゴリズムについては 「§ 1.6.3 値の計算」 を参照してください。

この属性を設定すると、要求された値を [[current value]] スロットに割り当て、現在の AudioContextcurrentTime[[current value]] を使って setValueAtTime() メソッドを呼び出す効果があります。setValueAtTime() で発生する例外がこの属性を設定する事でも発生する事があります。

1.6.2. メソッド

cancelAndHoldAtTime(cancelTime)

これは cancelTime と同じかそれ以降の時刻のスケジュールされたすべてのパラメーターの変化をキャンセルするという点で cancelScheduledValues() と似ていますが、それに加えて cancelTime の時点でのオートメーション値が、他のオートメーションイベントが起こるまで、保持されます。

オートメーションが動作中に cancelAndHoldAtTime()を呼び出してから cancelTime に達するまでの任意の時間の cancelAndHoldAtTime() に対するタイムラインの動作は非常に複雑です。それで cancelAndHoldAtTime() の動作は次のアルゴリズムで定義されます。

\(t_c\) を cancelTime の値とします。そして、
  1. 時刻 \(t_1\) におけるイベントを ( 存在すれば ) \(E_1\) とし、\(t_1\) が \(t_1 \le t_c\) を満たす最大の数であるとします。

  2. 時間 \(t_2\) におけるイベントを ( 存在すれば ) \(E_2\) とし、\(t_2\) が \(t_c \lt t_2\) を満たす最小の数であるとします。

  3. もし \(E_2\) が存在すれば:

    1. もし、\(E_2\) が linear または exponential 型の傾斜の場合、

      1. 実質的に \(E_2\) を書き換えて、時刻 \(t_c\) に終了し、最終値が元の傾斜の \(t_c\) の時点の値である同じ種類の傾斜とします。 Graphical representation of calling cancelAndHoldAtTime when linearRampToValueAtTime has been called at this time.

      2. ステップ 5. に行きます。

    2. そうでなければ ステップ 4. に行きます。

  4. もし \(E_1\) が存在すれば:

    1. もし \(E_1\) が setTarget イベントの場合、

      1. 時刻 \(t_c\) に setValueAtTime イベントを暗黙的に挿入し、setTarget が時刻 \(t_c\) に持つであろう値とします。
        Graphical representation of calling cancelAndHoldAtTime when setTargetAtTime has been called at this time

      2. ステップ 5. に行きます。

    2. もし \(E_1\) が setValueCurve で、開始時刻が \(t_3\) 、持続時間が \(d\) の場合

      1. もし \(t_c \gt t_3 + d\) ならば ステップ 5. に行きます。

      2. そうでなければ、

        1. 実質的にこのイベントを、開始時刻が \(t_3\)、新しい持続時間が \(t_c-t_3\) の setValueCurve イベントで置き換えます。しかしながら、これは単なる置き換えではありません。このオートメーションは、オリジナルと同じ出力を生成するために留意しなくてはならず ( MUST )、ただ異なる持続時間を使用して計算された出力ではありません。( これだと、値の曲線を少し違う方法でサンプリングして、異なる結果を生じることになります )。
          Graphical representation of calling cancelAndHoldAtTime when setValueCurve has been called at this time

        2. ステップ 5. に行きます。

  5. 時刻 \(t_c\) より後ろのすべてのイベントを削除します。

イベントが追加されない場合は、cancelAndHoldAtTime() の後のオートメーション値は、元のタイムラインが時刻 \(t_c\) に持つ定数値となります。

AudioParam.cancelAndHoldAtTime() メソッドの引数。
パラメーター Null可 省略可 説明
cancelTime double この時刻以降の以前スケジュールされたパラメーターの変化はキャンセルされます。これは、AudioContextcurrentTime 属性と同じ時間軸の時刻です。もし cancelTime が負であるか有限数でない場合、RangeError 例外を発生します ( MUST )。 cancelTimecurrentTime より小さい場合は currentTime にクランプされます。
戻り値: AudioParam
cancelScheduledValues(cancelTime)

cancelTime と同じか後ろの時刻にスケジュールされたすべてのパラメーター変化を取り消します。スケジュールされたパラメーター変化を取り消すという事は、スケジュールされたイベントをイベントリストから削除することを意味します。オートメーションイベントの時刻cancelTime 未満の現在動作中のオートメーションも取り消され、( そのオートメーション以前の ) 直前の値が直ちに復元されるため、このような取り消しは不連続を引き起こす可能性があります。cancelAndHoldAtTime() によってスケジュールされたすべてのホールド値で、cancelTime の後ろにホールドの時刻が発生した場合にもまた削除されます。

setValueCurveAtTime() の場合、\(T_0\) と \(T_D\) は それぞれこのイベントの startTimeduration とします。そして cancelTime が \([T_0, T_0 + T_D]\) の範囲内にあるならば、イベントがタイムラインから削除されます。

AudioParam.cancelScheduledValues() メソッドの引数。
パラメーター Null可 省略可 説明
cancelTime double この時刻以降で既にスケジュールされているパラメーター変化はキャンセルされます。これは AudioContextcurrentTime 属性と同じ時間軸の時刻です。もし cancelTime が負であるか、有限数でない場合 RangeError 例外を発生します ( MUST )。 cancelTimecurrentTime より小さい場合は currentTime にクランプされます。
戻り値: AudioParam
exponentialRampToValueAtTime(value, endTime)

前にスケジュールされているバラメーター値から指定された値まで、指数的に連続して値を変化させる事をスケジュールします。フィルターの周波数や再生スピードなどのパラメーターは人間の聴覚特性のため、指数的変化が適しています。

時間範囲 \(T_0 \leq t < T_1\) ( ここで \(T_0\) は前のイベントの時刻で \(T_1\) はこのメソッドに渡された endTime パラメーターです ) に対して次のように計算されます:

$$
   v(t) = V_0 \left(\frac{V_1}{V_0}\right)^\frac{t - T_0}{T_1 - T_0}
 $$
 

ここで \(V_0\) は時刻 \(T_0\) での値、\(V_1\) はこのメソッドに渡された value パラメーターです。もし \(V_0\) と \(V_1\) が、逆の符号を持つか \(V_0\) が 0 ならば、\(T_0 \le t \lt T_1\) に対して \(v(t) = V_0\) となります。

これはまた、0 に向かう指数カーブが不可能である事も示しています。setTargetAtTime() で適当な時間定数を選択する事で良い近似を得る事ができます。

もしこの ExponentialRampToValue イベント以降のイベントがない場合 \(t \geq T_1\), \(v(t) = V_1\) となります

もしこのイベントより前にイベントが存在しない場合、指数カーブは setValueAtTime(value, currentTime) が呼び出されたかのように動作します。ここで value は属性の現在の値で currentTimeexponentialRampToValueAtTime() が呼び出された時刻のコンテキストの currentTime です。

もし、前のイベントが SetTarget イベントの場合、\(T_0\) と \(V_0\) は SetTarget オートメーションの現在の時刻と値から選択されます。SetTarget イベントがまだ開始されていない場合、\(T_0\) はイベントの開始時刻であり、\(V_0\) は SetTarget イベントの開始直前の値です。この場合 ExponentialRampToValue イベントは実質的に SetTarget イベントを置き換えます。もし SetTarget イベントが既に開始されている場合、\(T_0\) は現在のコンテキストの時刻であり、\(V_0\) は時刻 \(T_0\) での現在の SetTarget オートメーションの値です。どちらの場合も、オートメーション曲線は連続しています。

AudioParam.exponentialRampToValueAtTime() メソッドの引数。
パラメーター Null可 省略可 説明
value float パラメーターが指数変化により指定された時刻に到達する値です。この値が 0 の場合、RangeError 例外を発生します ( MUST )。
endTime double AudioContextcurrentTime 属性と同じ時間軸で、指数変化が終了する時刻です。 もし endTime が負の値または有限数でない場合 RangeError 例外を発生します ( MUST )。もし endTimecurrentTime よりも小さい場合、currentTime にクランプされます。
戻り値: AudioParam
linearRampToValueAtTime(value, endTime)

前にスケジュールされているパラメーター値から指定された値まで、直線的に連続して値を変化させる事をスケジュールします。

時間範囲 \(T_0 \leq t < T_1\) ( ここで \(T_0\) は前のイベントの時刻、\(T_1\) はこのメソッドで指定された endTime です ) の間の値は次のように計算されます:

$$
   v(t) = V_0 + (V_1 - V_0) \frac{t - T_0}{T_1 - T_0}
 $$
 

ここで \(V_0\) は時刻 \(T_0\) での値、\(V_1\) はこのメソッドで指定された value パラメーターです。

もしこの LinearRampToValue イベント以降にイベントがない場合、\(t \geq T_1\), \(v(t) = V_1\) となります。

もしこのイベントにより前にイベントが存在しない場合、直線変化は setValueAtTime(value, currentTime) が呼び出されたかのように動作します。ここで value は属性の現在の値で currentTimelinearRampToValueAtTime() が呼び出されたときのコンテキストの currentTime です。

もし、前のイベントが SetTarget イベントの場合、\(T_0\) と\(V_0\) は SetTarget オートメーションの現在の時刻と値から選択されます。つまり SetTarget イベントがまだ開始されていない場合、\(T_0\) はイベントの開始時刻であり、\(V_0\) は SetTarget イベントの開始直前の値です。この場合、LinearRampToValue イベントは実質的に SetTarget イベントを置き換えます。SetTarget イベントが既に開始されている場合、\(T_0\) は現在のコンテキストの時刻であり、\(V_0\) は時刻 T0 での現在の SetTarget オートメーションの値です。どちらの場合も、オートメーションの曲線は連続しています。

AudioParam.linearRampToValueAtTime() メソッドの引数。
パラメーター Null可 省略可 説明
value float 与えられた時刻にパラメーターが直線変化で到達する値です。
endTime double AudioContextcurrentTime 属性と同じ時間軸で、オートメーションが終了する時刻です。もし endTime が負の値または有限数でない場合 RangeError 例外を発生します ( MUST )。 もし endTimecurrentTime よりも小さい場合、currentTime にクランプされます。
戻り値: AudioParam
setTargetAtTime(target, startTime, timeConstant)

指定の時刻から、指定の時定数によって指数的に目標の値に漸近を開始します。様々な使い方がありますが、これは ADSR エンベロープの "ディケイ" および "リリース" を実装する際に役立ちます。値は指定の時刻に即、目標値になるのではなく徐々に目標値に向かって変化する事に注意してください。

時間範囲 \(T_0 \leq t\) について、ここで \(T_0\) は startTime パラメーターの時刻として :

$$
   v(t) = V_1 + (V_0 - V_1)\, e^{-\left(\frac{t - T_0}{\tau}\right)}
 $$
 

ここで \(V_0\) は \(T_0\) ( startTime パラメーター ) での初期値 ( [[current value]] 属性の値 )、\(V_1\) は target パラメーター、そして \(\tau\) は timeConstant パラメーターです。

LinearRampToValue または ExponentialRampToValue イベントがこのイベントの後に続く場合、その動作はそれぞれ linearRampToValueAtTime() または exponentialRampToValueAtTime() で説明しています。他のすべてのイベントの場合は、SetTarget イベントは次のイベントの時点で終了します。

AudioParam.setTargetAtTime() メソッドの引数。
パラメーター Null可 省略可 説明
target float パラメーターが指定の時刻から変化を開始する際の目標値です。
startTime double AudioContextcurrentTime 属性と同じ時間軸で指数的漸近を開始する時刻です。もし start が負の値または有限数でない場合は RangeError 例外を発生します ( MUST )。 もし、startTimecurrentTime よりも小さい場合、currentTime の値にクランプされます。
timeConstant float 目標値に漸近する一次フィルター ( 指数 ) の時定数です。この値が大きいと変化はゆっくりになります。値は負の値ではならず ( MUST )、そうでない場合 RangeError 例外を発生します ( MUST )。 もし timeConstant がゼロの場合、出力値は直ちに最終値にジャンプします。より正確には、timeConstant は、ステップ入力応答 ( 0 から 1 への遷移 ) が与えられた場合、一次線形連続時間不変システムが値 \(1 - 1/e\) ( 約 63.2% ) に達する時間です。
戻り値: AudioParam
setValueAtTime(value, startTime)

指定の時刻になるとパラメーター値を変更するようにスケジュールします。

もしこの SetValue イベントの後にもうイベントがない場合、 \(t \geq T_0\) に対して \(v(t) = V\) ここで \(T_0\) は startTime パラメーター 、そして \(V\) は value パラメーターの値です。別の言い方をすれば、値は定数のまま保持されます。

もしこの SetValue イベントの次のイベント ( 時刻は \(T_1\) ) が LinearRampToValue または ExponentialRampToValue でない場合、\(T_0 \leq t < T_1\) に対して:

$$
   v(t) = V
 $$
 

別の言い方をすれば、値に "ステップ" を作ってこの期間、定数のまま保持されます。

この SetValue イベントに続く次のイベントが LinearRampToValue または ExponentialRampToValue の場合、linearRampToValueAtTime() または exponentialRampToValueAtTime() をそれぞれ参照してください。

AudioParam.setValueAtTime() メソッドの引数。
パラメーター Null可 省略可 説明
value float 指定の時刻にパラメーターが変化する値です。
startTime double BaseAudioContextcurrentTime 属性と同じ時間軸で与えられた値に変化する時刻です。もし startTime が負の値または有限数でない場合は RangeError 例外を発生します ( MUST )。 もし startTimecurrentTime よりも小さい場合、currentTime にクランプされます。
戻り値: AudioParam
setValueCurveAtTime(values, startTime, duration)

指定の時刻と期間に対して、任意の値の配列を設定します。値の個数は必要とされる期間に合うようにスケーリングされます。

\(T_0\) を startTime、\(T_D\ を duration、\(V\) を values 配列、\(N\) を values 配列の長さとすると、期間 \(T_0 \le t < T_0 + T_D\) の間、次のようになります:

$$
   \begin{align*} k &= \left\lfloor \frac{N - 1}{T_D}(t-T_0) \right\rfloor \\
   \end{align*}
 $$
 

そして \(v(t)\) は \(V[k]\) と \(V[k+1]\) の間で直線補間されます。

曲線の期間が終了した後、(\(t \ge T_0 + T_D\)) に対して値は ( もしあれば ) 別のオートメーションイベントまで、最後の曲線の値を保持します。

時刻 \(T_0 + T_D\) 、値 \(V[N-1]\) として暗黙的な setValueAtTime() の呼び出しが行われ、以後のオートメーションは setValueCurveAtTime() イベントの終わりから開始するようになります。

AudioParam.setValueCurveAtTime() メソッドの引数。
パラメーター Null可 省略可 説明
values sequence<float> パラメーター値の曲線を表す float 値のシーケンスです。これらの値は、指定された時刻から開始される、指定された期間に割り当てられます。このメソッドが呼び出されると、オートメーションのためにカーブの内部的なコピーが作成されます。そのため、それ以降に渡した配列の中身を変更しても AudioParam に対する効果はありません。この属性の sequence<float> オブジェクトの長さが 2 未満の場合、InvalidStateError が発生します ( MUST )。
startTime double AudioContextcurrentTime 属性と同じ時間軸の曲線の適用を開始する時刻です。もし startTime が負の値または有限数でない場合 RangeError 例外を発生します ( MUST )。 もし startTimecurrentTime よりも小さい場合、currentTime の値にクランプされます。
duration double ( startTime パラメーターの時刻の後 ) values パラメーターに基づいて値が計算される期間の秒数です。もし duration( 訳注: 0 を含まない ) 厳密に正でないか、有限数でない場合、RangeError 例外を発生します ( MUST )。
戻り値: AudioParam

1.6.3. 値の計算

AudioParam には、単純パラメーター複合パラメーター という 2 つの異なる種類があります。単純パラメーター ( デフォルト ) は、AudioNode の最終的なオーディオ出力を計算するために単独で使用されます。複合パラメーターは、他の AudioParam と一緒に合わせて計算された値が、AudioNode の出力を計算するための入力となる AudioParam です。

computedValue はオーディオ DSP を制御する最終的な値であり、オーディオレンダリングスレッドによって、それぞれのレンダリング量子の時刻に計算します。

AudioParam の値の計算は 2 つの部分から成ります:

これらの値は次のように計算されなくてはなりません (MUST):

  1. paramIntrinsicValue は毎回計算されます。これは value 属性に直接設定された値であるか、以前または現在 オートメーションイベント が存在するならばこれらのイベントから計算された値です。 もしその時間範囲からオートメーションイベントが削除された場合 paramIntrinsicValue 値は変更されず value 属性が直接設定されるか時間範囲にオートメーションイベントが追加されるまで、以前の値のままになります。

  2. [[current value]] を この レンダリング量子 の先頭での paramIntrinsicValue の値にします。

  3. paramComputedValueparamIntrinsicValue の値と 入力される AudioParam バッファ の値の合計です。 合計が NaN の場合、合計を defaultValue に置き換えます。

  4. この AudioParam複合パラメーター の場合、他の AudioParam と組み合わせてその最終値を計算します。

  5. computedValueparamComputedValue に設定します。

computedValue公称範囲 は、このパラメーターが実質的に持つことができる最小値と最大値です。単純パラメーター の場合、computedValue はこのパラメーターの 単純な公称範囲 内にクランプされます。複合パラメーター では、複合される別の AudioParam の値と合わせて計算された後、最終的な値が 公称範囲 にクランプされます。

オートメーションメソッドを使用する場合にも、クランプは依然として適用されます。ただし、オートメーション自体はクランプが全くないかのように実行され、オートメーションの値が出力される際にのみ、上記のクランプが実行されます。

例えば、ノード \(N\) が \([0, 1]\) の公称範囲を有する AudioParam \(p\) を持っているとき、次のオートメーションのシーケンスは
N.p.setValueAtTime(0, 0);
N.p.linearRampToValueAtTime(4, 1);
N.p.linearRampToValueAtTime(0, 2);
 

曲線の最初の勾配は 4 であり、最大値 1 に達すると出力は一定に保たれます。最後に、時刻 2 の近くで、曲線の傾きは -4 になります。これを図示したのが下のグラフで、破線はクリッピングされない場合に何が起こったかを示し、実線は公称範囲へのクリッピングによる audioparam の実際の予想される動作を示しています。

AudioParam automation clipping to nominal
AudioParam のオートメーションの公称範囲によるクリッピング。

1.6.4. AudioParam オートメーションの例

AudioParam automation
パラメーターオートメーションの例。
const curveLength = 44100;const curve = new Float32Array(curveLength);for (const i = 0; i < curveLength; ++i)  curve[i] = Math.sin(Math.PI * i / curveLength);const t0 = 0;const t1 = 0.1;const t2 = 0.2;const t3 = 0.3;const t4 = 0.325;const t5 = 0.5;const t6 = 0.6;const t7 = 0.7;const t8 = 1.0;const timeConstant = 0.1;param.setValueAtTime(0.2, t0);param.setValueAtTime(0.3, t1);param.setValueAtTime(0.4, t2);param.linearRampToValueAtTime(1, t3);param.linearRampToValueAtTime(0.8, t4);param.setTargetAtTime(.5, t4, timeConstant);// Compute where the setTargetAtTime will be at time t5 so we can make// the following exponential start at the right point so there’s no// jump discontinuity. From the spec, we have// v(t) = 0.5 + (0.8 - 0.5)*exp(-(t-t4)/timeConstant)// Thus v(t5) = 0.5 + (0.8 - 0.5)*exp(-(t5-t4)/timeConstant)param.setValueAtTime(0.5 + (0.8 - 0.5)*Math.exp(-(t5 - t4)/timeConstant), t5);param.exponentialRampToValueAtTime(0.75, t6);param.exponentialRampToValueAtTime(0.05, t7);param.setValueCurveAtTime(curve, t7, t8 - t7);

1.7. AudioScheduledSourceNode インターフェース

このインターフェースは、AudioBufferSourceNodeConstantSourceNode、および OscillatorNode などのソースノードの共通の機能を表します。

( start() を呼び出すことによって ) ソースが開始されるより前は、ソースノードは無音 ( 0 ) を出力しなければなりません ( MUST )。(stop() を呼び出すことによって ) ソースが停止した後、ソースは無音 ( 0 ) を出力しなければなりません ( MUST )。

AudioScheduledSourceNode は直接インスタンス化することはできませんが、代わりにソースノードの具体的なインターフェースに拡張されています。

AudioScheduledSourceNode は関連付けられている BaseAudioContextcurrentTimeAudioScheduledSourceNode が開始するように設定されている時間以上で、停止するように設定されている時間未満の場合に、再生中 になります。

AudioScheduledSourceNode は作成時から内部にブーリアンスロット [[source started]] を持っており、最初は false に設定されています。

[Exposed=Window]
 interface AudioScheduledSourceNode : AudioNode {
   attribute EventHandler onended;
   void start(optional double when = 0);
   void stop(optional double when = 0);
 };
 

1.7.1. 属性

onended, EventHandler

この属性は AudioScheduledSourceNode 型のノードに送られる ended イベントの EventHandler ( HTML[HTML] で説明されています ) を設定します。ソースノードが ( 実際のノードによって決まる方法で ) 再生を停止した時 Event 型のイベント ( HTML [HTML] で説明されています ) がイベントハンドラーに送られます。

すべての AudioScheduledSourceNodestop() によって設定された停止時間に達すると onended イベントが発行されます。 AudioBufferSourceNode の場合、再生が duration の時間に達したか、buffer 全体を再生し終わった場合にも、イベントが送出されます。

1.7.2. メソッド

start(when)

指定した時刻に音を再生するようにスケジュールします。

このメソッドが呼ばれると以下の手順を実行します:
  1. もしこの AudioScheduledSourceNode の内部スロット [[source started]] が true ならば、 InvalidStateError 例外を発生します ( MUST ) 。

  2. 後述するパラメーターの制約のために発生するエラーがないかを調べます。もし何らかの例外が発生した場合、以降のステップを中止します。

  3. この AudioScheduledSourceNode の内部スロット [[source started]]true に設定します。

  4. メッセージ内のパラメーター値を含めて AudioScheduledSourceNode を開始するための 制御メッセージをキューに入れます

  5. 次の条件が満たされた場合にのみ レンダリングスレッドで実行 するための 制御メッセージ を関連付けられた AudioContext に 送信します :

    1. コンテキストの 制御スレッドの状態suspendedである。

    2. コンテキストが スタート可能 である。

    3. [[suspended by user]] フラグが false である。

AudioScheduledSourceNode.start(when) メソッドの引数。
パラメーター Null可 省略可 説明
when double when パラメーターは、サウンドの再生開始時刻を秒単位で表します。これは、AudioContextcurrentTime 属性と同じ時間軸を使用します。いつ AudioScheduledSourceNode が信号を出力するかは開始時刻に依存し、when の正確な値は常に丸めずにサンプルフレーム単位で使用されます。この値に 0 が渡された場合、または値が currentTime よりも小さい場合は、音が即時に再生されます。もし when が負の場合には RangeError 例外を発生します ( MUST )。
戻り値: void
stop(when)

正確な時刻に音の再生を停止するようにスケジュールします。もし stop がすでに呼び出された後に再度呼び出された場合は、最後の呼び出しだけが適用されます。後続のコールの前にバッファがすでに停止していない限り、前回の呼び出しで設定された停止時刻は適用されません。バッファがすでに停止している場合は、さらに stop を呼び出しても効果はありません。スケジュールされた開始時刻よりも前に停止時刻に達すると、音は再生されません。

このメソッドが呼ばれた時、以下のステップを実行します:
  1. もしこの AudioScheduledSourceNode の内部スロット [[source started]]true でない時、InvalidStateError 例外を発生します (MUST)。

  2. 後述するパラメーターの制約のために発生するエラーがないかを調べます。

  3. パラメーター値を含めて AudioScheduledSourceNode を停止するための 制御メッセージをキューに入れます

もしノードが AudioBufferSourceNode の場合、AudioBufferSourceNode を停止する 制御メッセージ を実行することは、再生アルゴリズムhandleStop() 関数を呼び出すことを意味します。
AudioScheduledSourceNode.stop(when) メソッドの引数。
パラメーター Null可 省略可 説明
when double when パラメーターは、ソースの再生を停止する時間 ( 秒 ) を示します。これは、AudioContextcurrentTime 属性と同じ時間軸を使用します。この値に 0 が渡された場合、または値が currentTime よりも小さい場合は、音の再生は即時に停止します。もし when が負の場合には RangeError 例外を発生します ( MUST )。
戻り値: void

1.8. AnalyserNode インターフェース

このインターフェースはリアルタイムの周波数および時間領域の分析を可能にするノードを表します。オーディオストリームは加工されずに入力から出力に渡されます。

プロパティ 説明
numberOfInputs 1
numberOfOutputs 1 この出力は接続されずに放置される事もあります。
channelCount 2
channelCountMode "max"
channelInterpretation "speakers"
tail-time No
[Exposed=Window]
 interface AnalyserNode : AudioNode {
   constructor (BaseAudioContext context, optional AnalyserOptions options = {});
   void getFloatFrequencyData (Float32Array array);
   void getByteFrequencyData (Uint8Array array);
   void getFloatTimeDomainData (Float32Array array);
   void getByteTimeDomainData (Uint8Array array);
   attribute unsigned long fftSize;
   readonly attribute unsigned long frequencyBinCount;
   attribute double minDecibels;
   attribute double maxDecibels;
   attribute double smoothingTimeConstant;
 };
 

1.8.1. コンストラクター

AnalyserNode(context, options)

コンストラクターが BaseAudioContext c とオプションオブジェクト option を指定して呼び出される場合、ユーザーエージェントは引数の contextoptions を使って AudioNode this を初期化しなくてはなりません ( MUST )。

AnalyserNode.constructor(context, options) メソッドの引数。
パラメーター Null可 省略可 説明
context BaseAudioContext 新しく作成される AnalyserNode関連付け られる BaseAudioContext です。
options AnalyserOptions この AnalyserNode のオプションの初期パラメーター値です。

1.8.2. 属性

fftSize, unsigned long

周波数領域の分析に使用する FFT のサイズ ( サンプルフレーム数 ) です。これは 32 から 32768 までの 2 の累乗でなくてはならず ( MUST )、そうでなければ、IndexSizeError 例外を発生します ( MUST )。 デフォルトの値は 2048 です。大きな FFT サイズは計算量が増加する事に注意してください。

fftSize が異なる値に変更されると、( getByteFrequencyData() および getFloatFrequencyData() の ) 周波数データの平滑化に関連するすべての状態がリセットされます。つまり、時間の経過による 平滑化 に使用される 前のブロック のデータ、\(\hat{X}_{-1}[k]\) が、すべての \(k\) に対して 0 に設定されます。

fftSize を増加させた時、現在の時間領域のデータ はそれまでと異なり、より過去のサンプルフレームを含んで伸長する必要があることに注意してください。 これは実質的に AnalyserNode は最後の 32768 のサンプルフレームを常に保持しなければならない ( MUST ) ことを意味し、「現在の時間領域のデータ」は、常に最新の fftSize の大きさのサンプルフレームとなります。

frequencyBinCount, unsigned long 型, readonly

FFT サイズの半分の値です。

maxDecibels, double

maxDecibels は FFT 解析データを unsigned byte 値へ変換するスケーリングの際の最大パワー値です。デフォルトの値は -30 です。もしこの属性の値が minDecibels より小さいか同じ値に設定された場合 IndexSizeError 例外を発生します ( MUST )。

minDecibels, double

minDecibels は FFT 解析データを unsigned byte値へ変換するスケーリングの際の最少パワー値です。デフォルトの値は -100 です。もしこの属性の値が maxDecibels よりも大きいか同じに設定された場合 IndexSizeError 例外を発生します ( MUST )。

smoothingTimeConstant, double

0 -> 1 の範囲の値で、0 ならば最後の解析フレームに対して時間平均が取られない事を表します。デフォルトの値は 0.8 です。もしこの属性の値が 0 より小さいか 1 より大きい値が設定された場合 IndexSizeError 例外を発生します ( MUST )。

1.8.3. メソッド

getByteFrequencyData(array)

引数として渡された Uint8Array が保持する バイトへの参照 を取得し 現在の周波数データ をコピーします。 配列の要素が frequencyBinCount よりも少ない場合、超過した要素は削除されます。 配列に frequencyBinCount よりも多くの要素がある場合超過した要素は無視されます。 周波数データの計算には、最新の fftSize フレームが使用されます。

getByteFrequencyData() または getFloatFrequencyData() への別の呼び出しが前の呼び出しと同じ レンダリング量子 内で発生した場合、現在の周波数データ は同じデータで更新されません。 代わりに、以前に計算されたデータが返されます。

符号なしバイト配列に格納され値は次のように計算されます。 FFT ウィンドウ処理と平滑化で説明されているように \(Y[k]\) を 現在の周波数データ とします。 次に、バイト値 \(b[k]\) は

$$
   b[k] = \left\lfloor
       \frac{255}{\mbox{dB}_{max} - \mbox{dB}_{min}}
       \left(Y[k] - \mbox{dB}_{min}\right)
     \right\rfloor
 $$
 

ここで \(\mbox{dB}_{min}\) は minDecibels、そして \(\mbox{dB}_{max}\) は maxDecibels です。 もし \(b[k]\) が 0 から 255 の範囲外である場合は \(b[k]\) をその範囲に収まるようにクリップされます。

AnalyserNode.getByteFrequencyData() メソッドの引数。
パラメーター Null可 省略可 説明
array Uint8Array このパラメーターは周波数領域の分析データをコピーする場所を示します。
戻り値: void
getByteTimeDomainData(array)

引数として渡された Uint8Array が保持する バイトへの参照 を取得し 現在の時間領域のデータ ( 波形データ ) をコピーします。 配列の要素が fftSize よりも少ない場合、超過した要素は削除されます。 配列に fftSize よりも多くの要素がある場合超過した要素は無視されます。 計算には、最新の fftSize フレームが使用されます。

unsigned byte 配列に格納される値は次のように計算されます。\(x[k]\) を時間領域データとします。バイトの値、 \(b[k]\) は、

$$
   b[k] = \left\lfloor 128(1 + x[k]) \right\rfloor.
 $$
 

もし \(b[k]\) が 0 から 255 の範囲外の場合、\(b[k]\) は範囲内にクリップされます。

AnalyserNode.getByteTimeDomainData() メソッドの引数。
パラメーター Null可 省略可 説明
array Uint8Array このパラメーターは時間領域のサンプルデータをコピーする場所を示します。
戻り値: void
getFloatFrequencyData(array)

引数として渡された Float32Array が保持する バイトへの参照 を取得し 現在の周波数データ をコピーします。もし配列が frequencyBinCount よりも小さい場合、余った要素は捨てられます。もし配列が frequencyBinCount よりも大きい場合、余剰の要素は無視されます。最も最近の fftSize のフレームが周波数データの計算に使用されます。

以前の呼び出しと同じ レンダリング量子 内で getFloatFrequencyData() または getByteFrequencyData() が再度呼び出された場合、現在の周波数データ は同じデータで更新されず、代わりに、以前に計算されたデータが返されます。

周波数データの単位は dB です

AnalyserNode.getFloatFrequencyData() メソッドの引数。
パラメーター Null可 省略可 説明
array Float32Array このパラメーターは周波数領域の分析データをコピーする場所を示します。
戻り値: void
getFloatTimeDomainData(array)

引数として渡された Float32Array が保持する バイトへの参照 を取得し、現在の時間領域データ ( 波形データ ) をコピーします。もし配列が fftSize よりも小さい場合、余った要素は捨てられます。もし配列が fftSize よりも大きい場合、余剰の要素は無視されます。最も最近の fftSize のフレームが (ダウンミックスされた後) 返されます。

AnalyserNode.getFloatTimeDomainData() メソッドの引数。
パラメーター Null可 省略可 説明
array Float32Array このパラメーターは時間領域のサンプルデータをコピーする場所を示します。
戻り値: void

1.8.4. AnalyserOptions

これは AnalyserNode を生成する際に使用するオプションを指定します。すべてのメンバーは省略可能で、もし指定されない場合は通常のデフォルト値がノードの生成に使用されます。

dictionary AnalyserOptions : AudioNodeOptions {
   unsigned long fftSize = 2048;
   double maxDecibels = -30;
   double minDecibels = -100;
   double smoothingTimeConstant = 0.8;
 };
 
1.8.4.1. ディクショナリー AnalyserOptions メンバー
fftSize, unsigned long 型, defaulting to 2048

周波数領域解析のための FFT サイズとして要求する初期値。

maxDecibels, double 型, デフォルトは -30

FFT 解析の最大パワー (dB) として要求する初期値。

minDecibels, double 型, デフォルトは -100

FFT 解析の最小パワー (dB) として要求する初期値。

smoothingTimeConstant, double 型, デフォルトは 0.8

FFT 解析のスムーズ化定数として要求する初期値。

1.8.5. 時間領域のダウンミックス

現在の時間領域データ が計算されるとき、入力信号は channelCount が 1 であり、channelCountMode が "max" であり、channelInterpretation が "speakers" であるかのように、モノラルに ダウンミックス されなければなりません。これは、AnalyserNode 自体の設定とは無関係です。最新の fftSize フレームがこのダウンミックス処理に使用されます。

1.8.6. FFT 窓関数と時間的スムージング

現在の周波数データ が計算されたとき、次の処理が行われます:

  1. 現在の時間領域データ を計算します。

  2. 時間領域の入力データに対して ブラックマン窓を適用 します。

  3. 窓関数を通した時間領域の入力データからイマジナリとリアルの周波数データを得るため、フーリエ変換を適用 します。

  4. 周波数領域データに 時間的スムージング の処理を行います。

  5. dB への変換 を行います。

次の式では \(N\) をこの AnalyserNodefftSize 属性とします。

ブラックマン窓の適用 は時間領域の入力に対して次の処理を行います。\(n = 0, \ldots, N - 1\) に対する \(x[n]\) は時間領域のデータです。ブラックマン窓は、
$$
 \begin{align*}
   \alpha &= \mbox{0.16} \\ a_0 &= \frac{1-\alpha}{2} \\
   a_1 &= \frac{1}{2} \\
   a_2 &= \frac{\alpha}{2} \\
   w[n] &= a_0 - a_1 \cos\frac{2\pi n}{N} + a_2 \cos\frac{4\pi n}{N}, \mbox{ for } n = 0, \ldots, N - 1
 \end{align*}
 $$
 

窓関数を通した信号 \(\hat{x}[n]\) は

$$
   \hat{x}[n] = x[n] w[n], \mbox{ for } n = 0, \ldots, N - 1
 $$
 
フーリエ変換の適用 は次のようなフーリエ変換の計算から成ります。\(X[k]\) は複素周波数領域のデータで \(\hat{x}[n]\) は上で計算された窓関数を通した時間領域のデータです。そして、
$$
   X[k] = \frac{1}{N} \sum_{n = 0}^{N - 1} \hat{x}[n]\, W^{-kn}_{N}
 $$
 

ただし、 \(k = 0, \dots, N/2-1\) where \(W_N = e^{2\pi i/N}\).

周波数データの 時間的スムージング は次のように処理されます:

そしてスムージングされた値\(\hat{X}[k]\) は次の式で計算されます

$$
   \hat{X}[k] = \tau\, \hat{X}_{-1}[k] + (1 - \tau)\, \left|X[k]\right|
 $$
 

ただし、 \(k = 0, \ldots, N - 1\).

dBへの変換 は次の処理で行われます。 \(\hat{X}[k]\) を 時間的スムージング で計算された値として:
$$
   Y[k] = 20\log_{10}\hat{X}[k]
 $$
 

ただし、 \(k = 0, \ldots, N-1\).

この配列、\(Y[k]\) は getFloatFrequencyData() によって出力の配列にコピーされます。getByteFrequencyData() に対しては、\(Y[k]\) は minDecibelsmaxDecibels の範囲内にクリップされ、minDecibels が 0、maxDecibels が 255 になるようにスケーリングされます。

1.9. AudioBufferSourceNode インターフェース

このインターフェースは AudioBuffer によってメモリー上に保持されているオーディオデータからのオーディオソースを表します。これはオーディオデータの再生に高度なスケジューリングの柔軟性と精度が要求される場合に役立ちます。もしネットワークからあるいはディスクからのデータをサンプル精度で再生する必要がある場合、再生機能の実装には AudioWorkletNode を使用しなくてはなりません。

start() メソッドはいつ再生されるかをスケジュールするために使用されます。start() メソッドを複数回呼び出す事はできません。再生は ( もし loop 属性が false の場合 ) バッファのオーディオデータがすべて再生されると、あるいは stop() メソッドが呼び出されて指定された時刻になると自動的に停止します。より詳細には start() および stop() の説明を参照してください。

プロパティ 説明
numberOfInputs 0
numberOfOutputs 1
channelCount 2
channelCountMode "max"
channelInterpretation "speakers"
tail-time No

出力のチャンネル数は常に buffer 属性に指定された AudioBuffer のチャンネル数と同じになります。もし buffernull の場合、チャンネルは無音の 1 チャンネルとなります。

さらに、バッファに複数のチャンネルがある場合 AudioBufferSourceNode の出力は、次のいずれかの条件が成立した後、レンダリング量子の開始時に 1 チャンネルの無音に変更する必要があります :

AudioBufferSourceNode再生ヘッド位置 は、バッファ内の最初のサンプルフレームの時刻を基準にした秒単位の時間オフセットとして定義される値です。その値はノードの playbackRate および detune パラメーターとは独立したものとして想定されます。一般に、再生ヘッド位置はサブサンプルの精度であり、正確なサンプルフレームの位置を参照するものではありません。その値は 0 とバッファ全体の長さの間で有効な値を取ります。

playbackRate および detune 属性は、 複合パラメーター を形成します。それらは組み合わせて使用され、次のように computedPlaybackRate 値を決定します:

computedPlaybackRate(t) = playbackRate(t) * pow(2, detune(t) / 1200)
 

この 複合パラメーター公称範囲 は \((-\infty, \infty)\) です。

AudioBufferSourceNode は作成されたときに ブーリアンの内部スロット [[buffer set]] を持っており、初期値は false に設定されています。

[Exposed=Window]
 interface AudioBufferSourceNode : AudioScheduledSourceNode {
   constructor (BaseAudioContext context,
                optional AudioBufferSourceOptions options = {});
   attribute AudioBuffer? buffer;
   readonly attribute AudioParam playbackRate;
   readonly attribute AudioParam detune;
   attribute boolean loop;
   attribute double loopStart;
   attribute double loopEnd;
   void start (optional double when = 0,
               optional double offset,
               optional double duration);
 };
 

1.9.1. コンストラクター

AudioBufferSourceNode(context, options)

コンストラクターが BaseAudioContext c とオプションオブジェクト option を指定して呼び出される時、ユーザーエージェントは引数の contextoptions を使って AudioNode this を初期化 しなくてはなりません ( MUST )。

AudioBufferSourceNode.constructor(context, options) メソッドの引数。
パラメーター Null可 省略可 説明
context BaseAudioContext 作成した新しい AudioBufferSourceNode関連付け られる BaseAudioContext です。
options AudioBufferSourceOptions この AudioBufferSourceNode のオプションの初期パラメーター値です。

1.9.2. 属性

buffer, AudioBuffer 型, nullable

再生されるオーディオのリソースを表します。

buffer 属性を設定する際は次の手順が行われます:
  1. new bufferbuffer に割り当てる AudioBuffer または null とします。

  2. もし new buffernull でなく、 [[buffer set]] が true ならば、InvalidStateError 例外を発生してこれらの手順を中止します。

  3. もし new buffernull でなければ、[[buffer set]] を true に設定します。

  4. new bufferbuffer 属性に割り当てます。

  5. もしこのノードで start() が既に呼ばれていた場合、この buffer内容の取得 処理を実行します。

detune, AudioParam 型, readonly

オーディオストリームをレンダリングする速度を変調する追加のパラメーターで、単位はセントです。このパラメーターは、playbackRate と組み合わせて computedPlaybackRate を計算する 複合パラメーター です。

loop, boolean

オーディオデータの loopStartloopEnd で指定された範囲を繰り返してループ再生するかどうかを指定します。デフォルトは false です。

loopEnd, double

loop 属性が true の場合、ループの終了位置を示すオプションの 再生ヘッド位置 です。その値そのものはループ範囲に含まれません。そのデフォルトの value は 0 で、通常は 0 から バッファの長さの範囲の任意の値に設定できます。loopEnd が 0 より小さいまたは 0 である、または loopEnd がバッファの長さよりも長い場合、ループはバッファの最後が終了位置になります。

loopStart, double

loop 属性が true の場合にループを開始するオプションの 再生ヘッド位置 です。そのデフォルトの value は 0 で、0 からバッファの長さの範囲の任意の値に設定できます。もし loopStart が 0 より小さい場合、ループは 0 から開始します。もし loopStart がバッファの長さより大きい場合、ループはバッファの最後から開始します。

playbackRate, AudioParam 型, readonly

オーディオストリームをレンダリングする速度です。これは、detune と組み合わせて computedPlaybackRate が計算される 複合パラメーター です。

1.9.3. メソッド

start(when, offset, duration)

指定の時刻に音の再生開始をスケジュールします。

メソッドが呼び出されたとき、以下の手順が実行されます:
  1. このノードで既に stop が呼び出されている場合、または既に start の呼び出しが発生している場合は、InvalidStateError 例外を発生します ( MUST )。

  2. 後述するパラメーターの制約のために発生するエラーがないか調べます。

  3. AudioBufferSourceNode を開始するため、パラメーターと共に 制御メッセージをキューに入れます

  4. 関連付けられた AudioContext制御メッセージ を送って、次の条件が満たされている場合 レンダリングスレッドで実行 します :

    1. コンテキストの 制御スレッドの状態suspended になっている。

    2. コンテキストが スタート可能 である。

    3. [[suspended by user]] フラグが false になっている。

AudioBufferSourceNode を開始するための 制御メッセージ の実行は、後述の 再生アルゴリズムhandleStart() 関数を呼び出すことを意味します。
AudioBufferSourceNode.start(when, offset, duration) メソッドの引数。
パラメーター Null可 省略可 説明
when double when パラメーターは、再生の開始時刻を ( 秒で ) 指定します。これは AudioContextcurrentTime 属性と同じ時間軸の時刻を使用します。もしこの値に 0 、あるいは currentTime よりも小さな値を渡した場合、音は即時に再生されます。もし when が負の値の場合、RangeError 例外を発生します ( MUST )。
offset double offset パラメーターは再生を開始する 再生ヘッド位置 を指定します。もしこの値に 0 が渡された場合、再生はバッファの先頭から開始されます。もし offset が負の値の場合は RangeError 例外を発生します ( MUST )。 もし offsetloopEnd より大きく、playbackRate が正か 0 で、looptrue の場合は、再生は loopEnd から始まります。 もし offsetloopStart より大きく、playbackRate が負、looptrue の場合、再生は loopStart から始まります。 offsetstartTime に到達したとき [0, duration] の範囲に暗黙的にクランプされます。ここで duration はこの AudioBufferSourceNodebuffer 属性に設定されている AudioBufferduration 属性の値です。
duration double duration パラメータは、再生される音の持続時間を表し、全体または部分的なループの反復を含む、出力されるバッファ内容全体の秒数で表します。 duration の単位は、 playbackRate の影響とは無関係です。 例えば、再生速度が 0.5 で 5 秒間の duration の場合、5 秒間分のバッファ内容が半分の速度で出力され、10 秒間の出力が生成されます。 duration が負の場合、RangeError 例外を発生します ( MUST )。
戻り値: void

1.9.4. AudioBufferSourceOptions

AudioBufferSourceNode を生成する際のオプションを指定します。すべてのメンバーは省略可能です。指定されていない場合、通常のデフォルト値がノードの生成に使用されます。

dictionary AudioBufferSourceOptions {
   AudioBuffer? buffer;
   float detune = 0;
   boolean loop = false;
   double loopEnd = 0;
   double loopStart = 0;
   float playbackRate = 1;
 };
 
1.9.4.1. ディクショナリー AudioBufferSourceOptions メンバー
buffer, AudioBuffer 型, nullable

再生するオーディオのデータを指定します。これは bufferAudioBufferSourceNodebuffer 属性に割り当てるのと等価です。

detune, float 型, デフォルトは 0

detune AudioParam の初期値です。

loop, boolean 型, デフォルトは false

loop 属性の初期値です。

loopEnd, double 型, デフォルトは 0

loopEnd 属性の初期値です。

loopStart, double 型, デフォルトは 0

loopStart 属性の初期値です。

playbackRate, float 型, デフォルトは 1

playbackRate 属性の初期値です。

1.9.5. ループ再生

このセクションは非基準情報です。基準としての要件については 再生アルゴリズム を参照してください。

loop 属性を true に設定すると、端点 loopStart および loopEnd によって定義される範囲が、一度その範囲内のどこかが再生されると、その後範囲の再生を繰り返します。loop が true である間、ループ再生は次のいずれかが発生するまで続きます:

ループの範囲は loopStart から 自身を含まない loopEnd までの領域を占めているとみなされます。 ループ範囲の再生方向は、ノードの再生速度の符号を考慮します。 再生速度が正の場合、ループは loopStart から loopEnd まで; 再生速度が負の場合は loopEnd から loopStart までのループが発生します。

ループは start()offset 引数の解釈には影響しません。再生は常に指定されたオフセットから開始され、再生中にループ範囲に差し掛かった場合にのみループが開始されます。

有効なループ開始点と終了点は、後述のアルゴリズムで定義されているように、0 から バッファの長さの間にある必要があります。loopEnd は、loopStart と同じかより後ろになるようにさらに制約されます。これらの制約のいずれかに沿わない場合は、ループ範囲はバッファ全体を指すとみなされます。

ループの端点はサブサンプルの精度で扱われます。端点が正確なサンプルフレームのオフセットにならない場合、または再生レートが 1 に等しくない場合、ループの再生は、ループの終了点と開始点が一致するように繋ぎ合わされ、それがバッファの連続した領域のオーディオであるように補間されます。

ループ関連のプロパティは、バッファの再生中に変化させても良く、一般に次のレンダリング量子から有効となります。 正確な内容については、後述の基準としての再生アルゴリズムによって定義されます。

loopStartloopEnd 属性のデフォルト値はどちらも 0 です。loopEnd の値が 0 である事はバッファ全体の長さと等価であるため、デフォルトのループ範囲はバッファ全体になります。

ループの端点の値は、バッファのサンプルレートを前提とした時間のオフセットとして表されています。これらの値は再生中に動的に変化可能なノードの playbackRate パラメーターとは無関係であることに注意してください。

1.9.6. AudioBuffer 内容の再生

この基準情報のセクションでは、再生中に動的に変化する可能性がある次の要素の組み合わせの影響を考慮しつつ、バッファ内容の再生について定義します。

AudioBufferSourceNode の出力を生成するための内部のアルゴリズムは、以下の原則に従います:

アルゴリズムの説明は次のとおりです:

let buffer; // AudioBuffer employed by this nodelet context; // AudioContext employed by this node// The following variables capture attribute and AudioParam values for the node.// They are updated on a k-rate basis, prior to each invocation of process().let loop;let detune;let loopStart;let loopEnd;let playbackRate;// Variables for the node’s playback parameterslet start = 0, offset = 0, duration = Infinity; // Set by start()let stop = Infinity; // Set by stop()// Variables for tracking node’s playback statelet bufferTime = 0, started = false, enteredLoop = false;let bufferTimeElapsed = 0;let dt = 1 / context.sampleRate;// Handle invocation of start method callfunction handleStart(when, pos, dur) {  if (arguments.length >= 1) {    start = when;  }  offset = pos;  if (arguments.length >= 3) {    duration = dur;  }}// Handle invocation of stop method callfunction handleStop(when) {  if (arguments.length >= 1) {    stop = when;  } else {    stop = context.currentTime;  }}// Interpolate a multi-channel signal value for some sample frame.// Returns an array of signal values.function playbackSignal(position) {  /*    This function provides the playback signal function for buffer, which is a    function that maps from a playhead position to a set of output signal    values, one for each output channel. If |position| corresponds to the    location of an exact sample frame in the buffer, this function returns    that frame. Otherwise, its return value is determined by a UA-supplied    algorithm that interpolates between sample frames in the neighborhood of    position.    If position is greater than or equal to loopEnd and there is no subsequent    sample frame in buffer, then interpolation should be based on the sequence    of subsequent frames beginning at loopStart.   */   ...}// Generate a single render quantum of audio to be placed// in the channel arrays defined by output. Returns an array// of |numberOfFrames| sample frames to be output.function process(numberOfFrames) {  let currentTime = context.currentTime; // context time of next rendered frame  const output = []; // accumulates rendered sample frames  // Combine the two k-rate parameters affecting playback rate  const computedPlaybackRate = playbackRate * Math.pow(2, detune / 1200);  // Determine loop endpoints as applicable  let actualLoopStart, actualLoopEnd;  if (loop && buffer != null) {    if (loopStart >= 0 && loopEnd > 0 && loopStart < loopEnd) {      actualLoopStart = loopStart;      actualLoopEnd = Math.min(loopEnd, buffer.duration);    } else {      actualLoopStart = 0;      actualLoopEnd = buffer.duration;    }  } else {    // If the loop flag is false, remove any record of the loop having been entered    enteredLoop = false;  }  // Handle null buffer case  if (buffer == null) {    stop = currentTime; // force zero output for all time  }  // Render each sample frame in the quantum  for (let index = 0; index < numberOfFrames; index++) {    // Check that currentTime and bufferTimeElapsed are    // within allowable range for playback    if (currentTime < start || currentTime >= stop || bufferTimeElapsed >= duration) {      output.push(0); // this sample frame is silent      currentTime += dt;      continue;    }    if (!started) {      // Take note that buffer has started playing and get initial      // playhead position.      if (loop && computedPlaybackRate >= 0 && offset >= actualLoopEnd) {        offset = actualLoopEnd;      }      if (computedPlaybackRate < 0 && loop && offset < actualLoopStart) {        offset = actualLoopStart;      }      bufferTime = offset;      started = true;    }    // Handle loop-related calculations    if (loop) {      // Determine if looped portion has been entered for the first time      if (!enteredLoop) {        if (offset < actualLoopEnd && bufferTime >= actualLoopStart) {          // playback began before or within loop, and playhead is          // now past loop start          enteredLoop = true;        }        if (offset >= actualLoopEnd && bufferTime < actualLoopEnd) {          // playback began after loop, and playhead is now prior          // to the loop end          enteredLoop = true;        }      }      // Wrap loop iterations as needed. Note that enteredLoop      // may become true inside the preceding conditional.      if (enteredLoop) {        while (bufferTime >= actualLoopEnd) {          bufferTime -= actualLoopEnd - actualLoopStart;        }        while (bufferTime < actualLoopStart) {          bufferTime += actualLoopEnd - actualLoopStart;        }      }    }    if (bufferTime >= 0 && bufferTime < buffer.duration) {      output.push(playbackSignal(bufferTime));    } else {      output.push(0); // past end of buffer, so output silent frame    }    bufferTime += dt * computedPlaybackRate;    bufferTimeElapsed += dt * computedPlaybackRate;    currentTime += dt;  } // End of render quantum loop  if (currentTime >= stop) {    // End playback state of this node.  No further invocations of process()    // will occur.  Schedule a change to set the number of output channels to 1.  }  return output;}

次の非基準の図は、様々な主要シナリオでのアルゴリズムの動作を示しています。バッファの動的なリサンプリングは考慮されませんが、ループ位置の時間が変更されない限り、結果の再生には重大な影響はありません。すべての図において、次の規則が適用されます:

この図は、バッファ内の最後のサンプルフレームの後にエンドポイントがある単純なループがあるバッファの基本的な再生を示しています:

AudioBufferSourceNode basic playback
AudioBufferSourceNode の基本再生

この図は、playbackRate の補間を示し、1 つおきに出力サンプルフレームが補間される、バッファコンテンツの半分の速度での再生を示しています。特に注目すべき点は、ループされた出力の最後のサンプルフレームで、ループの開始点を使用して補間されます。