構文

selectAudioOutput()
selectAudioOutput(options)

引数

options 省略可

ユーザーへの問い合わせで提供される機器を構成するオブジェクトです。

deviceId 省略可

以前に公開された/許可された単一の機器の ID を 表す文字列です。 設定しない場合は、利用できるオーディオ出力機器がすべて表示されます。

このオプションは、同じ機器を将来のセッションで既定で使用できるように、機器 ID を保存したいというアプリケーションのためのものです。 同じ機器に対して新しいIDが返される場合があることに注意してください。また、永続的な ID は、それが selectAudioOutput() で正常に渡された後でなければ、setSinkId() で使用することができません。

メモ: ユーザーエージェントは、指定された NULL ではない ID が以前のセッションで selectAudioOutput() によってユーザーに公開されていた場合、ユーザーへのプロンプトをスキップすることを選択することができます。 この場合、ユーザーエージェントは単にこの機器 ID で解決するか、同じ機器の新しい ID が変更されている場合は、それを使用することができます。 以前指定した機器にその権限が与えられていたものの、その後取り消された場合、ユーザーエージェントは許可された機器をすべて表示し、指定された ID を持つ端末をハイライト表示することがあります。

返値

Promiseで、 MediaDeviceInfo オブジェクトで履行されます。このオブジェクトは、ユーザーが選択した音声出力機器を記述します。

例外

NotAllowedError DOMException

現在のページに speaker-selection 権限ポリシーが与えられていない場合、またはユーザーが機器を選択せずに選択プロンプトを閉じた場合に返されます。

NotFoundError DOMException

利用可能な音声出力機器がない場合に返されます。

InvalidStateError DOMException

一時的な有効化が発生していない場合に返されます（何らかの UI イベントから起動する必要があります）。

セキュリティ要件

API へのアクセスは、以下の制約を受けることになります。

• このメソッドは保護されたコンテキストで呼び出す必要があります。
• 一時的なユーザーによる有効化が必要です。 この機能が機能するためには、ユーザーがページや UI 要素を操作する必要があります。
• アクセスは HTTP の speaker-selection 権限ポリシーで制限される可能性があります。

権限の状態は、権限 API の navigator.permissions.query() メソッドで、 speaker-selection 権限の権限記述子を使用することで、確認することができます。

例

こちらは、ボタンクリックにより起動される関数の中で selectAudioOutput() を使用する例です。 これは、選択された機器 ID とラベル（もしあれば）またはエラーメッセージを出力しています。

document.querySelector("#myButton").addEventListener("click", () => {
  if (!navigator.mediaDevices.selectAudioOutput) {
    console.log("selectAudioOutput() not supported.");
    return;
  }

  // 選択した機器やエラーをプロンプト表示しログ出力する
  navigator.mediaDevices
    .selectAudioOutput()
    .then((device) => {
      console.log(`${device.kind}: ${device.label} id = ${device.deviceId}`);
    })
    .catch((err) => {
      console.error(`${err.name}: ${err.message}`);
    });
});

出力を選択すると、このような結果が出るかもしれません。

audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

仕様書

ブラウザーの互換性

関連情報

• HTMLMediaElement.setSinkId()
• HTMLMediaElement.sinkId
• WebRTC - この API の紹介ページ