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