3.1 Methods

captureStream

The captureStream() method produces a real-time capture of the media that is rendered to the media element.

The captured MediaStream comprises of MediaStreamTracks that render the content from the set of selected (for VideoTrack s, or other exclusively selected track types) or enabled (for AudioTrack s, or other track types that support multiple selections) tracks from the media element. If the media element does not have a selected or enabled tracks of a given type, then no MediaStreamTrack of that type is present in the captured stream.

A <video> element can therefore capture a video MediaStreamTrack and any number of audio MediaStreamTracks. An <audio> element can capture any number of audio MediaStreamTracks. In both cases, the set of captured MediaStreamTracks could be empty.

Unless and until there is a track of given type that is selected or enabled, no MediaStreamTrack of that type is present in the captured stream. In particular, if the media element does not have a source assigned, then the captured MediaStream has no tracks. Consequently, a media element with a ready state of HAVE_NOTHING produces no captured MediaStreamTrack instances. Once metadata is available and the selected or enabled tracks are determined, new captured MediaStreamTrack instances are created and added to the MediaStream.

A captured MediaStreamTrack ends when playback ends (and the ended event fires) or when the track that it captures is no longer selected or enabled for playback. A track is no longer selected or enabled if the source is changed by setting the src or srcObject attributes of the media element.

The set of captured MediaStreamTracks change if the source of the media element changes. If the source for the media element ends, a different source is selected.

If the selected VideoTrack or enabled AudioTracks for the media element change, a addtrack event with a new MediaStreamTrack is generated for each track that was not previously selected or enabled; and a removetrack events is generated for each track that ceases to be selected or enabled. A MediaStreamTrack MUST end prior to being removed from the MediaStream.

Since a MediaStreamTrack can only end once, a track that is enabled, disabled and re-enabled will be captured as two separate tracks. Similarly, restarting playback after playback ends causes a new set of captured MediaStreamTrack instances to be created. Seeking during playback without changing track selection does not generate events or cause a captured MediaStreamTrack to end.

The MediaStreamTracks that comprise the captured MediaStream become muted or unmuted as the tracks they capture change state. At any time, a media element might not have active content available for capture on a given track for a variety of reasons:

• Media playback could be paused.
• A track might not have content for the current playback time if that time is either before the content of that track starts or after the content ends.
• A MediaStreamTrack that is acting as a source could be muted or disabled.
• The contents of the track might become inaccessible to the current origin due to cross-origin protections. For instance, content that is rendered from an HTTP URL can be subject to a redirect on a request for partial content, or the enabled or selected tracks can change to include cross-origin content.

Absence of content is reflected in captured tracks through the muted attribute. A captured MediaStreamTrack MUST have a muted attribute set to true if its corresponding source track does not have available and accessible content. A mute event is raised on the MediaStreamTrack when content availability changes.

What output a muted capture produces as a result will vary based on the type of media: a VideoTrack ceases to capture new frames when muted, causing the captured stream to show the last captured frame; a muted AudioTrack produces silence.

Whether a media element is actively rendering content (e.g., to a screen or audio device) has no effect on the content of captured streams. Muting the audio on a media element does not cause the capture to produce silence, nor does hiding a media element cause captured video to stop.

Captured audio from an element with an effective playback rate other than 1.0 MUST be time-stretched. An unplayable playback rate causes the captured audio track to become muted.

No parameters.

Return type: MediaStream

captureStreamUntilEnded

A stream captured using captureStreamUntilEnded() captures the rendered output from a single media resource. The resulting stream ends when the media element has ended playback.

captureStreamUntilEnded() operates in the same way that captureStream() does, except that when playback ends, so do all the MediaStreamTracks in the MediaStream.

All MediaStreamTracks captured using captureStreamUntilEnded() end when the media element playback ends. After playback has ended, changes to the media element — such as seeking, restarting playback or changing the source media — do not result in changes to the captured MediaStream.

No parameters.

Return type: MediaStream

4.1 Methods

captureStream

The captureStream() method produces a real-time video capture of the surface of the canvas. The resulting media stream has a single video CanvasCaptureMediaStreamTrack that matches the dimensions of the canvas element.

Content from a canvas that is not origin-clean MUST NOT be captured. This method throws a SecurityError exception if the canvas is not origin-clean.

A captured stream MUST immediately cease to capture content if the origin-clean flag of the source canvas becomes false after the stream is created by captureStream(). The captured MediaStreamTrack MUST become muted, producing no new content while the canvas remains in this state.

Each track that captures a canvas has an internal frameCaptureRequested property that is set to true when a new frame is requested from the canvas.

The value of the frameCaptureRequested property on all new tracks is set to true when the track is created. On creation of the captured track with a specific, non-zero frameRate, the user agent starts a periodic timer at an interval of 1/frameRate seconds. At each activation of the timer, the frameCaptureRequested property is set to true.

In order to support manual control of frame capture with the requestFrame() method, browsers MUST support a value of 0 for frameRate. However, a captured stream MUST request capture of a frame when created, even if frameRate is zero.

This method throws a NotSupportedError if frameRate is negative.

A new frame is requested from the canvas when frameCaptureRequested is true and the canvas is painted. Each time that the captured canvas is painted, the following steps are executed:

1. For each track capturing from the canvas execute the following steps:
   1. If new content has been drawn to the canvas since it was last painted, and if the frameCaptureRequested internal property of track is set, add a new frame to track containing what was painted to the canvas.
   2. If a frameRate value was specified, set the frameCaptureRequested internal property of track to false.

Note

This algorithm results in a captured track not starting until something changes in the canvas.

Parameter	Type	Nullable	Optional	Description
frameRate	double	✘	✔

Return type: MediaStream

4.2 The CanvasCaptureMediaStreamTrack

The CanvasCaptureMediaStreamTrack is an extension of MediaStreamTrack that provide a single requestFrame() method. Applications that depend on tight control over the rendering of content to the media stream can use this method to control when frames from the canvas are captured.

interface CanvasCaptureMediaStreamTrack : MediaStreamTrack {
    readonly        attribute HTMLCanvasElement canvas;
    void requestFrame ();
};