画面キャプチャ

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であるメンバーが含まれている場合、promiseを却下して 返す。却下理由には、新しく作成されたTypeErrorを用いる。

   2. CSに、その名前が 表示サーフェスに適用可能な制約可能なプロパティを指定するメンバーが含まれ、 さらに、その値が、次のいずれかの名前を持つメンバーを含む辞書であり、 名前がminまたはexactである場合、 promiseを却下して返す。却下理由には、新しく 作成されたTypeErrorを用いる。

   3. CSに、その名前が 表示サーフェスに適用可能な制約可能なプロパティを指定するメンバーが含まれ、 さらに、その値が、次の名前を持つメンバーを含む辞書であり、 その名前がmaxで、さらにそのメンバーの値が 制約可能なプロパティの下限値より小さい場合、 failedConstraintをそのメンバーの名前とし、 messageをundefinedまたは 人間が読める有益なメッセージのいずれかとし、promiseを 却下して返す。却下理由には、新しい OverconstrainedErrorを用いる。これは、 OverconstrainedError(failedConstraint, message)を呼び出して作成する。

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

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

11. ユーザー アクティベーションを消費する。this の 関連 グローバルオブジェクトを用いる。

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

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

    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 します。

14. p を返します。

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

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

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

ユーザーエージェントがしてはならないのは、 部分的に透明なキャプチャ対象の 表示サーフェスの背後にあるコンテンツをキャプチャすることである。

新たに作成されたMediaStreamTrackについて、 ユーザーエージェントが してはならないのは、ユーザーに表示されたプロンプトをキャプチャすることである。

現在画面にレンダリングされていない情報は、キャプチャ内で不明瞭にされるべきである。 ただし、アプリケーションがそのコンテンツにアクセスすることを明示的に 認可されている場合（たとえば、 昇格された権限などの手段を通じて）は除く。

ユーザーエージェントがしてはならないのは、音声を ユーザーの能動的な 同意なしに共有することである。たとえば、ウィンドウの映像のキャプチャに、そのウィンドウとは無関係なアプリケーションを 含むシステム全体の音声のキャプチャが伴う場合が該当する。

共有されている表示サーフェスは、一時的または 永続的にアプリケーションからアクセスできなくなる場合がある。これは、 オペレーティングシステムまたはユーザーエージェントによって行われた措置による。何をもって表示 サーフェスをアクセス不能とみなすかは、この 仕様の範囲外であるが、例として考えられるのは、モニターが 切断されること、ウィンドウまたはブラウザーが閉じられるか最小化されること、あるいは 電話への 着信である。

表示サーフェスが、必ずしも 永続的ではないアクセス不能状態になった場合、ユーザーエージェントは必ずタスクをキューに入れなければならない。このタスクが ユーザー インタラクションタスクソース上で設定するミュート状態は、 対応するメディア トラックのものであり、その値はtrueである。

表示サーフェスがアクセス不能状態を脱して アクセス可能になった場合、ユーザーエージェントは必ずタスクをキューに入れなければならない。このタスクが ユーザー インタラクションタスクソース上で設定するミュート状態は、 対応するメディアトラックのものであり、 その値はfalseである。

表示サーフェスが 永続的なアクセス不能状態（ソースウィンドウが閉じる場合など）になった場合、 ユーザーエージェントは必ずタスクをキューに入れなければならない。このタスクが ユーザー インタラクションタスクソース上で 終了させるのは、対応するメディア トラックである。

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

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

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

getDisplayMedia における制約は、 getUserMedia() における制約とは異なる目的を果たします。 制約は検出には役立たず、ユーザーが選択した後にのみ 適用されます。

この節では、 getDisplayMedia のトラックに 適用される制約を定義します。 getUserMedia() 用に定義された制約は、ここに記載されていない限り適用されません。

これらの制約の一部は、ダウンスケーリングやフレーム間引きなどの ユーザーエージェントによる処理、および表示固有の機能を有効にします。 その他の制約は、ユーザーが選択した 表示サーフェスに固有のプロパティを、 能力および設定として観察できるようにします。

次の新規および既存の MediaStreamTrack の制約可能な プロパティは、 ユーザーが選択した映像の表示サーフェスに、 次の動作で適用されるものとして定義されます。

次の新規および既存の MediaStreamTrack の制約可能な プロパティは、 ユーザーが選択した音声ソースに、次の動作で適用されるものとして 定義されます。

ユーザーが選択した表示サーフェスの基礎となるソースに固有の プロパティが、たとえばエンドユーザーがキャプチャ中のウィンドウのサイズを変更したことに 応じて変化し、その変化によって 1 つ以上の制約可能なプロパティの 能力および設定の一方または両方が古くなった場合、ユーザーエージェントは ユーザー 操作タスクソースで、次の手順を実行するタスクをキューに 入れなければなりません。

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

   これにより「過剰制約」状態が発生する場合、ユーザーエージェントは、 原因となる制約が過剰制約を生じさせている間、その制約を 無視しなければなりません。ユーザーエージェントはトラックを ミュートしてはなりません。

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"
};

WebIDLenum AudioSelectionPreferenceEnum {
  "preferred"
};

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

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]で推奨されているように、カメラやマイクを共有する際にユーザーに提供されるものと同様のフィードバックとコントロール機構を提供することが推奨されます。

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

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