AudioContext: setSinkId() メソッド

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

setSinkId() は AudioContext インターフェイスのメソッドで、AudioContext の音声出力機器を設定します。sink ID が明示的に設定されていない場合は、既定のシステム音声出力機器が使われます。

音声機器を既定でない機器に設定するには、開発者は音声機器にアクセスする許可を得る必要があります。必要な場合、MediaDevices.getUserMedia() を呼ぶことによりユーザーに必要な許可を求めるプロンプトを表示することができます。

さらに、この機能は speaker-selection 権限ポリシー によりブロックされる場合があります。

構文

js
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 に通して少し音量を下げる音声グラフを作成します。

さらに、音声出力機器をその場で変えることができるドロップダウンメニューを用意します。そのために、

  1. ドロップダウンメニューに配置するボタンを用意します。まず、MediaDevices.getUserMedia() を呼び、機器を列挙するために必要な許可を得るためのプロンプトを開きます。次に、MediaDevices.enumerateDevices() を用いてすべての利用可能な機器を取得します。ループにより、各機器を <select> 要素の選択肢として利用可能にします。さらに、音声をどの出力でも再生したくないときのために選択肢「None」を作成します。

    js
    mediaDeviceBtn.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);

    //...

  2. <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

関連情報