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` 
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` (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 with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

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