MediaDevices: getDisplayMedia() メソッド

構文

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 非標準 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 呼び出しに追加するために使用する呼び出し側に返されます。

仕様書

ブラウザーの互換性

関連情報

• 画面キャプチャ API
• 画面キャプチャ API の使用
• メディアキャプチャとストリーム API
• WebRTC API
• getUserMedia(): カメラやマイクからメディアをキャプチャ