画面キャプチャ

WebIDLpartial interface MediaDevices {
  Promise<MediaStream> getDisplayMedia(optional DisplayMediaStreamOptions options = {});
};

getDisplayMedia

ユーザーに対して表示のライブキャプチャの許可を求めます。

ユーザーエージェントは、エンドユーザーが毎回利用可能な選択肢の中から共有する表示面を選べるようにしなければならず（MUST）、options.video や options.audio に含まれるいかなる MediaTrackConstraints を用いてその選択を制限してはなりません（MUST NOT）。

ユーザーエージェントは、displaySurface 制約の存在およびその値を、ユーザーに提示するソースの表示に影響させることができます（MAY）。それでもユーザーエージェントは依然として任意の表示面を無制限に選択できるように提供しなければなりません（MUST）。ユーザーエージェントは、モニターの共有はリスクが高いためユーザーが選択しないよう促すことが強く推奨されます。

options.video や options.audio に含まれるいかなる MediaTrackConstraints も、ユーザーが選択を行った後にのみユーザーが選択したメディアへ適用されなければなりません（MUST）。

音声に関しては、ユーザーエージェントはエンドユーザーに共有するオーディオソースを提示してもよい（MAY）ものとします。どの選択肢を提示するかはユーザーエージェント次第であり、提示される音声ソースが必ずしもビデオソースと同一であるとは限りません。オーディオソースは特定のウィンドウ、ブラウザー、システム全体のオーディオ、あるいはそれらの組み合わせであり得ます。オーディオとビデオの両方を要求した場合でも、ユーザーエージェントはオーディオを返さないことが許されています。生涯にわたってオーディオが共有されないことが確実であるとユーザーエージェントが判断した場合、それは結果のストリームにオーディオトラックを含めてはなりません（MUST NOT）。ユーザーエージェントは、オーディオとビデオの要求に対してビデオトラックのみを返すか（MAY）、オーディオトラックとビデオトラックの両方を返すことができます（MAY）。ただし、オーディオのみの要求は拒否されなければなりません（MUST）。

getDisplayMedia は、異なるソース集合からメディアを取得しユーザー選択を要求する点に加え、getUserMedia() と異なり、"granted" の権限を永続化することはできません。

getDisplayMedia() が呼び出されると、ユーザーエージェントは次の手順を実行しなければなりません（MUST）：

1. mediaDevices をこの操作の this とします。

2. controller を options.controller が存在すればそれに、存在しなければ null にします。

3. もし controller が null でない場合、次の手順を実行します：

   1. もし controller.[[IsBound]] が true であれば、reject された promise を、DOMException オブジェクト（そのname 属性が InvalidStateError の値を持つ）で返して終了します。

   2. controller.[[IsBound]] を true に設定します。

4. もしこの操作の relevant global object が transient activation を持たない場合、reject された promise を、DOMException オブジェクト（そのname 属性が InvalidStateError の値を持つ）で返して終了します。

5. このメソッドの第一引数を options とします。

6. constraints を [options.audio, options.video] とします。

7. もし constraints.video が false であれば、新たに作成された reject された promise を、作成された TypeError で返します。

8. constraints の中で値 CS が辞書である既存の各メンバーについて、次の手順を実行します：

   1. もし CS が advanced というメンバーを含むなら、新たに作成された 作成された TypeError で拒否された promise を返します。

   2. もし CS が表示面に適用可能な制約可能プロパティを指定する名前のメンバーを含み、その値がさらに min または exact というメンバーを含む辞書であるなら、新たに作成された 作成された TypeError で拒否された promise を返します。

   3. もし CS が表示面に適用可能な制約可能プロパティを指定する名前のメンバーを含み、その値がさらに max というメンバーを含み、そのメンバーの値が制約可能プロパティの floor value 未満であるなら、failedConstraint をそのメンバー名とし、message を undefined か説明的な人間可読のメッセージのいずれかとし、OverconstrainedError(failedConstraint, message) によって作成された新しいエラーで拒否された promise を返します。

9. requestedMediaTypes を、constraints のうち辞書値または true の値を持つメディア型の集合とします。

10. もしこの操作の current settings object の relevant global object に関連付けられた Document が完全にアクティブでない（fully active でない）か、フォーカスを持っていない（have focus でない）場合、reject された promise を、DOMException オブジェクト（そのname 属性が InvalidStateError の値を持つ）で返して終了します。

11. p を新しい promise とします。

12. 次の手順を並列で実行します：

    1. requestedMediaTypes の各メディア型 T について、

       1. もし型 T のソースが存在しない場合、ユーザーインタラクションタスクソースに対してタスクをキューし、p を新しい DOMException（そのname 属性が NotFoundError の値を持つ）で reject し、これらの手順を中止します。

       2. 現在の閲覧コンテキストで型 T のソースを取得するための権限状態を読み取ります。もし権限状態が "denied" であれば、下のラベル 許可失敗 にジャンプします。

    2. 任意で、例えば事前に確立されたユーザープリファレンス、セキュリティ上の理由、あるいはプラットフォームの制約に基づいて、下のラベル 許可失敗 にジャンプしてもよい。

    3. ユーザーに表示デバイスを選択させるよう 促し、その結果として提供されるメディアの集合を得ます。これは PermissionDescriptor の name が "display-capture" に設定されたものとして扱います。

       提供されるメディアは正確に1つのビデオトラックを含まなければなりません（MUST）。

       提供されるメディアは最大で1つのオーディオトラックを含むことができます。このオーディオトラックは、requestedMediaTypes に音声が指定されていなかった場合、あるいはそれが false と指定されていた場合は含めてはなりません（MUST NOT）。

       選択されたデバイスはユーザーによって決定されたものでなければなりません（MUST）。一度選択されたら、ユーザーがユーザーエージェントとの相互作用を通じて許可しない限り、MediaStreamTrack のソースは変更してはなりません（MUST NOT）。

       ユーザーエージェントは、ブラウザーのウィンドウが可視であるブラウザー表示デバイスや、その他共有時に著しくリスクが高いと考えられるモニター表示デバイスの共有をユーザーに警告すること、またはそれらの選択を抑制しようとすることを推奨します。

       もし要求の結果が "granted" であれば、提供されたメディアのソースとなっている各デバイスについて、デバイスの安定かつプライベートな識別子である deviceId を用いて [[devicesLiveMap]][deviceId] を true に、もしまだ true でなければ [[devicesAccessibleMap]][deviceId] を true に設定します。

       ユーザーエージェントは "granted" の権限エントリを保存してはなりません（MUST NOT）。

       もし結果が "denied" であれば、下のラベル 許可失敗 にジャンプします。ユーザーが応答しない場合、このアルゴリズムはこのステップで停止します。

       ユーザーが許可したが、OS/プログラム/ウェブページのロック等のハードウェアエラーによりアクセスできない場合は、ユーザーインタラクションタスクソースにタスクをキューして p を新しい DOMException（そのname 属性が NotReadableError の値を持つ）で reject し、これらの手順を中止します。

       もし結果が "granted" であるにもかかわらず、上記以外の理由でデバイスアクセスが失敗した場合は、ユーザーインタラクションタスクソースにタスクをキューして p を新しい DOMException（そのname 属性が AbortError の値を持つ）で reject し、これらの手順を中止します。

    4. stream を MediaStream オブジェクトとします。

    5. ユーザーが許可した各 source について、次の手順を実行します：

       1. track を source と mediaDevices を用いて MediaStreamTrack を作成 した結果とします。

       2. track を stream のトラック集合に追加します。

       3. Tie track source to MediaDevices を source と mediaDevices で実行します。

    6. 適切な制約を用いて stream の全てのトラックに対して ApplyConstraints アルゴリズム を実行します。これが失敗した場合、失敗した結果を failedConstraint に、人間が読める説明を message にそれぞれ設定し、ユーザーインタラクションタスクソースにタスクをキューして p を OverconstrainedError(failedConstraint, message) で拒否し、これらの手順を中止します。

    7. この getDisplayMedia() の呼び出しは、現在新しい キャプチャセッション を生成したものと見なされます。

    8. ユーザーインタラクションタスクソースにタスクをキューして、次の手順を実行します：

       1. もし controller が null でない場合、次の手順を実行します：

          1. controller.[[Source]] を stream のビデオトラックの [[Source]] に設定します。

          2. controller.[[DisplaySurfaceType]] を、stream のビデオトラックの DisplayCaptureSurfaceType に設定します。

       2. last activation timestamp を現在の高解像度時刻に設定します。

       3. Resolve p を stream で完了させます。

    9. もし controller が null でない場合、ユーザーインタラクションタスクソースにタスクをキューして controller に対して finalize focus decision algorithm を実行します。

    10. これらの手順を中止します。

    11. 許可失敗: ユーザーインタラクションタスクソースにタスクをキューして、p を新しい DOMException（そのname 属性が NotAllowedError の値を持つ）で reject します。

13. p を返します。

トップレベルのドキュメントがフォーカスを失ったとき、そのドキュメント内およびネストされた閲覧コンテキストのドキュメントにあるすべての CaptureController オブジェクトに対して次の手順を実行します：

1. もし [[Source]] が undefined であれば、これらの手順を中止します。

2. [[FocusChangeDisabled]] を true に設定します。

ユーザーエージェントは、部分的に透明なキャプチャされた 表示面 の背後にあるコンテンツをキャプチャしてはなりません（MUST NOT）。

新しく作成された MediaStreamTrack について、ユーザーエージェントはプロンプトとしてユーザーに表示した内容をキャプチャしてはなりません（MUST NOT）。

現在スクリーンにレンダリングされていない情報は、アプリケーションが明示的にそのコンテンツへアクセスする許可を得ていない限り（例：昇格された権限 のような手段で）、キャプチャでは隠蔽されるべきです（SHOULD）。

ユーザーエージェントは、アクティブなユーザーの同意（例：active user consent）なしにオーディオを共有してはなりません（MUST NOT）。例えば、あるウィンドウのビデオをキャプチャする際にシステム全体のオーディオ（そのウィンドウに無関係なアプリケーションを含む）を同時にキャプチャするような場合が該当します。

共有されている 表示面 は、オペレーティングシステムやユーザーエージェントによる操作により、アプリケーションから一時的または永久にアクセスできなくなることがあります。どのような状態が 表示面 をアクセス不能とみなすかは本仕様の範囲外ですが、例としては MAY モニターが切断される、ウィンドウ や ブラウザ が閉じられるまたは最小化される、あるいは電話の着信による場合などがあります。

表示面が必ずしも永続的ではないアクセス不能状態に入ると、ユーザーエージェント MUST タスクをキューに登録 し、 ユーザー相互作用タスクソース 上で、その対応するメディアトラックのミュート状態を true に設定するように 操作します。

表示面がアクセス不能状態を抜けて再びアクセス可能になると、ユーザーエージェント MUST タスクをキューに登録 し、 ユーザー相互作用タスクソース 上で、その対応するメディアトラックのミュート状態を false に設定するように 操作します。

表示面が永続的なアクセス不能状態（例えばソースの ウィンドウ の閉鎖）の状態に入ると、ユーザーエージェント MUST タスクをキューに登録 し、 ユーザー相互作用タスクソース 上で、その対応するメディアトラックを 終了 させなければなりません。

直前に getDisplayMedia によって返されたストリームは、デフォルトでミュートされているトラックを含むことが MAY あります。 同じストリームに属するオーディオトラックとビデオトラックは、互いに独立してミュート／ミュート解除される MAY あります。

ソース選択のための制約を受け付けないということは、getDisplayMedia が音声、映像、または音声と映像の表示ソースが存在するかどうかを公開するフィンガープリンティングの側面のみを提供することを意味します。

displaySurface 制約を受け入れても、ユーザーの選択を制限するものではない点に注意してください。

制約は、getDisplayMedia においては、 getUserMedia() とは異なる目的を持ちます。 それらは探索を助けるものではなく、ユーザー選択の後にのみ適用されます。

このセクションは、getDisplayMedia のトラックに どの制約が適用されるかを定義します；ここに記載されていない getUserMedia() 用に定義された制約は適用されません。

これらの制約のいくつかは、ダウンスケーリングやフレーム間引きなどのユーザーエージェントによる処理や、表示固有の機能を可能にします。その他は、ユーザーが選択した display surface の固有の特性を、機能や設定として観測可能にします。

以下の新規および既存の MediaStreamTrack の Constrainable Properties は、ユーザーが選択したビデオの display surface に適用され、以下の動作を持ちます：

以下の新規および既存の MediaStreamTrack の Constrainable Properties は、ユーザーが選択したオーディオソースに適用され、以下の動作を持ちます：

ユーザーが選択した display surface の基になるソースの固有のプロパティが変化する場合（例えばエンドユーザーがキャプチャされたウィンドウのサイズを変更した場合）や、これらの変化が一つ以上の制約可能プロパティの能力や設定を古くさせる場合、ユーザーエージェントは MUST タスクをキューに登録 して ユーザー相互作用タスクソース 上で次の手順を実行する必要があります：

1. 影響を受けるすべての制約可能プロパティを同時に更新します。

   これが「過度の制約（overconstrained）」状況を引き起こす場合、ユーザーエージェントはその過度に制約している制約を、その過度の制約が続く限り無視しなければなりません。ユーザーエージェントはトラックをミュートしてはなりません。

WebIDLenum CaptureStartFocusBehavior {
  "focus-capturing-application",
  "focus-captured-surface",
  "no-focus-change"
};

WebIDL[Exposed=Window, SecureContext]
interface CaptureController : EventTarget {
  constructor();
  undefined setFocusBehavior(CaptureStartFocusBehavior focusBehavior);
};

WebIDLenum SelfCapturePreferenceEnum {
  "include",
  "exclude"
};

WebIDLenum SystemAudioPreferenceEnum {
  "include",
  "exclude"
};

WebIDLenum WindowAudioPreferenceEnum {
  "system",
  "window",
  "exclude"
};

WebIDLenum SurfaceSwitchingPreferenceEnum {
  "include",
  "exclude"
};

WebIDLenum MonitorTypeSurfacesEnum {
  "include",
  "exclude"
};

WebIDLdictionary DisplayMediaStreamOptions {
  (boolean or MediaTrackConstraints) video = true;
  (boolean or MediaTrackConstraints) audio = false;
  CaptureController controller;
  SelfCapturePreferenceEnum selfBrowserSurface;
  SystemAudioPreferenceEnum systemAudio;
  WindowAudioPreferenceEnum windowAudio;
  SurfaceSwitchingPreferenceEnum surfaceSwitching;
  MonitorTypeSurfacesEnum monitorTypeSurfaces;
};

WebIDLpartial dictionary MediaTrackSupportedConstraints {
  boolean displaySurface = true;
  boolean logicalSurface = true;
  boolean cursor = true;
  boolean restrictOwnAudio = true;
  boolean suppressLocalAudioPlayback = true;
};

WebIDLpartial dictionary MediaTrackConstraintSet {
  ConstrainDOMString displaySurface;
  ConstrainBoolean logicalSurface;
  ConstrainDOMString cursor;
  ConstrainBoolean restrictOwnAudio;
  ConstrainBoolean suppressLocalAudioPlayback;
};

WebIDLpartial dictionary MediaTrackSettings {
  DOMString displaySurface;
  boolean logicalSurface;
  DOMString cursor;
  boolean restrictOwnAudio;
  boolean suppressLocalAudioPlayback;
  double screenPixelRatio;
};

WebIDLpartial dictionary MediaTrackCapabilities {
  DOMString displaySurface;
  boolean logicalSurface;
  sequence<DOMString> cursor;
};

WebIDLenum DisplayCaptureSurfaceType {
  "monitor",
  "window",
  "browser"
};

WebIDLenum CursorCaptureConstraint {
  "never",
  "always",
  "motion"
};

キャプチャの潜在的なソースは、このAPIによって個別のメディアソースとして扱われます。しかし、表示キャプチャソースは、ホストシステムに関する過剰な情報を明らかにするため、enumerateDevices() によって列挙されてはなりません。

したがって、表示キャプチャソースは、その deviceId が公開されていないため、deviceId 制約を使用して選択することはできません。

論理的表示面のキャプチャは、ユーザーが意識していないコンテンツが共有される可能性を引き起こします。論理的表示面は、ユーザーが公開する意図がなかった情報をレンダリングする可能性があります。この情報が目に見える場合にはより容易に認識できます。このような手段は機械に対しては効果が薄いですが、人間の受信者は一瞬だけ表示されるコンテンツを処理する能力が低いです。

現在画面にレンダリングされていない情報は、昇格された権限を通じてそのコンテンツにアクセスすることが明示的に許可されていない限り、キャプチャで隠されるよう推奨されます。

論理的表示面の隠された領域がどのようにして可視的表示面のキャプチャを生成するかは、異なる場合があります。プレゼンテーションソフトウェアのようなアプリケーションは、隠された部分が隠される前に表示されていた画像をレンダリングすることで利益を得る可能性があります。画像を固定すると、変化するコンテンツに視覚的なアーティファクトを引き起こすか、コンテンツが隠されていることを隠す可能性があります。キャプチャの固定部分はバグと誤解されることがあります。代わりに、隠された領域は灰色やハッチングなどで隠されていることを示すコンテンツに置き換えられる場合があります。

一部のシステムでは、論理的表示面のみをキャプチャする場合があります。小さな画面を持つデバイスなどは、通常ウィンドウの概念を持たず、全画面モードでのみアプリケーションをレンダリングします。これらのシステムは、現在表示されていないアプリケーションのキャプチャを提供する可能性がありますが、論理的表示面をキャプチャしないと使用できない場合があります。

ウィンドウやその他の表示面をキャプチャする際に、部分的に透明な場合、その背後にあるコンテンツはキャプチャされません。

ユーザープロンプトが新しく作成されたMediaStreamTrackによって短時間ウェブページに公開されるリスクがあります。例えば、ユーザーがユーザープロンプトが表示されている画面を選択した場合です。ユーザープロンプトが選択可能なさまざまな表示面のプレビューを表示する場合、これらのプレビューは新しく作成されたMediaStreamTrackによってキャプチャされません。

この文書は、ユーザーの同意を確認するために使用されるメカニズムに追加の制限を設けることを推奨します。これらの制限は、APIがもたらすセキュリティおよびプライバシーリスクを軽減することを目的としています。

2つの同意の形式が説明されています：アクティブなユーザーの同意と、さまざまな昇格された権限です。これらは規範的ではなく、推奨事項のみです。

実装では、[GETUSERMEDIA]で推奨されているように、カメラやマイクを共有する際にユーザーに提供されるものと同様のフィードバックとコントロール機構を提供することが推奨されます。

コンテンツがアクティブにキャプチャされているとき、ユーザーがコンテンツが共有されていることを認識することが重要です。ユーザーエージェントは、コンテンツがキャプチャされている間、目立つインジケーターを表示することが推奨されます。インジケーターに加えて、ユーザーエージェントが、正確に何が共有されているかを確認する手段を提供することが推奨されます。この機能は、キャプチャされたコンテンツをレンダリングすることでアプリケーションが簡単に提供できるものですが、ユーザーが共有されている内容を正確に評価することを可能にします。

フィードバック機構に加えて、ユーザーがアクティブなキャプチャを停止する手段を提供することが推奨されます。