MediaDevices: getDisplayMedia() メソッド

MediaDevices インターフェイスの getDisplayMedia() メソッドは、ディスプレイまたはその一部（ウィンドウなど）の内容を MediaStream としてキャプチャする許可を選択し、許可するようユーザーに促します。

生成されたストリームは、 MediaStream 収録 API を使って記録したり、 WebRTC セッションとして送信することが可能です。

詳細および使用例については、画面キャプチャ API の使用を参照してください。

構文

js

getDisplayMedia()
getDisplayMedia(options)

引数

options 省略可

オプションのオブジェクトで、返される MediaStream の要件を指定します。 getDisplayMedia() のオプションは MediaDevices.getUserMedia() メソッドの constraints と同じように動作しますが、ただし audio および video が指定された場合のみです。getDisplayMedia() の利用可能なオプションプロパティの一覧は次の通りです。

video 省略可

論理値または MediaTrackConstraints (en-US) インスタンスで、既定値は true です。このオプションを省略するか、true に設定すると、ストリームに映像トラックが格納されます。true の値は、返す MediaStream に映像トラックが格納されることを示します。getDisplayMedia() は映像トラックを必要とするので、このオプションを false に設定すると、プロミスは TypeError で拒否されます。

audio 省略可

論理値または MediaTrackConstraints (en-US) インスタンスで、既定値は false です。返される MediaStream の値が true の場合、ユーザーが選択した表示画面が音声が対応していて利用可能な場合、音声トラックが格納されることを示します。

controller 省略可

含まれている場合、キャプチャセッションをさらに操作するために使用できるメソッドを持つ CaptureController (en-US) オブジェクトのインスタンスです。

preferCurrentTab 省略可

論理値です。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 (en-US) が許可されていない場合などに返されます。min と exact 値は、MediaDevices.getDisplayMedia() の呼び出しの中で使用される制約では許可されません。

セキュリティ

getDisplayMedia() は悪用される可能性があるため、プライバシーとセキュリティに関する重大な懸念の源となり得ます。そのため、仕様書では getDisplayMedia() を完全に対応するためにブラウザーに要求される基準を詳述しています。

  • 指定されたオプションは、ユーザーが利用できるオプションを制限するために使用することはできません。代わりに、ユーザーがソースを選択した後、オプションに一致する出力を生成するために適用する必要があります。
  • getDisplayMedia() を使用するための go-ahead 権限は、再利用のために永続化することはできません。ユーザーは毎回、許可を求めるプロンプトを表示しなければなりません。
  • 単発のユーザーにようる有効化が必要です。この機能を動作させるためには、ユーザーがページや UI 要素を操作する必要があります。
  • getDisplayMedia()の呼び出しは、イベントハンドラーのようなユーザーのアクションに反応して実行されるコードから行われなければなりません。
  • ブラウザーは、ブラウザーを含むディスプレイやウィンドウを共有することについての警告をユーザーに提供し、他のコンテンツがキャプチャされて他のユーザーに表示される可能性があることに注意することが推奨されます。

例

以下の例では、 displayMediaOptions 引数で指定された一連のオプションを指定して画面のキャプチャを開始する startCapture() メソッドが作成されています。このオプションは、優先するストリーム構成と、ビデオをキャプチャする表示面を指定したオブジェクトで指定されます。

js

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() (en-US) を使用して WebRTC 呼び出しに追加するために使用する呼び出し側に返されます。

仕様書

Specification
Screen Capture
# dom-mediadevices-getdisplaymedia

ブラウザーの互換性

BCD tables only load in the browser

関連情報