스크린 캡처

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

getDisplayMedia

사용자에게 그들의 디스플레이를 실시간으로 캡처할 권한을 요청합니다.

사용자 에이전트는 최종 사용자가 매번 공유할 display surface를 모든 가능한 선택지 중에서 직접 선택하도록 허용해야 하며(MUST), options.video나 options.audio에 있는 어떠한 MediaTrackConstraints도 그 선택을 제한하는 데 사용해서는 안 됩니다(MUST NOT).

사용자 에이전트는 displaySurface 제약과 그 값을 사용하여 사용자에게 제시되는 소스 목록의 표현 방식에 영향을 줄 수는 있습니다(MAY). 그럼에도 불구하고 사용자 에이전트는 여전히 모든 display surface에 대해 사용자에게 무제한 선택권을 제공해야 합니다(MUST). 사용자 에이전트는 사용자가 모니터를 공유하는 것을 피하도록 권장하는 것이 강력히 권장됩니다. 이는 개인 정보 보호에 대한 위험을 초래할 수 있기 때문입니다.

options.video 또는 options.audio에 있는 어떠한 MediaTrackConstraints도 사용자가 선택을 마친 이후에만 사용자가 선택한 미디어에 적용되어야 합니다(MUST).

오디오의 경우, 사용자 에이전트는 최종 사용자에게 공유할 오디오 소스를 제시할 수 있습니다(MAY). 어떤 선택지가 제공되는지는 사용자 에이전트에 달려 있으며, 오디오 소스는 반드시 비디오 소스와 동일하지 않을 수 있습니다. 오디오 소스는 특정 window일 수도 있고, browser일 수도 있으며, 전체 시스템 오디오이거나 그 조합일 수도 있습니다. getUserMedia()와 달리, 오디오+비디오 요청에 대해 사용자 에이전트는 오디오 제약이 있더라도 반드시 오디오를 반환할 필요가 없습니다. 스트림 수명 동안 오디오가 전혀 공유되지 않을 것이 확실한 경우 사용자 에이전트는 결과 스트림에 오디오 트랙을 포함해서는 안 됩니다(MUST NOT). 사용자 에이전트는 오디오와 비디오 요청을 받아들일 때 비디오 트랙만 반환할 수 있고(MAY), 또는 오디오 트랙과 비디오 트랙을 모두 반환할 수 있습니다(MAY). 사용자 에이전트는 오디오 전용 요청을 거부해야 합니다(MUST).

다른 소스 세트를 사용하고 사용자 선택을 요구한다는 점 외에도, getDisplayMedia는 "granted" 권한을 영구적으로 유지할 수 없다는 점에서 getUserMedia()와도 다릅니다.

getDisplayMedia()가 호출되면, 사용자 에이전트는 다음 단계를 실행해야 합니다(MUST).

1. mediaDevices를 this로 둔다.

2. controller를 options.controller가 있으면 그 값으로, 그렇지 않으면 null로 둔다.

3. controller가 null이 아닌 경우, 다음 단계를 실행한다:

   1. controller.[[IsBound]]가 true이면, rejected된 프로미스를 반환하고, 그 이유로 DOMException 객체를 제공하며, 해당 객체의 name 속성은 InvalidStateError 여야 한다.

   2. controller.[[IsBound]]를 true로 설정한다.

4. relevant global object가 this의 경우, 해당 객체가 transient activation을 가지고 있지 않으면, rejected된 프로미스를 반환하고, 그 이유로 DOMException 객체를 제공하며, 해당 객체의 name 속성은 InvalidStateError 여야 한다.

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

6. constraints를 [options.audio, options.video]로 둔다.

7. constraints.video가 false이면, 새로 생성된 rejected된 프로미스를 반환하고 새로 생성된 TypeError를 반환한다.

8. constraints의 기존 멤버들 각각에 대해, 그 값이 사전(dictionary)인 경우 다음 단계를 실행한다:

   1. CS가 advanced 멤버를 포함하면, 새로 생성된 rejected된 프로미스를 반환하고 새로 생성된 TypeError를 반환한다.

   2. CS가 display surface에 적용 가능한 제약 가능한 속성의 이름을 멤버로 가지고 있고, 그 값이 다시 min 또는 exact 멤버를 포함하는 사전이라면, 새로 생성된 rejected된 프로미스를 반환하고 새로 생성된 TypeError를 반환한다.

   3. CS가 display surface에 적용 가능한 제약 가능한 속성의 이름을 멤버로 가지고 있고, 그 값이 다시 max 멤버를 포함하며 그 멤버의 값이 해당 제약 가능한 속성의 floor value보다 작다면, failedConstraint를 그 멤버의 이름으로 두고, message를 undefined 또는 사람이 읽을 수 있는 설명 메시지 중 하나로 두어, rejected된 프로미스를 반환하며 OverconstrainedError(failedConstraint, message)로 생성된 새 OverconstrainedError를 반환한다.

9. requestedMediaTypes를 constraints에서 사전(dictionary) 값이거나 true인 멤버들의 미디어 타입 집합으로 둔다.

10. 현재 설정 객체의 관련 전역 객체의 연결된 Document가 완전히 활성화되어 있지 않거나 포커스를 가지고 있지 않다면, 새로 생성된 rejected된 프로미스를 반환하고, 그 이유로 DOMException 객체를 제공하며, 해당 객체의 name 속성은 InvalidStateError 여야 한다.

11. 사용자 활성화를 소비한다. 이때 this의 관련 전역 객체를 사용한다.

12. p를 새 프로미스로 둔다.

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

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

       1. 타입 T의 소스가 전혀 없다면, 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 reject하여 p를 새로 생성된 DOMException 객체(그 객체의 name 속성은 NotFoundError여야 함)로 거부하고 이 단계를 중단한다.

       2. 현재 브라우징 컨텍스트에서 타입 T의 소스를 얻기 위한 권한 상태를 읽는다. 권한 상태가 "denied"이면 PermissionFailure 단계로 이동한다.

    2. 선택적으로(예: 이전에 설정된 사용자 선호, 보안상의 이유, 플랫폼 제한 등으로 인해) Permission Failure 단계로 이동할 수 있다.

    3. 사용자에게 디스플레이 장치를 선택하도록 프롬프트를 표시한다. 이때 PermissionDescriptor의 name을 "display-capture"로 설정하여 제공된 미디어 집합을 얻는다.

       제공된 미디어는 정확히 하나의 비디오 트랙을 포함해야 한다(MUST).

       제공된 미디어는 최대 하나의 오디오 트랙을 포함할 수 있다. 이 오디오 트랙은 requestedMediaTypes에 오디오가 명시되지 않았거나 해당 값이 false로 지정된 경우 포함되어서는 안 된다(MUST NOT).

       선택된 장치는 사용자에 의해 결정된 것이어야 한다(MUST). 일단 선택되면, MediaStreamTrack의 소스는 사용자가 사용자 에이전트와의 상호작용을 통해 허용하지 않는 한 변경되어서는 안 된다(MUST NOT).

       사용자 에이전트는 브라우저 창이 보이는 경우와 같이 브라우저 browser 디스플레이 장치나 monitor 디스플레이 장치의 공유를 사용자에게 경고하거나, 이러한 선택을 비권장하도록 유도하는 것이 권장된다. 이는 공유 시 훨씬 더 높은 위험을 초래하기 때문이다.

       요청 결과가 "granted"인 경우, 제공된 미디어를 공급하는 각 장치에 대해 장치를 나타내는 안정적이고 비공개적인 id인 deviceId를 사용하여 [[devicesLiveMap]][deviceId]를 true로 설정하고, 아직 true가 아니면 [[devicesAccessibleMap]][deviceId]도 true로 설정해야 한다.

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

       결과가 "denied"이면, Permission Failure 단계로 이동한다. 사용자가 응답하지 않으면 이 알고리즘은 이 단계에서 정체된다.

       사용자가 권한을 부여했지만 OS/프로그램/웹페이지 잠금 같은 하드웨어 오류로 접근할 수 없는 경우, 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 reject하여 p를 새로 생성된 DOMException 객체(그 객체의 name 속성은 NotReadableError여야 함)로 거부하고 이 단계를 중단한다.

       결과가 "granted"이지만 장치 접근이 위에 열거된 이유 외의 어떤 이유로 실패하면, 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 reject하여 p를 새로 생성된 DOMException 객체(그 객체의 name 속성은 AbortError여야 함)로 거부하고 이 단계를 중단한다.

    4. stream를 MediaStream 객체로 둔다.

    5. 사용자가 권한을 부여한 각 source에 대해 다음 단계를 실행한다:

       1. track를 source와 mediaDevices로 MediaStreamTrack 생성의 결과로 둔다.

       2. track를 stream의 트랙 집합에 추가한다.

       3. Tie track source to MediaDevices를 source와 mediaDevices로 실행한다.

    6. stream의 모든 트랙에 대해 적절한 제약을 사용하여 ApplyConstraints algorithm를 실행한다. 실패할 경우, failedConstraint를 실패한 알고리즘의 결과로 두고, message를 undefined 또는 사람이 읽을 수 있는 설명 메시지 중 하나로 둔 다음, 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 reject하여 p를 OverconstrainedError(failedConstraint, message)로 생성된 새 OverconstrainedError로 거부하고 이 단계를 중단한다.

    7. 이 getDisplayMedia() 호출은 이제 새로운 capture-session을 생성한 것으로 간주된다.

    8. 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 다음 단계를 실행한다:

       1. controller가 null이 아니면 다음 단계를 실행한다:

          1. controller.[[Source]]를 stream의 비디오 트랙의 [[Source]]로 설정한다.

          2. controller.[[DisplaySurfaceType]]를 stream의 비디오 트랙의 DisplayCaptureSurfaceType로 설정한다.

       2. last activation timestamp를 current high resolution time로 설정한다.

       3. Resolve p를 stream로 한다.

    9. controller가 null이 아니면, 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 finalize focus decision algorithm를 controller에 대해 실행한다.

    10. 이 단계들을 중단한다.

    11. Permission Failure: 작업을 큐에 넣어 사용자 상호작용 작업 소스에서 reject하여 p를 새로 생성된 DOMException 객체(그 객체의 name 속성은 NotAllowedError여야 함)로 거부한다.

14. p를 반환한다.

최상위 문서가 포커스를 잃을 때, 해당 문서와 그 중첩된 browsing contexts의 모든 CaptureController 객체에 대해 다음 단계를 실행한다:

1. [[Source]]가 undefined이면, 이 단계들을 중단한다.

2. [[FocusChangeDisabled]]를 true로 설정한다.

사용자 에이전트는 부분적으로 투명한 캡처된 display surface 뒤에 있는 내용을 캡처해서는 안 된다(MUST NOT).

새로 생성된 MediaStreamTrack에 대해, 사용자 에이전트는 프롬프트로 사용자에게 표시된 내용을 캡처해서는 안 된다(MUST NOT).

현재 화면에 렌더링되지 않은 정보는 애플리케이션이 해당 콘텐츠에 대해 명시적으로 접근 권한을 부여받지 않은 한(예: elevated permissions과 같은 수단을 통해) 캡처 시 가려져야 한다(SHOULD).

사용자 에이전트는 활성 사용자 동의(active user consent) 없이는 오디오를 공유해서는 안 된다(MUST NOT). 예를 들어, 특정 window의 비디오 캡처가 전체 시스템의 오디오 캡처(그 창과 관련 없는 애플리케이션 포함)를 동반하는 경우가 이에 해당한다.

공유 중인 디스플레이 표면은 운영체제나 사용자 에이전트의 동작으로 인해 일시적이거나 영구적으로 애플리케이션에서 접근 불가능하게 될 수 있습니다. 어떤 것이 디스플레이 표면이 접근 불가능하다고 간주되는지는 이 명세의 범위를 벗어나지만, 예시로는 모니터의 연결 해제, 창 또는 브라우저의 종료나 최소화, 또는 전화의 수신 통화 등이 포함될 MAY 있습니다.

만약 디스플레이 표면이 반드시 영구적이지는 않은 접근 불가능 상태에 들어가면, 사용자 에이전트는 작업을 큐에 넣어 해당하는 미디어 트랙의 muted 상태를 true로 설정하는 작업을 사용자 상호작용 작업 소스에서 실행해야 합니다(MUST).

만약 디스플레이 표면이 접근 불가능 상태에서 벗어나 접근 가능하게 되면, 사용자 에이전트는 작업을 큐에 넣어 해당하는 미디어 트랙의 muted 상태를 false로 설정하는 작업을 사용자 상호작용 작업 소스에서 실행해야 합니다(MUST).

만약 디스플레이 표면이 영구적인 접근 불가능 상태(예: 소스인 창의 종료)에 들어가면, 사용자 에이전트는 작업을 큐에 넣어 해당하는 미디어 트랙을 종료하는 작업을 사용자 상호작용 작업 소스에서 실행해야 합니다(MUST).

방금 getDisplayMedia에 의해 반환된 스트림은 기본적으로 음소거된 트랙들을 포함할 MAY 있습니다. 동일 스트림에 속한 오디오 및 비디오 트랙은 서로 독립적으로 음소거/음소거 해제될 MAY 있습니다.

소스 선택에 대한 제약을 수락하지 않는다는 것은 getDisplayMedia가 오디오, 비디오 또는 오디오+비디오 디스플레이 소스가 존재하는지를 노출하는 지문(fingerprinting) 표면만 제공한다는 것을 의미합니다.

참고로 displaySurface 제약을 수락해도 사용자 선택이 제한되지는 않습니다.

제약 조건은 getDisplayMedia에서 getUserMedia()와 다른 목적으로 사용된다. 제약 조건은 검색을 지원하지 않으며, 사용자가 선택한 후에만 적용된다.

이 절에서는 getDisplayMedia 트랙에 적용되는 제약 조건을 정의한다. getUserMedia()에 정의된 제약 조건은 여기에 나열되지 않은 한 적용되지 않는다.

이러한 제약 조건 중 일부는 다운스케일링과 프레임 데시메이션 같은 사용자 에이전트 처리와 디스플레이 관련 기능을 활성화한다. 다른 제약 조건은 사용자가 선택한 디스플레이 표면의 고유 속성을 기능 및 설정으로 관찰할 수 있게 한다.

다음과 같은 새로운 기존 MediaStreamTrack 제한 가능 속성은 다음 동작을 통해 사용자가 선택한 비디오 디스플레이 표면에 적용되도록 정의된다.

다음과 같은 새로운 기존 MediaStreamTrack 제한 가능 속성은 다음 동작을 통해 사용자가 선택한 오디오 소스에 적용되도록 정의된다.

사용자가 선택한 디스플레이 표면의 기반 소스가 가진 고유 속성이 변경되어, 예를 들어 최종 사용자가 캡처 중인 창의 크기를 조절함으로써 하나 이상의 제한 가능 속성의 기능 및/또는 설정이 최신 상태가 아니게 되는 경우, 사용자 에이전트는 사용자 상호작용 태스크 소스에서 다음 단계를 실행하도록 태스크를 대기열에 추가해야 한다.

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

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가 초래할 수 있는 보안 및 프라이버시 위험을 완화하기 위해 설계되었습니다.

동의 상호작용은 두 가지 형태로 설명됩니다: 사용자의 적극적인 동의와 다양한 상승된 권한입니다. 이는 비규범적 권장 사항입니다.

구현에서는 [GETUSERMEDIA]에서 권장하는 대로 카메라나 마이크를 공유할 때 제공되는 것과 유사한 사용자 피드백 및 제어 메커니즘을 제공할 것을 권장합니다.

사용자가 콘텐츠가 적극적으로 캡처되고 있을 때 콘텐츠가 공유되고 있음을 인지하는 것이 중요합니다. 사용자 에이전트는 콘텐츠가 캡처되는 동안 눈에 띄는 표시기를 표시할 것을 권장합니다. 표시기에 추가하여, 사용자 에이전트는 정확히 무엇이 공유되고 있는지 알 수 있는 수단을 제공할 것을 권장합니다. 이 기능은 애플리케이션이 캡처된 콘텐츠를 렌더링하여 쉽게 제공할 수 있지만, 이를 통해 사용자는 공유되고 있는 내용을 정확히 평가할 수 있습니다.

피드백 메커니즘 외에도 사용자가 활성 캡처를 중지할 수 있는 수단을 제공하는 것이 좋습니다.