Web Audio API

Web audio の概念と利用方法

Web Audio API は音声操作をオーディオコンテキスト内の操作として実現し、モジュラールーティングできるようにデザインされています。基本的な操作は オーディオノードとして表現されています。これを接続することで、オーディオグラフを作成します。 チャンネル構成の異なる複数の音源も 1 つのコンテキスト内で扱えます。この構成によって、複雑で動的な音声操作を実現できるようになっています。

Audio nodes are linked into chains and simple webs by their inputs and outputs. They typically start with one or more sources. ソースはごく短時間に(毎秒数万程度)音の強度の配列を提供します。 ソースはOscillatorNode などで数学的に計算されるか、 AudioBufferSourceNode やMediaElementAudioSourceNode のような音声/動画ファイルや、 オーディオストリーム(MediaStreamAudioSourceNode) から来ます。実際、音声ファイルは要するにマイクであるとか電子的に生成された音の強度の記録なのであり、最終的に単一の複雑な波へとミックスされるわけです。

ノードの出力は他のノードの入力に紐付けられます。つまり、入力ストリームにミックスや編集をして他へ出力できるわけです。一般的な編集の例としては音量の変更です( GainNode )。意図した効果を十分に施したあと、ユーザーに音声を聞かせたい場合、サウンドをスピーカーやヘッドオンに流すために、 AudioContext.destination の入力に紐付ける必要があります。

簡潔で通常のWeb Audioの使い方は次のようになります:

1. オーディオコンテキストを作成する
2. コンテキストの中で、<audio>,オシレーター,ストリームなどのソースを作成する
3. リバーブ・フィルター・パンナー・コンプレッサーなどのエフェクトノードを作成する
4. 最終的な音声の到達先を選ぶ(例えばスピーカー)
5. ソースをエフェクトに繋げ、エフェクトを到達先(destination)に繋げる

タイミングは高精度で低遅延に制御されます。正確にイベントに反応したり特定の音声サンプルにアクセスしたりすることができます。ドラムマシンやシーケンサーのようなアプリケーションを作ることができます。

Web Audio API は立体音響も扱えます。 source-listener モデル に基づいたシステムを利用し、パンニングモデルをコントロールできます。また距離に基づく音の減衰や、ドップラー効果(ソースや観測者の移動)も扱えます。

Web Audio APIがターゲットとする人

Web Audio APIは音声技術に馴染みがない人にとって、怖気づくかもしれません。また、多くの機能があるため、開発者にとってとっつきにくいものになっています。

Web Audio APIの用途としては、futurelibrary.noのような雰囲気作りのためやフォームの検証に音を活用するために、単に音声をWebサイトに組み込むために使用できます。一方で、高度な対話型ツールの作成にも利用できます。こうしたことを踏まえると、開発者とミュージシャンの双方に適していると言えます。

プログラミングは得意だけどAPIの構造と用語の解説が必要な人のために、簡単なチュートリアルがあります。

また、Web Audio APIの背景にある基本理念に関する記事もあり、特にこのAPIの範囲でデジタルオーディオがどのように動作するのかを理解するのに役立ちます。またAPIの基礎となる優れた概念の紹介も含んでいます。

プログラムを書く作業はカードゲームに例えられます。ルールを学んで遊んでみて、またルールを学んで再び遊んでみて・・・。したがって最初のチュートリアルと記事を見たあとにピンとこなかった場合、最初のチュートリアルを拡張して、学んだことを実践して、段階的に高度なことを学んでいく発展的なチュートリアルがあります。

それとは別に、このAPIのすべての機能を網羅したチュートリアルとリファレンスを用意しています。このページのサイドバーを参照して下さい。

音楽的な側面に精通し、音楽理論の概念に精通し、楽器の構築を開始したい場合は、発展的チュートリアルやその他の解説を基に制作に移る事ができるでしょう(上記のリンク付きチュートリアルでは、スケジューリングに関する注意事項、オーダーメイドの発振器やエンベロープの作成、LFOなどについて説明しています) 。

プログラミングの基本に慣れていない場合は、まず初級者向けのJavaScriptチュートリアルを参照してから、このページに戻ってください。初級者向けのJavaScript学習モジュールを参照してください。

Web Audio API インタフェース

Web Audio API は全部で28のインタフェースと関連するイベントを持ちます。それらは機能的に9個のカテゴリに分けられます。

一般的なオーディオグラフの定義

Web Audio API で利用するオーディオグラフのコンテナと、その構成要素は以下の通りです。

AudioContext

音声モジュールを組み合わせて作成される、音声処理のグラフを表します。グラフ内の各モジュールは AudioNode として表現されています。オーディオコンテキストは、コンテキスト内での処理を担当するノードの作成を行います。

AudioContextOptions

AudioContextOptions は AudioContext を作成するときにオプションを渡したいときに使用します。

AudioNode

AudioNode インタフェースは音声処理のモジュールの表現しています。これには<audio>要素や<video> 要素のような音源、音声の出力先、BiquadFilterNode や GainNode) のようなフィルタなどが含まれます。

AudioParam

AudioParam インタフェースは AudioNode の持つような、音声に関するパラメータを表現しています。値をセットするだけでなく、差分を指定することも可能です。また指定した時間やパターンで、値を変更をすることもできます。

AudioParamMap

AudioParam のマップのようなインターフェイスを提供します。つまり forEach()、get()、 has()、 keys()、 values()メソッドや size プロパティが使えます。

BaseAudioContext

BaseAudioContext インターフェイスはオンライン音声処理グラフ( AudioContext)やオフライン音声処理グラフ( OfflineAudioContext)の基底となるものです。直接 BaseAudioContext を使うことはなく、これを継承するこれら2つのインターフェイスを介して使用します。

ended (event)

ended イベントは、再生が終了した際に発火するイベントです。

音源

Web Audio API 内で利用できる音源は以下の通りです。

AudioScheduledSourceNode

AudioScheduledSourceNode は AudioNode の一種で、いくつかの音源ノードの親インターフェイスです。

OscillatorNode

OscillatorNode はサイン波を出力する AudioNode です。出力する波形の周波数を指定できます。

AudioBuffer

 AudioBuffer はメモリ上に展開された短い音声データを表します。 AudioContext.createBuffer() によって音声ファイルから、もしくはAudioContext.createBuffer() メソッドによって生データから作成されます。このデータは AudioBufferSourceNode を利用して再生されます。

AudioBufferSourceNode

AudioBufferSourceNode は AudioNode の一種で、メモリ上の音声データを利用した音源です。音声データ自身は AudioBuffer として保存されています。

MediaElementAudioSourceNode

MediaElementAudioSourceNode は AudioNode の一種で、<audio> 要素や <video> 要素を利用する音源です。

MediaStreamAudioSourceNode

MediaStreamAudioSourceNode は AudioNode の一種で、マイクやWebカメラといった WebRTC MediaStream からの入力を扱える音源です。複数の音声トラックがストリーム上にある場合、 id は辞書順(アルファベット順)です。

MediaStreamTrackAudioSourceNode

MediaStreamTrackAudioSourceNodeはAudioNode の一種で、 MediaStreamTrack からの入力を扱える音源です。 createMediaStreamTrackSource() メソッドによって作られたノードの場合、使用するトラックを指定してください。 MediaStreamAudioSourceNode 以上の制御を提供します。

オーディオエフェクトフィルター

これらを利用すると、音源からの音声にエフェクトをかけられます。

BiquadFilterNode

BiquadFilterNode は AudioNode の一種で、単純な低次フィルタです。フィルタやトーンコントロール、グラフィックイコライザで利用されます。BiquadFilterNode の入力と出力はともに 1 つです。

ConvolverNode

ConvolverNode はAudioNode の一種で、Audiobuffer に対して線形畳み込みを行います。リバーブの実現に利用されます。

DelayNode

DelayNode は AudioNode の一種で、delay-line を表します。入力された音声を、遅らせて出力します。

DynamicsCompressorNode

DynamicsCompressorNode はコンプレッサとして働きます。大きな音の音量を絞ることで、複数の音を同時に再生した時に起きがちな、音のクリッピングや歪みを回避します。

GainNode

GainNode は AudioNode の一種で、入力された音の音量を指定されたものに変更して出力します。

WaveShaperNode

WaveShaperNode は AudioNode の一種で、非線形のディストーションエフェクトを実現します。curve 属性に指定された関数を用いて、入力を歪ませます。音を歪ませ、温かみを与えるために用いられます。

PeriodicWaveNode

OscillatorNode の出力の波形を変えるために用いられます。

IIRFilterNode

一般的な無限インパルス応答(IIR)フィルターの実装です。トーン制御デバイスやグラフィックイコライザーの実装に利用できます。

音声の出力先

処理した音声の出力先を、以下のもので定めます。

AudioDestinationNode

AudioDestinationNode はコンテキスト内での出力先を表します。通常はスピーカとなっています。

MediaStreamAudioDestinationNode

MediaElementAudioSourceNode は音声の出力先となる AudioNode の一種で、WebRTC MediaStream と1 つの AudioMediaStreamTrack から構成されます。Navigator.getUserMedia で取得された MediaStream と同様に扱えます。

分析と可視化

音声の時間領域 / 周波数領域分析には、AnalyserNode を利用します。

AnalyserNode

AnalyserNode を利用すると、音声のリアルタイムに時間領域分析と周波数領域分析が行えます。これを利用すると、音声の可視化が行えます。

オーディオチャンネルの分岐と合成

オーディオチャンネルを分岐したり合成したりするのにこれらのインターフェースを使います。

ChannelSplitterNode

The ChannelSplitterNode はオーディオソースの複数のチャンネルを別々のモノラル出力へ分離します。

ChannelMergerNode

ChannelMergerNode は異なるモノラルの入力を、1 つの出力へとまとめます。それぞれの入力は、出力内のチャンネルとなります。

立体音響

以下を利用すると、立体音響を実現できます。

AudioListener

AudioListener は聴者の向きと位置を表します。

PannerNode

PannerNode は AudioNode の一種で、空間内での音の振る舞いを規定します。位置はカルテシアンの右手座標系で表され、速度ベクトルで動きを表します。向きはコーンの向きで表現します。

StereoPannerNode

StereoPannerNode インターフェイスは単純なステレオプランナーで、音声ストリームのパン(左右バランス)を調整できます。

JavaScript による音声処理

音声Workletを使うことで、JavaScriptやWebAssemblyを使って自作のAudioNodeを定義できます。音声Workletは Worklet インターフェイスという軽量版 Worker インターフェイスを実装しています。 Chrome 66 以降で既定で有効です。

AudioWorklet

AudioWorklet インターフェイスは BaseAudioContext.audioWorklet を介して利用でき、新たなモジュールを音声Workletに追加できます。

AudioWorkletNode

AudioWorkletNode インターフェイスは AudioNode の一種で、音声グラフに組み込んだり、対応する AudioWorkletProcessor にメッセージを送信できます。

AudioWorkletProcessor

AudioWorkletProcessor インターフェイスは AudioWorkletGlobalScope で実行する音声処理コードで、音声の生成・処理・分析を直接行ったり、対応する AudioWorkletNode にメッセージを送信できます。

AudioWorkletGlobalScope

AudioWorkletGlobalScope インターフェイスは WorkletGlobalScope から派生するオブジェクトで、音声処理スクリプトが実行されるワーカーコンテキストを表現します。WorkletスレッドでJavaScriptを用いて音声の生成・処理・分析を直接行えるよう設計されています。

廃止: script processor nodes

音声Workletが定義されるよりも昔、 Web Audio API はJavaScriptを使用する音声処理に ScriptProcessorNode  を利用していました。しかしながら処理がメインスレッドで走るためにパフォーマンスが良くありませんでした。歴史的な理由から ScriptProcessorNode  は維持されていますが非推奨であり、将来の規格から取り除かれる予定です。

ScriptProcessorNode

ScriptProcessorNode を利用すると、JavaScript から音声データの生成、処理、分析を行えます。このノードは AudioNode の一種で、入力と出力の二つのバッファとリンクしています。入力バッファに新しいデータがセットされる度に AudioProcessingEvent インタフェースを実装したイベントが生起します。イベントハンドラは出力バッファにデータをセットして処理を終了します。

audioprocess (event)

audioprocess イベントは ScriptProcessorNode の処理が可能になった際に発火します。

AudioProcessingEvent

AudioProcessingEvent は ScriptProcessorNode の入力バッファが処理可能になったことを表すイベントです。

オフライン / バックグラウンドでの処理

以下を利用すると、音声を出力することなく処理できます。

OfflineAudioContext

OfflineAudioContext は AudioContext の一種で、AudioNode を組み合わせて、音声処理を行うグラフを表現しています。通常の AudioContext と異なり、OfflineAudioContext は音声を出力せず、バッファ内で高速に処理を行います。

complete (event)

complete イベントは OfflineAudioContext の処理が終了した時に発火します。

OfflineAudioCompletionEvent

OfflineAudioCompletionEvent は OfflineAudioContext の処理が終了したことを表します。complete イベントは、これを実装しています。

廃止されたインタフェース

以下のものは、 Web Audio API の古い仕様には存在しましたが、現在は廃止され、別のものに置き換えられています。

JavaScriptNode

JavaScript で音声を直接処理できます。廃止され、 ScriptProcessorNode に置き換えられています。

WaveTableNode

定期的な波形変換を行います。廃止され PeriodicWaveNode に置き換えられています。

例

GitHubの webaudio-example に多数の例が掲載されています。

仕様

ブラウザ互換性

関連情報

Tutorials/guides

• Basic concepts behind Web Audio API
• Using the Web Audio API
• Advanced techniques: creating sound, sequencing, timing, scheduling
• Autoplay guide for media and Web Audio APIs
• Using IIR filters
• Visualizations with Web Audio API
• Web audio spatialisation basics
• Controlling multiple parameters with ConstantSourceNode
• Mixing Positional Audio and WebGL
• Developing Game Audio with the Web Audio API
• Porting webkitAudioContext code to standards based AudioContext

Libraries

• Tones: a simple library for playing specific tones/notes using the Web Audio API.
• Tone.js: a framework for creating interactive music in the browser.
• howler.js: a JS audio library that defaults to Web Audio API and falls back to HTML5 Audio, as well as providing other useful features.
• Mooog: jQuery-style chaining of AudioNodes, mixer-style sends/returns, and more.
• XSound: Web Audio API Library for Synthesizer, Effects, Visualization, Recording ... etc
• OpenLang: HTML5 video language lab web application using the Web Audio API to record and combine video and audio from different sources into a single file (source on GitHub)
• Pts.js: Simplifies web audio visualization (guide)

Related topics

• Web media technologies
• Guide to media types and formats on the web