AudioContext: setSinkId() メソッド
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
setSinkId()
は AudioContext
インターフェイスのメソッドで、AudioContext
の音声出力機器を設定します。sink ID が明示的に設定されていない場合は、既定のシステム音声出力機器が使われます。
音声機器を既定でない機器に設定するには、開発者は音声機器にアクセスする許可を得る必要があります。必要な場合、MediaDevices.getUserMedia()
を呼ぶことによりユーザーに必要な許可を求めるプロンプトを表示することができます。
さらに、この機能は speaker-selection
権限ポリシー によりブロックされる場合があります。
構文
setSinkId(sinkId)
引数
sinkId
-
出力音声機器として設定する機器のシンク ID です。以下の型のいずれかです。
- 文字列
-
シンク ID を表す文字列です。たとえば、
MediaDevices.enumerateDevices()
が返すMediaDeviceInfo
オブジェクトのdeviceId
プロパティで取得できます。 AudioSinkOptions
-
シンク ID の様々なオプションを表すオブジェクトです。現在、これは 1 個のプロパティ
type
を取り、その値はnone
です。この値を設定すると、音声を音声出力機器で再生せずに処理させることができます。これは、処理と並行して再生する必要がないときにエネルギーの消費を最小化するのに有用なオプションです。
返値
undefined
の値で解決する Promise
を返します。
シンク ID を既存の値(すなわち、AudioContext.sinkId
が返す値)に設定しようとすると、エラーは発生しませんが、処理がすぐに停止します。
例外
InvalidAccessError
DOMException
-
選択された音声出力機器へのアクセスに失敗したとき発生します。
NotAllowedError
DOMException
-
ブラウザーに音声機器にアクセスする許可がないとき発生します。
NotFoundError
DOMException
-
渡された
sinkId
がシステムで検出されたどの音声機器にも一致しないとき発生します。
例
SetSinkId test example (ソースコードを見る) では、AudioBufferSourceNode
により 3 秒間のホワイトノイズを生成し、GainNode
に通して少し音量を下げる音声グラフを作成します。
さらに、音声出力機器をその場で変えることができるドロップダウンメニューを用意します。そのために、
-
ドロップダウンメニューに配置するボタンを用意します。まず、
MediaDevices.getUserMedia()
を呼び、機器を列挙するために必要な許可を得るためのプロンプトを開きます。次に、MediaDevices.enumerateDevices()
を用いてすべての利用可能な機器を取得します。ループにより、各機器を<select>
要素の選択肢として利用可能にします。さらに、音声をどの出力でも再生したくないときのために選択肢「None」を作成します。jsmediaDeviceBtn.addEventListener('click', async () => { if ("setSinkId" in AudioContext.prototype) { selectDiv.innerHTML = ''; const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); const devices = await navigator.mediaDevices.enumerateDevices(); // 簡潔にするため、ドロップダウン作成のためのほとんどの DOM 関係のスクリプトは省略 const audioOutputs = devices.filter( (device) => device.kind === 'audiooutput' && device.deviceId !== 'default' ); audioOutputs.forEach((device) => { const option = document.createElement('option') option.value = device.deviceId; option.textContent = device.label; select.appendChild(option); }); const option = document.createElement('option') option.value = 'none'; option.textContent = 'None'; select.appendChild(option); //...
-
<select>
要素にchange
イベントリスナーを追加し、新しい値が選択された時にシンク ID を変更して音声出力機器を変更できるようにします。ドロップダウンで「None」が選択された場合は{ type : 'none' }
オブジェクトを引数としてsetSinkId()
を呼ぶことにより音声機器が選択されていない状態にし、それ以外の場合は<select>
要素のvalue
属性に格納された音声機器 ID を引数として呼びます。js// ... select.addEventListener('change', async () => { if(select.value === 'none') { await audioCtx.setSinkId({ type : 'none' }); } else { await audioCtx.setSinkId(select.value); } }) } });
出力機器の変更は音声の再生中にも、再生前にも、再生と再生の間にもできます。
仕様書
Specification |
---|
Web Audio API # dom-audiocontext-setsinkid |
ブラウザーの互換性
BCD tables only load in the browser