AudioContext: setSinkId() メソッド
==============================

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

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

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

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

構文
--


```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 with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* SetSinkId test example
* Change the destination output device in Web Audio
* `AudioContext.sinkId`
* `sinkchange`