MediaDevices: getDisplayMedia() メソッド
MediaDevices
インターフェイスの getDisplayMedia()
メソッドは、ディスプレイまたはその一部(ウィンドウなど)の内容を MediaStream
としてキャプチャする許可を選択し、許可するようユーザーに促します。
生成されたストリームは、 MediaStream 収録 API を使って記録したり、 WebRTC セッションとして送信することが可能です。
詳細および使用例については、画面キャプチャ API の使用を参照してください。
構文
getDisplayMedia()
getDisplayMedia(options)
引数
options
省略可-
オプションのオブジェクトで、返される
MediaStream
の要件を指定します。getDisplayMedia()
のオプションはMediaDevices.getUserMedia()
メソッドの constraints と同じように動作しますが、ただしaudio
およびvideo
が指定された場合のみです。getDisplayMedia()
の利用可能なオプションプロパティの一覧は次の通りです。video
省略可-
論理値または
MediaTrackConstraints
インスタンスで、既定値はtrue
です。このオプションを省略するか、true
に設定すると、ストリームに映像トラックが格納されます。true
の値は、返すMediaStream
に映像トラックが格納されることを示します。getDisplayMedia()
は映像トラックを必要とするので、このオプションをfalse
に設定すると、プロミスはTypeError
で拒否されます。 audio
省略可-
論理値または
MediaTrackConstraints
インスタンスで、既定値はfalse
です。返されるMediaStream
の値がtrue
の場合、ユーザーが選択した表示画面が音声が対応していて利用可能な場合、音声トラックが格納されることを示します。 controller
省略可-
含まれている場合、キャプチャセッションをさらに操作するために使用できるメソッドを持つ
CaptureController
オブジェクトのインスタンスです。 preferCurrentTab
Non-standard 省略可-
論理値です。
true
とすると、ブラウザーが現在のタブを最も推奨するキャプチャソースとして提供するように指示します。つまり、ユーザーに表示される「共有するものを選んでください」オプションの中に、別個の「このタブ」オプションとして表示されます。これは、一般的に多くの種類のアプリが現在のタブを共有したいだけなので有益なことです。例えば、スライドデッキアプリは、ユーザーが仮想会議にプレゼンテーションを格納する現在のタブをストリーミングできるようにすることができます。既定値は仕様書では定められていません。ブラウザー別の既定値については、ブラウザーの互換性の節を参照してください。 selfBrowserSurface
省略可-
ブラウザーが、キャプチャのためにユーザーが現在のタブを選択することを許可するかどうかを指定する列挙型値です。これは、動画会議アプリが誤って自分自身でディスプレイを共有してしまったときに経験する「無限の鏡のホール」効果を避けるために役立ちます。使用可能な値は、ブラウザーがキャプチャーの選択肢に現在のタブを含めることを指示する
include
と、除外することを指示するexclude
です。既定値は仕様書では定められていません。ブラウザー別の既定値については、ブラウザーの互換性の節を参照してください。 surfaceSwitching
省略可-
ブラウザーが、画面共有中にユーザーが共有タブを動的に切り替えるためのコントロールを表示するかどうかを指定する列挙型の値です。これは、ユーザーが共有タブを切り替えたいときに毎回共有プロセス全体を読み直すよりもずっと便利です。使用可能な値は、ブラウザーがコントロールを含めることを指示する
include
と、コントロールを表示しないことを指示するexclude
です。既定値は仕様書では定められていません。ブラウザー別の既定値については、ブラウザーの互換性の節を参照してください。 systemAudio
省略可-
ブラウザーがユーザーに提供する使用可能な音声ソースの中にシステム音声を含めるべきかどうかを指定する列挙型の値です。使用可能な値は、ブラウザーがシステム音声を選択肢のリストに含めることを指示する
include
と、除外することを指示するexclude
です。既定値は仕様書では定められていません。ブラウザー別の既定値については、ブラウザーの互換性の節を参照してください。
メモ: 能力と制約と設定の記事を見ると、これらのオプションがどのように動作するかのもっと詳細があります。
返値
Promise
で、ユーザーが選択した画面領域から来る映像トラックと、オプションの音声トラックを含む MediaStream
に解決します。
メモ: 音声トラックに対するブラウザーの対応は、メディアレコーダーが全く対応していないかどうかという点でも、対応している音声ソースという点でも、さまざまです。各ブラウザーの詳細については、互換性一覧表を確認してください。
例外
AbortError
DOMException
-
エラーまたは失敗がここに挙げた他の例外のいずれにも該当しない場合に返される。
InvalidStateError
DOMException
-
getDisplayMedia()
の呼び出しが、イベントハンドラーのようなユーザーアクションによって実行されているコードから行われなかった場合に返されます。このイベントのもう一つの原因として考えられるのは、getDisplayMedia()
が呼び出されたコンテキストのdocument
が完全にアクティブでないことです。 NotAllowedError
DOMException
-
画面領域へのアクセス許可がユーザーによって(例えば権限ポリシーで)拒否された場合、または現在の閲覧インスタンスが画面共有へのアクセスを許可されていない場合に返されます。
NotFoundError
DOMException
-
キャプチャ可能な画面映像のソースが存在しない場合に返却されます。
NotReadableError
DOMException
-
ユーザーが画面、ウィンドウ、タブ、またはその他の画面データのソースを選択したが、ハードウェアまたはオペレーティングシステムレベルのエラーまたはロックアウトが発生し、選択したソースの共有ができない場合に返されます。
OverconstrainedError
DOMException
-
ストリームを作成した後、互換性のあるストリームが生成できなかったため、指定された制約の適用に失敗した場合に返されます。
TypeError
-
指定した
options
に許可されていない値が含まれた状態でgetDisplayMedia()
を呼び出した場合、例えばvideo
プロパティを false に設定した場合、あるいは指定したMediaTrackConstraints
が許可されていない場合などに返されます。min
とexact
値は、MediaDevices.getDisplayMedia()
の呼び出しの中で使用される制約では許可されません。
セキュリティ
getDisplayMedia()
は悪用される可能性があるため、プライバシーとセキュリティに関する重大な懸念の源となり得ます。そのため、仕様書では getDisplayMedia()
を完全に対応するためにブラウザーに要求される基準を詳述しています。
- 指定されたオプションは、ユーザーが利用できるオプションを制限するために使用することはできません。代わりに、ユーザーがソースを選択した後、オプションに一致する出力を生成するために適用する必要があります。
getDisplayMedia()
を使用するための go-ahead 権限は、再利用のために永続化することはできません。ユーザーは毎回、許可を求めるプロンプトを表示しなければなりません。- 単発のユーザーにようる有効化が必要です。この機能を動作させるためには、ユーザーがページや UI 要素を操作する必要があります。
getDisplayMedia()
の呼び出しは、イベントハンドラーのようなユーザーのアクションに反応して実行されるコードから行われなければなりません。- ブラウザーは、ブラウザーを含むディスプレイやウィンドウを共有することについての警告をユーザーに提供し、他のコンテンツがキャプチャされて他のユーザーに表示される可能性があることに注意することが推奨されます。
例
以下の例では、 displayMediaOptions
引数で指定された一連のオプションを指定して画面のキャプチャを開始する startCapture()
メソッドが作成されています。このオプションは、優先するストリーム構成と、ビデオをキャプチャする表示面を指定したオブジェクトで指定されます。
async function startCapture(displayMediaOptions) {
let captureStream;
try {
captureStream =
await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
} catch (err) {
console.error(`Error: ${err}`);
}
return captureStream;
}
これは await
を使用して、 getDisplayMedia()
が MediaStream
で解決するのを非同期に待ち、指定したオプションで要求された表示コンテンツを含むストリームを生成します。ストリームは、ストリームからビデオトラックを追加するために RTCPeerConnection.addTrack()
を使用して WebRTC 呼び出しに追加するために使用する呼び出し側に返されます。
仕様書
Specification |
---|
Screen Capture # dom-mediadevices-getdisplaymedia |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- 画面キャプチャ API
- 画面キャプチャ API の使用
- メディアキャプチャとストリーム API
- WebRTC API
getUserMedia()
: カメラやマイクからメディアをキャプチャ