MediaDevices: selectAudioOutput() メソッド
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
MediaDevices
の selectAudioOutput()
は、ユーザーに特定の音声出力機器、例えばスピーカーやヘッドフォンを選択するよう尋ねます。
成功すると、返される Promise
は選択された機器を記述した MediaDeviceInfo
で解決されます。
構文
selectAudioOutput()
selectAudioOutput(options)
引数
options
省略可-
ユーザーへの問い合わせで提供される機器を構成するオブジェクトです。
deviceId
省略可-
プロンプトに表示する(唯一の)機器の ID を表す文字列(既定値は "")。
メモ: ユーザーエージェントは、指定された NULL ではない ID が以前のセッションで
selectAudioOutput()
によってユーザーに公開されていた場合、ユーザーへのプロンプトをスキップすることを選択することができます。 この場合、ユーザーエージェントは単にこの機器 ID で解決するか、同じ機器の新しい ID が変更されている場合は、それを使用することができます。これは、永続化された機器 ID を使用したいアプリケーションのためのものです。 この ID は
setSinkId()
で動作する前にselectAudioOutput()
で正常に渡されなければなりません。
返値
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=
仕様書
Specification |
---|
Audio Output Devices API # dom-mediadevices-selectaudiooutput |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- WebRTC - この API の紹介ページ