MediaDevices: selectAudioOutput() メソッド

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

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

selectAudioOutput()MediaDevices インターフェイスのメソッドで、ユーザーに特定の音声出力機器、例えばスピーカーやヘッドフォンを選択するよう尋ねます。ユーザーが機器を選択すると、そのメソッドはユーザーに選択した機器を音声出力シンクとして使用するその権限を付与します。

選んだ後、その機器が利用できる場合は、MediaDevices.enumerateDevices()を使用して列挙し、HTMLMediaElement.setSinkId()を使用して音声出力シンクとして設定することができます。

成功すると、返される Promise は選択された機器を記述した MediaDeviceInfo で解決されます。

構文

js
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 へのアクセスは、以下の制約を受けることになります。

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

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

js
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}`);
    });
});

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

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

仕様書

Specification
Audio Output Devices API
# dom-mediadevices-selectaudiooutput

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
selectAudioOutput
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.

関連情報