뷰포트 캡처

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

getViewportMedia

사용자에게 뷰포트(현재 탭)를 실시간 캡처할 권한을 요청한다.

사용자 에이전트는 권한이 부여된 후 생성된 미디어에 제공된 options를 MUST 적용해야 한다.

오디오의 경우, 사용자 에이전트는 가능한 경우 캡처에 현재 뷰포트의 오디오를 포함하는 옵션을 최종 사용자에게 제시할 수 있다(MAY). 오디오+비디오와 관련하여 getDisplayMedia()와 마찬가지로, 사용자 에이전트는 오디오 제약이 존재하더라도 오디오를 반환하지 않을 수 있다. 사용자 에이전트가 스트림의 수명 동안 오디오가 공유되지 않을 것임을 알고 있다면, 결과 스트림에 오디오 트랙을 포함해서는 안 된다(MUST NOT). 사용자 에이전트는 오디오 및 비디오 요청을 결과 스트림에 비디오 트랙만 반환하여 수락할 수 있으며(MAY), 또는 결과 스트림에 오디오 트랙과 비디오 트랙을 모두 반환하여 수락할 수도 있다(MAY). 사용자 에이전트는 오디오 전용 요청을 거부해야 한다(MUST).

getDisplayMedia()와 마찬가지로, "granted" 권한은 영속화될 수 없다.

getViewportMedia() 메서드가 호출되면, 사용자 에이전트는 다음 단계를 실행해야 한다(MUST):

1. 현재 설정 객체의 크로스 오리진 격리 기능이 false이면, 거부된 promise를 반환한다. 이 promise는 DOMException 객체로 거부되며, 그 name 속성 값은 SecurityError이다.

2. 관련 전역 객체의 연결된 Document의 최상위 브라우징 컨텍스트의 required document policy에 Require-Document-Policy: viewport-capture 및 Document-Policy: viewport-capture가 포함되어 있지 않으면 (TODO: 올바른 알고리즘 사용), 거부된 promise를 반환한다. 이 promise는 DOMException 객체로 거부되며, 그 name 속성 값은 SecurityError이다.

3. 관련 전역 객체가 this에 대해 일시적 활성화를 가지고 있지 않으면, 거부된 promise를 반환한다. 이 promise는 DOMException 객체로 거부되며, 그 name 속성 값은 InvalidStateError이다.

4. options를 메서드의 첫 번째 인수로 둔다.

5. options.video가 false이면, 새로 생성된 TypeError로 거부된 promise를 반환한다.

6. options에서 값 CS가 딕셔너리인 각 존재하는 멤버에 대해, 다음 단계를 실행한다:

   1. CS에 advanced라는 이름의 멤버가 포함되어 있으면, 새로 생성된 TypeError로 거부된 promise를 반환한다.

   2. CS가 표시 표면에 적용 가능한 제약 가능 속성을 지정하는 이름의 멤버를 포함하고, 그 값이 다시 min 또는 exact라는 이름의 멤버를 포함하는 딕셔너리이면, 새로 생성된 TypeError로 거부된 promise를 반환한다.

   3. CS가 표시 표면에 적용 가능한 제약 가능 속성을 지정하는 이름의 멤버를 포함하고, 그 값이 다시 max라는 이름의 멤버를 포함하는 딕셔너리이며, 그 멤버의 값이 다시 그 제약 가능 속성의 floor value보다 작으면, failedConstraint를 그 멤버의 이름으로 두고, message를 undefined 또는 정보 제공용 사람이 읽을 수 있는 메시지로 둔 다음, OverconstrainedError(failedConstraint, message)를 호출하여 생성된 새 OverconstrainedError로 promise를 거부한다.

7. requestedMediaTypes를 options에서 딕셔너리 값 또는 true 값을 가진 미디어 타입의 집합으로 둔다.

8. 관련 전역 객체의 연결된 Document가 완전히 활성이 아니거나 포커스를 가지고 있지 않으면, 거부된 promise를 반환한다. 이 promise는 DOMException 객체로 거부되며, 그 name 속성 값은 InvalidStateError이다.

9. p를 새 promise로 둔다.

10. 다음 단계를 병렬로 실행한다:

    1. requestedMediaTypes의 각 미디어 타입 T에 대해,

       1. T 타입의 소스가 사용 가능하지 않으면, reject p with a new DOMException object whose name attribute has the value NotFoundError.

       2. 현재 브라우징 컨텍스트에서 T 타입의 소스를 획득하기 위한 현재 권한 상태를 읽는다. 권한 상태가 "denied"이면, 아래의 권한 실패라고 표시된 단계로 점프한다.

    2. 선택적으로, 예를 들어 이전에 설정된 사용자 선호, 보안상의 이유 또는 플랫폼 제한에 따라, 아래의 권한 실패라고 표시된 단계로 점프한다.

    3. 사용 권한 요청 을 뷰포트 캡처에 대해 수행한다. 이는 PermissionDescriptor이며, 그 name은 "viewport-capture"로 설정되고, 그 결과 제공된 미디어의 집합이 된다.

       제공된 미디어는 정확히 하나의 비디오 트랙을 포함해야 하며(MUST), 이 트랙은 관련 전역 객체의 연결된 Document의 최상위 브라우징 컨텍스트의 뷰포트의 브라우저 표시 표면에 대한 실시간 캡처여야 한다(MUST).

       제공된 미디어는 최대 하나의 오디오 트랙을 포함해야 하며(MUST), 제공되는 경우, 그 오디오 트랙은 관련 전역 객체의 연결된 Document의 최상위 브라우징 컨텍스트의 활성 문서와, 관련 전역 객체의 연결된 Document의 최상위 브라우징 컨텍스트의 중첩된 브라우징 컨텍스트들 안에 있는 모든 활성 문서의 합에 의해 생성된 결합 오디오여야 한다(MUST). 이 오디오 트랙은 requestedMediaTypes에 오디오가 지정되지 않았거나 false로 지정된 경우 포함되어서는 안 된다(MUST NOT).

       MediaStreamTrack의 소스는 변경되어서는 안 된다(MUST NOT).

       요청의 결과가 "granted"이면, 제공된 미디어를 소싱하는 각 디바이스에 대해, 그 디바이스의 안정적이고 비공개인 id인 deviceId를 사용하여, 이미 true가 아니라면 [[devicesLiveMap]][deviceId]를 true로 설정하고, 이미 true가 아니라면 [[devicesAccessibleMap]][deviceId]를 true로 설정한다.

       사용자 에이전트는 "granted" 권한 엔트리를 저장해서는 안 된다(MUST NOT).

       결과가 "denied"이면, 아래의 권한 실패라고 표시된 단계로 점프한다. 사용자가 응답하지 않으면, 이 알고리즘은 이 단계에서 멈춘다.

       사용자가 권한을 부여했지만 OS/프로그램/웹페이지 잠금과 같은 하드웨어 오류가 접근을 방해하면, p를 거부한다. 이때 새 DOMException 객체를 사용하며, 그 name 속성 값은 NotReadableError이고, 이 단계를 중단한다.

       결과가 "granted"이지만, 위에 나열된 사유가 아닌 다른 어떤 사유로 디바이스 접근이 실패하면, p를 거부한다. 이때 새 DOMException 객체를 사용하며, 그 name 속성 값은 AbortError이고, 이 단계를 중단한다.

    4. stream을 사용자가 권한을 부여한 MediaStream 객체로 둔다.

    5. 적절한 제약으로 stream의 모든 트랙에 대해 ApplyConstraints 알고리즘을 실행한다. 이것이 실패하면, failedConstraint를 실패한 알고리즘의 결과로 두고, message를 undefined 또는 정보 제공용 사람이 읽을 수 있는 메시지로 둔 다음, OverconstrainedError(failedConstraint, message)를 호출하여 생성된 새 OverconstrainedError로 p를 거부한다.

    6. videoTrack를 stream의 비디오 트랙으로 둔다.
    7. videoTrack.[[Restrictable]]을 true로 설정한다.

    8. p를 stream으로 해결하고 이 단계를 중단한다.

    9. 권한 실패: p를 새 DOMException 객체로 거부한다. 그 객체의 name 속성 값은 NotAllowedError이다.

11. p를 반환한다.

사용자 에이전트는 부분적으로 투명하게 캡처된 표시 표면 뒤의 콘텐츠를 캡처해서는 안 된다(MUST NOT).

사용자 에이전트는 캡처된 탭에서 방출된 오디오 이외의 오디오를 공유해서는 안 되며(MUST NOT), 전체 시스템의 오디오를 공유해서도 안 된다(MUST NOT).

getViewportMedia와 관련된 제약은 getDisplayMedia()와 관련된 제약뿐이며, 이는 5.4 캡처된 표시 표면을 위한 제약 가능 속성에 정의되어 있다.

뷰포트 캡처는 강력한 기능이며, 이름 "viewport-capture"으로 식별되고, 사용하려면 명시적 권한이 필요하다.

Permissions 명세와의 통합에 필요한 대로, 이 명세는 다음을 정의한다:

권한 상태 제약

이 설명자의 권한 상태에 유효한 값은 "prompt" 및 "denied"이다. 사용자 에이전트는 이 설명자의 권한 상태를 "granted"로 설정해서는 결코 안 된다(MUST NOT).

이 명세는 문자열 "viewport-capture"로 식별되는 정책 제어 기능을 정의한다. 그 기본 허용 목록은 "self"이다.