DOM 요소에서 미디어 캡처

비규범으로 표시된 섹션뿐 아니라, 이 명세의 모든 저작 지침, 도표, 예제 및 참고는 비규범입니다. 이 명세의 그 밖의 모든 것은 규범입니다.

이 문서의 핵심 단어 MUST 및 MUST NOT은 여기에 표시된 것처럼 모두 대문자로 나타날 때, 그리고 그 경우에만 BCP 14 [RFC2119] [RFC8174]에 설명된 대로 해석되어야 합니다.

이 명세는 단일 제품, 즉 이 명세에 포함된 인터페이스를 구현하는 사용자 에이전트에 적용되는 적합성 기준을 정의합니다.

이 명세에서 정의된 API를 구현하기 위해 ECMAScript를 사용하는 구현은 Web IDL 명세 [WEBIDL]에 정의된 ECMAScript 바인딩과 일관되는 방식으로 이를 구현해야 합니다. 이 명세가 해당 명세와 그 용어를 사용하기 때문입니다.

captureStream 메서드가 HTML [HTML5] 미디어 요소에 추가됩니다. 캡처를 위한 메서드는 HTMLMediaElement와 HTMLCanvasElement 모두에 추가됩니다.

MediaStream과 HTMLMediaElement 모두 track이라는 개념을 노출합니다. HTMLMediaElement에 사용되는 공통 타입이 없기 때문에, 이 문서는 VideoTrack 또는 AudioTrack을 가리키기 위해 track이라는 용어를 사용합니다. MediaStreamTrack은 MediaStream의 미디어를 식별하는 데 사용됩니다.

WebIDLpartial interface HTMLMediaElement {
    MediaStream captureStream ();
};

captureStream

captureStream() 메서드는 미디어 요소에 렌더링되는 미디어의 실시간 캡처를 생성합니다.

캡처된 MediaStream은 미디어 요소에서 선택된 (VideoTrack 또는 그 밖의 배타적으로 선택되는 track 타입의 경우) 또는 활성화된 (AudioTrack 또는 다중 선택을 지원하는 그 밖의 track 타입의 경우) track 집합의 콘텐츠를 렌더링하는 MediaStreamTrack들로 구성됩니다. 미디어 요소에 특정 타입의 선택되거나 활성화된 track이 없으면, 캡처된 스트림에는 해당 타입의 MediaStreamTrack이 존재하지 않습니다.

따라서 video 요소는 비디오 MediaStreamTrack 및 임의 개수의 오디오 MediaStreamTrack을 캡처할 수 있습니다. audio 요소는 임의 개수의 오디오 MediaStreamTrack을 캡처할 수 있습니다. 두 경우 모두, 캡처된 MediaStreamTrack 집합은 비어 있을 수 있습니다.

특정 타입의 선택되거나 활성화된 track이 존재하기 전까지는, 해당 타입의 MediaStreamTrack이 캡처된 스트림에 존재하지 않습니다. 특히, 미디어 요소에 소스가 할당되어 있지 않으면, 캡처된 MediaStream에는 트랙이 없습니다. 결과적으로 준비 상태가 HAVE_NOTHING인 미디어 요소는 캡처된 MediaStreamTrack 인스턴스를 생성하지 않습니다. 메타데이터를 사용할 수 있게 되고 선택되거나 활성화된 track들이 결정되면, 새로운 캡처된 MediaStreamTrack 인스턴스가 생성되어 MediaStream에 추가됩니다.

캡처된 MediaStreamTrack은 종료됩니다. 이는 재생이 종료되고 (ended 이벤트가 발생하고), 또는 해당 트랙이 캡처하는 track이 더 이상 재생을 위해 선택되거나 활성화되지 않을 때입니다. 미디어 요소의 src 또는 srcObject 속성을 설정하여 소스가 변경되면, track은 더 이상 선택되거나 활성화되지 않습니다.

캡처된 MediaStreamTrack의 집합은 미디어 요소의 소스가 변경되면 변경됩니다. 미디어 요소의 소스가 종료되면 다른 소스가 선택됩니다.

미디어 요소의 선택된 VideoTrack 또는 활성화된 AudioTrack이 변경되면, 이전에 선택되거나 활성화되지 않았던 각 track에 대해 새로운 MediaStreamTrack을 포함하는 addtrack 이벤트가 생성됩니다. 그리고 선택되거나 활성화된 상태를 중단하는 각 track에 대해 removetrack 이벤트가 생성됩니다. MediaStreamTrack은 MediaStream에서 제거되기 전에 MUST 종료되어야 합니다.

MediaStreamTrack은 한 번만 종료될 수 있으므로, 활성화되었다가 비활성화되고 다시 활성화된 트랙은 두 개의 별도 트랙으로 캡처됩니다. 마찬가지로, 재생이 종료된 뒤 재생을 다시 시작하면 새로운 캡처된 MediaStreamTrack 인스턴스 집합이 생성됩니다. 재생 중 탐색은 트랙 선택을 변경하지 않는 한 이벤트를 생성하거나 캡처된 MediaStreamTrack을 종료시키지 않습니다.

캡처된 MediaStream을 구성하는 MediaStreamTrack들은 자신이 캡처하는 트랙의 상태 변화에 따라 음소거되거나 음소거 해제됩니다. 언제든지, 미디어 요소는 다양한 이유로 특정 트랙에서 캡처할 수 있는 활성 콘텐츠를 갖지 않을 수 있습니다.

미디어 재생이 일시 정지되어 있을 수 있습니다.
track은 현재 재생 시간이 해당 트랙의 콘텐츠가 시작되기 전이거나 콘텐츠가 종료된 뒤인 경우, 현재 재생 시간에 대한 콘텐츠를 갖지 않을 수 있습니다.
소스 역할을 하는 MediaStreamTrack은 muted 또는 disabled될 수 있습니다.
track의 콘텐츠는 교차 출처 보호로 인해 현재 출처에서 접근할 수 없게 될 수 있습니다. 예를 들어, HTTP URL에서 렌더링된 콘텐츠는 부분 콘텐츠 요청에서 리디렉션의 대상이 될 수 있고, 활성화되거나 선택된 트랙이 교차 출처 콘텐츠를 포함하도록 변경될 수 있습니다.

콘텐츠의 부재는 캡처된 트랙에서 muted 속성을 통해 반영됩니다. 캡처된 MediaStreamTrack은 이에 대응하는 소스 track에 사용 가능하고 접근 가능한 콘텐츠가 없으면 muted 속성이 true로 설정되어 MUST 합니다. 콘텐츠 가용성이 변경되면 mute 이벤트가 MediaStreamTrack에서 발생합니다.

음소거된 캡처가 결과적으로 어떤 출력을 생성하는지는 미디어 타입에 따라 달라집니다. VideoTrack은 음소거되면 새 프레임 캡처를 중단하여, 캡처된 스트림이 마지막으로 캡처된 프레임을 표시하게 합니다. 음소거된 AudioTrack은 무음을 생성합니다.

미디어 요소가 콘텐츠를 실제로 렌더링하고 있는지(예: 화면 또는 오디오 장치로)는 캡처된 스트림의 콘텐츠에 영향을 주지 않습니다. 미디어 요소에서 오디오를 음소거해도 캡처가 무음을 생성하게 하지 않으며, 미디어 요소를 숨겨도 캡처된 비디오가 중지되지 않습니다. 마찬가지로, 미디어 요소의 오디오 레벨 또는 볼륨은 캡처된 오디오의 볼륨에 영향을 주지 않습니다.

유효 재생률이 1.0이 아닌 요소에서 캡처된 오디오는 MUST 시간 신축되어야 합니다. 재생할 수 없는 재생률은 캡처된 오디오 트랙을 음소거 상태로 만듭니다.

captureStream 메서드가 HTML [HTML5] canvas 요소에 추가됩니다. 그 결과 생성되는 CanvasCaptureMediaStreamTrack은 캔버스에서 프레임이 샘플링되는 시점을 제어할 수 있는 메서드를 제공합니다.

WebIDLpartial interface HTMLCanvasElement {
    MediaStream captureStream (optional double frameRequestRate);
};

captureStream

captureStream() 메서드는 캔버스 표면의 실시간 비디오 캡처를 생성합니다. 그 결과 생성되는 미디어 스트림은 캔버스 요소의 크기와 일치하는 단일 비디오 CanvasCaptureMediaStreamTrack을 갖습니다.

origin-clean이 아닌 캔버스의 콘텐츠는 캡처되어서는 MUST NOT 합니다. 캔버스가 origin-clean이 아니면 이 메서드는 SecurityError 예외를 던집니다.

캡처된 스트림은 captureStream()으로 생성된 뒤 소스 캔버스의 origin-clean 플래그가 false가 되면 콘텐츠 캡처를 즉시 중단해야 MUST 합니다. 캔버스가 이 상태로 남아 있는 동안, 캡처된 MediaStreamTrack은 muted가 되어 새 콘텐츠를 생성하지 않아야 MUST 합니다.

캔버스를 캡처하는 각 트랙은 [[frameCaptureRequested]] 내부 슬롯을 가지며, 이 슬롯은 캔버스에서 새 프레임이 요청될 때 true로 설정됩니다.

새 트랙이 생성될 때 모든 새 트랙의 [[frameCaptureRequested]] 값은 true로 설정됩니다. 특정한 0이 아닌 frameRequestRate로 캡처된 트랙이 생성되면, 사용자 에이전트는 1/frameRequestRate 초 간격의 주기적 타이머를 시작합니다. 타이머가 활성화될 때마다 [[frameCaptureRequested]]가 true로 설정됩니다.

requestFrame() 메서드로 프레임 캡처를 수동 제어하는 것을 지원하기 위해, 브라우저는 frameRequestRate에 대해 0 값을 지원해야 MUST 합니다. 그러나 캡처된 스트림은 frameRequestRate가 0이더라도 생성될 때 프레임 캡처를 요청해야 MUST 합니다.

frameRequestRate가 음수이면 이 메서드는 NotSupportedError 예외를 던집니다.

[[frameCaptureRequested]]가 true이고 캔버스가 그려질 때 캔버스에서 새 프레임이 요청됩니다. 캡처되는 캔버스가 그려질 때마다 다음 단계가 실행됩니다.

캔버스에서 캡처하는 각 track에 대해 다음 단계를 실행합니다.
1. 캔버스가 마지막으로 그려진 뒤 새 콘텐츠가 캔버스에 그려졌고, track의 [[frameCaptureRequested]] 내부 슬롯이 설정되어 있으면, 캔버스에 그려진 내용을 포함하는 새 프레임을 track에 추가합니다.
2. frameRequestRate 값이 지정된 경우, track의 [[frameCaptureRequested]] 내부 슬롯을 false로 설정합니다.

캔버스에 그려진 내용을 포함하는 새 프레임을 track에 추가할 때, 캔버스가 완전히 불투명하지 않으면 캔버스의 알파 채널 콘텐츠를 캡처하고 보존해야 합니다. 이 track의 소비자는 알파 채널을 보존하지 않을 수 있습니다.

참고

이 알고리즘의 결과, 캔버스에서 무언가 변경되기 전까지는 캡처된 트랙이 시작되지 않습니다.

매개변수	타입	Nullable	Optional	설명
frameRequestRate	`double`	✘	✔

반환 타입: MediaStream

CanvasCaptureMediaStreamTrack은 MediaStreamTrack의 확장이며, 단일 requestFrame() 메서드를 제공합니다. 미디어 스트림으로의 콘텐츠 렌더링을 정밀하게 제어해야 하는 애플리케이션은 이 메서드를 사용하여 캔버스의 프레임이 캡처되는 시점을 제어할 수 있습니다.

WebIDL[Exposed=Window] interface CanvasCaptureMediaStreamTrack : MediaStreamTrack {
    readonly        attribute HTMLCanvasElement canvas;
    undefined requestFrame ();
};

canvas of type HTMLCanvasElement, readonly: 이 미디어 스트림이 캡처하는 캔버스 요소입니다.

requestFrame: requestFrame() 메서드는 애플리케이션이 캔버스의 프레임이 캡처되어 트랙으로 렌더링되도록 수동으로 요청할 수 있게 합니다. 애플리케이션이 캔버스에 점진적으로 렌더링하는 경우, 이를 통해 애플리케이션은 부분적으로 렌더링된 프레임의 캡처를 피할 수 있습니다.

참고

현재 지정된 대로라면, 캔버스가 origin-clean이 아닌 경우에도 SecurityError 또는 다른 오류 피드백이 발생하지 않습니다. 이는 부분적으로 프레임 요청이 어디에서 오는지를 추적하지 않기 때문입니다. 이를 강조하고 싶은가요?

매개변수 없음.

반환 타입: undefined

미디어 요소는 미디어 요소의 출처와 다른 출처의 미디어 리소스를 렌더링할 수 있습니다. 이러한 경우, 결과로 생성되는 MediaStreamTrack의 콘텐츠는 문서 출처의 접근으로부터 보호되어야 MUST 합니다.

이 보호가 나타나는 방식은 콘텐츠가 접근되는 방법에 따라 달라집니다. 예를 들어, 접근할 수 없는 비디오를 canvas 요소 [HTML]에 렌더링하면 캔버스의 origin-clean 플래그가 false가 됩니다. Web Audio MediaStreamAudioSourceNode [WEBAUDIO]를 만들려고 하면 성공하지만, 문서 출처에는 아무 정보도 생성하지 않습니다(즉, 오디오 컨텍스트에는 무음만 전달됩니다). WebRTC [WEBRTC]를 사용하여 미디어를 전송하려고 하면 아무 정보도 전송되지 않습니다.

미디어 요소가 렌더링하는 미디어의 출처는 언제든지 변경될 수 있습니다. 이는 단일 미디어 리소스의 경우에도 마찬가지입니다. 사용자 에이전트는 미디어 출처의 변경이 교차 출처 콘텐츠의 노출로 이어지지 않도록 보장해야 MUST 합니다.

이 섹션은 공개 전에 제거됩니다.

[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[HTML5]: HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[mediacapture-streams]: Media Capture and Streams. Cullen Jennings; Bernard Aboba; Jan-Ivar Bruaroey; Henrik Boström; youenn fablet. W3C. 19 December 2024. CRD. URL: https://www.w3.org/TR/mediacapture-streams/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[streamproc]: MediaStream Processing API. Robert O'Callahan. W3C. 31 May 2012. W3C Working Group Note. URL: https://www.w3.org/TR/streamproc/
[WEBAUDIO]: Web Audio API. Paul Adenot; Hongchan Choi. W3C. 17 June 2021. W3C Recommendation. URL: https://www.w3.org/TR/webaudio-1.0/
[WEBIDL]: Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/
[WEBRTC]: WebRTC: Real-Time Communication in Browsers. Cullen Jennings; Jan-Ivar Bruaroey; Henrik Boström; Florent Castelli. W3C. 8 October 2024. W3C Recommendation. URL: https://www.w3.org/TR/webrtc/

[GETUSERMEDIA]: Media Capture and Streams. Cullen Jennings; Bernard Aboba; Jan-Ivar Bruaroey; Henrik Boström; youenn fablet. W3C. 19 December 2024. CRD. URL: https://www.w3.org/TR/mediacapture-streams/

DOM 요소에서 미디어 캡처

초록

이 문서의 상태

1. 소개

2. 적합성

3. HTML 미디어 요소 미디어 캡처 확장

메서드

4. HTML Canvas 요소 미디어 캡처 확장

메서드

4.1 `CanvasCaptureMediaStreamTrack`

속성

메서드

5. 보안 고려 사항

6. 변경 로그

6.1 2015-tbd-tbd 이후 변경 사항

A. 감사의 말

B. 참고 문헌

B.1 규범 참고 문헌

B.2 정보 참고 문헌

DOM 요소에서 미디어 캡처

초록

이 문서의 상태

1. 소개

2. 적합성

3. HTML 미디어 요소 미디어 캡처 확장

메서드

4. HTML Canvas 요소 미디어 캡처 확장

메서드

4.1 CanvasCaptureMediaStreamTrack

속성

메서드

5. 보안 고려 사항

6. 변경 로그

6.1 2015-tbd-tbd 이후 변경 사항

A. 감사의 말

B. 참고 문헌

B.1 규범 참고 문헌

B.2 정보 참고 문헌

4.1 `CanvasCaptureMediaStreamTrack`