ビューポートキャプチャ

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

getViewportMedia

ビューポート（現在のタブ）をライブキャプチャする許可をユーザーに求めます。

ユーザーエージェントは、許可が 与えられた後に、指定された任意の options を生成されるメディアに MUST 適用します。

音声の場合、ユーザーエージェントは、利用可能であれば、現在のビューポートからの音声をキャプチャに含める オプションをエンドユーザーに提示しても MAY かまいません。音声+動画に関して getDisplayMedia() と同様に、 ユーザーエージェントは、音声制約が存在する場合でも音声を返さないことが許されています。 ユーザーエージェントがストリームの存続期間中に音声が共有されないことを知っている場合、結果のストリームに 音声トラックを含めては MUST NOT なりません。ユーザーエージェントは、結果のストリームに動画トラックのみを返すことで 音声および動画の要求を受け入れても MAY かまいませんし、音声トラックと動画 トラックの両方を結果のストリームに返すことで要求を受け入れても MAY かまいません。 ユーザーエージェントは、音声のみの要求を拒否しなければ MUST なりません。

getDisplayMedia() と同様に、 「granted」 許可は永続化できません。

getViewportMedia() メソッドが呼び出されたとき、ユーザーエージェントは次の 手順を実行しなければ MUST なりません。

1. current settings object の cross-origin isolated capability が false の場合、 rejected された promise を返します。その promise は、 DOMException オブジェクトで拒否され、その name 属性の値は SecurityError です。

2. relevant global object の associated Document の top-level browsing context の required document policy が Require-Document-Policy: viewport-capture および Document-Policy: viewport-capture を含まない場合（TODO: 正しいアルゴリズムを使用する）、 rejected された promise を返します。その promise は、 DOMException オブジェクトで拒否され、その name 属性の値は SecurityError です。

3. relevant global object of this が transient activation を持たない場合、promise を rejected して返します。その promise は、 DOMException オブジェクトで拒否され、その name 属性の値は InvalidStateError です。

4. options をメソッドの最初の引数とします。

5. options.video が false の場合、新しく created された TypeError で rejected された promise を返します。

6. options 内の値 CS が辞書である各 existing メンバーについて、 次の手順を実行します。

   1. CS が advanced という名前のメンバーを含む場合、新しく created された TypeError で rejected された promise を返します。

   2. CS が、 display surface に適用可能な制約可能プロパティを指定する名前のメンバーを含み、 さらにその値が min または exact という名前のメンバーを含む辞書である場合、新しく created された TypeError で promise を rejected して返します。

   3. CS が、 display surface に適用可能な制約可能プロパティを指定する名前のメンバーを含み、 さらにその値が max という名前のメンバーを含む辞書であり、そのメンバーの値が その制約可能プロパティの floor value より小さい場合、 failedConstraint をそのメンバー名とし、 message を undefined または情報提供用の人間可読メッセージのいずれかとし、新しい OverconstrainedError を OverconstrainedError(failedConstraint, message) を呼び出して作成し、それで promise を rejected して返します。

7. requestedMediaTypes を、options 内で辞書値または true の値を持つメディアタイプの集合とします。

8. relevant global object の associated Document が fully active でない、または フォーカスを持たない場合、 rejected された promise を返します。その promise は DOMException オブジェクトで拒否され、その name 属性の値は InvalidStateError です。

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

10. 次の手順を並列に実行します。

    1. requestedMediaTypes 内の各メディアタイプ T について、

       1. 型 T のソースが利用できない場合、 新しい DOMException オブジェクトで p を reject します。その name 属性の値は NotFoundError です。

       2. 現在の閲覧コンテキスト内で型 T のソースを取得するための現在の permission state を読み取ります。許可状態が「denied」 である場合、下の PermissionFailure とラベル付けされた 手順へジャンプします。

    2. 任意で、たとえば以前に確立されたユーザー設定、セキュリティ上の理由、または プラットフォームの制限に基づいて、下の Permission Failure とラベル付けされた手順へ ジャンプします。

    3. Request permission to use viewport capture を、 PermissionDescriptor の name を "viewport-capture" に設定して行い、提供されるメディアの集合を得ます。

       提供されるメディアは、正確に 1 つの動画トラックを含まなければ MUST なりません。 その動画トラックは、 viewport の browser display surface のライブキャプチャでなければ MUST なりません。この viewport は、 relevant global object の associated Document の top-level browsing context のものです。

       提供されるメディアは、最大 1 つの音声トラックを含まなければ MUST なりません。 提供される場合、その音声トラックは、 relevant global object の associated Document の top-level browsing context の active document、および relevant global object の associated Document の top-level browsing context のネストされた browsing context 内にあるすべての active documents から成る文書群によって生成される音声の合計を合成したものでなければ MUST なりません。 この音声トラックは、音声が requestedMediaTypes で指定されていない場合、または false として指定されている場合には、含めては MUST NOT なりません。

       MediaStreamTrack のソースは変更されては MUST NOT なりません。

       要求の結果が「granted」 である場合、提供されるメディアのソースとなっている各デバイスについて、そのデバイスの安定したプライベート ID deviceId を使用して、 [[devicesLiveMap]][deviceId] を、まだ true でない場合は true に設定し、[[devicesAccessibleMap]][deviceId] を、 まだ true でない場合は true に設定します。

       ユーザーエージェントは、「granted」 許可エントリを保存しては MUST NOT なりません。

       結果が「denied」 である場合、下の Permission Failure とラベル付けされた手順へジャンプします。ユーザーが応答しない場合、このアルゴリズムは この手順で停止します。

       ユーザーが許可を与えたものの、OS、プログラム、または Web ページのロックのようなハードウェアエラーにより アクセスが妨げられる場合、 p を新しい DOMException オブジェクトで reject します。その name 属性の値は NotReadableError であり、これらの手順を中止します。

       結果が「granted」 であるものの、上記に列挙されたもの以外の理由でデバイスアクセスに失敗した場合、 p を新しい DOMException オブジェクトで reject します。その name 属性の値は AbortError であり、これらの手順を中止します。

    4. stream を、ユーザーが許可を与えた MediaStream オブジェクトとします。

    5. stream 内のすべてのトラックに対し、適切な制約を用いて ApplyConstraints algorithm を実行します。これが失敗した場合、failedConstraint を失敗したアルゴリズムの結果とし、 message を undefined または情報提供用の 人間可読メッセージのいずれかとし、 OverconstrainedError(failedConstraint, message) を呼び出して作成した新しい OverconstrainedError で p を reject します。

    6. videoTrack を stream 内の動画トラックとします。
    7. videoTrack.[[Restrictable]] を true に設定します。

    8. p を stream で Resolve し、これらの手順を中止します。

    9. Permission Failure: p を新しい DOMException オブジェクトで Reject します。その name 属性の値は NotAllowedError です。

11. p を返します。

ユーザーエージェントは、 部分的に透明なキャプチャ対象の display surface の背後にあるコンテンツをキャプチャしては MUST NOT なりません。

ユーザーエージェントは、 キャプチャされたタブから発せられる音声以外の音声を共有しては MUST NOT ならず、システム全体の音声を共有しても MUST NOT なりません。

getViewportMedia に関連する制約は、 getDisplayMedia() に関連するもののみです。これは 5.4 キャプチャされたディスプレイサーフェスの制約可能プロパティ で定義されています。

Viewport Capture は、 "viewport-capture" という name によって識別される powerful feature であり、 使用するには express permission が必要です。

Permissions 仕様との統合に必要とされるように、この 仕様は次を定義します。

permission state constraints

この記述子の permission state の有効な値は、 「prompt」 および 「denied」です。 ユーザーエージェントは、この記述子の permission state を 「granted」 に設定しては決して MUST NOT なりません。

この仕様は、文字列 "viewport-capture" によって識別される policy-controlled feature を定義します。 その default allowlist は "self" です。