Abstract

This document defines a recording API for use with MediaStreams as defined in [GETUSERMEDIA]

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is not complete. It is subject to major changes and, while early experimentations are encouraged, it is therefore not intended for implementation. The Media Capture Task Force expects this specification to evolve significantly based on:

This document was published by the Web Real-Time Communication Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All feedback is welcome.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Web Real-Time Communication Working Group, Device APIs Working Group) made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document was published by the Device APIs Working Group and Web Real-Time Communications Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All comments are welcome.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Device APIs Working Group, Web Real-Time Communications Working Group) made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Overview

This section is non-normative.

This API attempts to make basic recording very simple, while still allowing for more complex use cases. In the simplest case, the application instatiates the MediaRecorder object, calls record() and then calls stop() or waits for the MediaStream to be ended. The contents of the recording will be made available in the platform's default encoding via the dataavailable event. Functions are available to query the platform's available set of encodings, and to select the desired ones if the author wishes. The application can also choose how much data it wants to receive at one time. By default a Blob containing the entire recording is returned when the recording finishes. However the application can choose to receive smaller buffers of data at regular intervals.

Conformance

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent to the behavior specified in this document.

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

2. Media Recorder API

[ Constructor (MediaStream stream, [TreatUndefinedAs=Missing] optional DOMString mimeType)]
interface MediaRecorder : EventTarget {
    readonly    attribute MediaStream        stream;
    readonly    attribute DOMString          mimeType;
    readonly    attribute RecordingStateEnum state;
                attribute EventHandler       onstart;
                attribute EventHandler       onstop;
                attribute EventHandler       ondataavailable;
                attribute EventHandler       onpause;
                attribute EventHandler       onresume;
                attribute EventHandler       onerror;
                attribute Boolean            ignoreMutedMedia;
    void             start (optional long timeslice);
    void             stop ();
    void             pause ();
    void             resume ();
    void             requestData ();
    static DOMString canRecordMimeType (DOMString mimeType);
};

2.1 Constructors

MediaRecorder
ParameterTypeNullableOptionalDescription
streamMediaStream✘✘ The MediaStrea to be recorded.
mimeTypeDOMString✘✔ The container format for the recording, which may include any parameters that are defined for the format. If the UA does not support the format or any of the parameters specified, it must raise an UnsupportedOption Exception. If this paramater is not specified, the UA will use a platform-specific default format.

2.2 Attributes

ignoreMutedMedia of type Boolean,
If this attribute is set to true, the MediaRecorder will not record anything when the input Media Stream is muted. If this attribute is false, the MediaRecorder will record silence (for audio) and black frames (for video) when the input MediaStrea is muted. When the MediaRecorder is created, the UA must set this attribute to false.
mimeType of type DOMString, readonly
The MIME type that was be selected as the container for recording. This entry includes all the parameters to the base MimeType. The UA should be able to play back any of the MIME types it supports for recording. For example, it should be able to display a video recording in the HTML tag. The default value for this property is platform-specific.
ondataavailable of type EventHandler,
Called to handle the dataavailable event. Note that the Blob (see [FILE-API]) of recorded data is contained in this event and can be accessed via the 'data' attribute.
onerror of type EventHandler,
Called to handle the DOMError event.
onpause of type EventHandler,
Called to handle the pause event.
onresume of type EventHandler,
Called to handle the resume event.
onstart of type EventHandler,
Called to handle the start event.
onstop of type EventHandler,
Called to handle the stop event.
state of type RecordingStateEnum, readonly
The current state of the MediaRecorder object.
stream of type MediaStream, readonly
The MediaStream to be recorded.

2.3 Methods

canRecordMimeType, static

This method must return the empty string if mimeType is a type that the user agent knows it cannot record; it must return "probably" if the user agent is confident that mimeType represents a type that it can record; and it must return "maybe" otherwise. Implementors are encouraged to return "maybe" unless the type can be confidently established as being supported or not.

ParameterTypeNullableOptionalDescription
mimeTypeDOMString✘✘ A MimeType, including parameters, specifying a container format for recording.
Return type: DOMString
pause
When a MediaRecorder object’s pause()method is invoked, the UA must queue a task, using the DOM manipulation task source, that runs the following steps:
  1. If state is "inactive" raise a DOM InvalidState error and terminate these steps. Otherwise:
  2. Set state to "paused".
  3. Stop gathering data into its current Blob (but keep the Blob available so that recording can be resumed in the future).
  4. Raise a pause event
No parameters.
Return type: void
requestData
When a MediaRecorderobject’s requestData() method is invoked, the UA must queue a task, using the DOM manipulation task source, that runs the following steps:
  1. If state is not "recording" raise a DOM InvalidState error and terminate these steps. Otherwise:
  2. Raise a dataavailable event containing the current Blob of saved data. (Note that this Blob will be empty if no data has been gathered yet.)
  3. Create a new Blob and gather subsequent data into it.
No parameters.
Return type: void
resume
When a MediaRecorder object’s resume() method is invoked, the UA must queue a task, using the DOM manipulation task source, that runs the following steps:
  1. If state is "inactive" raise a DOM InvalidState error and terminate these steps. Otherwise:
  2. Set state to "recording".
  3. Resume (or continue) gathering data into its current Blob.
  4. Raise a resume event.
No parameters.
Return type: void
start
When a MediaRecorder object’s start() method is invoked, the UA must queue a task, using the DOM manipulation task source, that runs the following steps:
  1. If the state is not "inactive", raise a DOM InvalidState error and terminate these steps. Otherwise:
  2. Set state to 'recording' and wait until media becomes available from stream.
  3. Once data becomes available raise a start event and start gathering the data into a Blob (see [FILE-API]).
  4. If the timeSlice argument has been provided, then once timeSlice milliseconds of data have been colleced, or some minimum time slice imposed by the UA, whichever is greater, raise a dataavailable event containing the Blob of collected data, and start gathering a new Blob of data. Otherwise (if timeSlice has not been provided), continue gathering data into the original Blob.
  5. When the stream is ended set recording to 'inactive' and stop gathering data. Callers SHOULD not rely on exactness of the timeSlice value, especially if the timeSlice value is small. Callers SHOULD consider timeSlice as a minimum value
  6. Then raise a dataavailable event containing the Blob of data.
  7. Finally, raise a stop event.

Note that stop(), requestData(), and pause also affect the recording behavior.

The UA must record the MediaStream in such a way that the original Tracks can be retrieved at playback time. When multiple Blobs are returned (because of timeSlice or requestData), the individual Blobs need not be playable, but the combination of all the Blobs from a completed recording must be playable. If any Track within the MediaStream is muted at any time (i.e., if its readyState is set to muted), the UA must insert black frames or silence until the Track is unmuted. If the UA is unable to start recording or at any point is unable to contine recording, it must raise a DOMError event, followed by a dataavailable event containing the Blob it has gathered, follwed by the stop event.

ParameterTypeNullableOptionalDescription
timeslicelong✘✔ The number of milliseconds of data to return in a single Blob.
Return type: void
stop
When a MediaRecorder object’s stop method is invoked, the UA must queue a task, using the DOM manipulation task source, that runs the following steps:
  1. If state is "inactive", raise a DOM InvalideStateErrorevent and terminate these steps. Otherwise:
  2. Set state to 'inactive' and stop gathering data.
  3. Raise a dataavailable event containing the Blob of data that has been gathered.
  4. Raise a stop event
No parameters.
Return type: void

The MediaRecorder() constructor takes one argument which must be of type MediaStream (see [GETUSERMEDIA]). When the constructor is invoked, the UA must construct a new MediaRecorder object, set its mediaStream attribute to be the provided MediaStream, set its state attribute to 'inactive' and return the object.

2.4 RecordingStateEnum

enum RecordingStateEnum {
    "inactive",
    "recording",
    "paused"
};
Enumeration description
inactiveRecording is not occuring. (Either it has not been started or it has been stopped.).
recordingRecording has been started and the UA is capturing data..
pausedRecording has been started, then paused, and not yet stopped or resumed.

3. Blob Event

[Constructor]
interface BlobEvent : Event {
    readonly    attribute Blob data;
};

3.1 Attributes

data of type Blob, readonly
Returns a Blob object whose type attribute indicates the encoding of the blob data.

BlobEventInit

dictionary BlobEventInit {
    Blob data;
};

3.2 Dictionary BlobEventInit Members

data of type Blob
A Blob object containing the data to deliver via this event.

4. MediaRecorder Properties

[TO DO: Provide API surface to set and read these. When that is done, this section will be removed.]

Property Name Values Notes
MimeType DOMString The MIME type that was be selected as the container for recording. This entry includes all the parameters to the base MimeType. The UA should be able to play back any of the MIME types it supports for recording. For example, it should be able to display a video recording in the HTML <img> tag. The default value for this property is platform-specific.
BitRate long The bitrate type that was selected as for recording. The default value for this property is platform-specific.
ignoreMutedMedia boolean If this property is set to 'true', the MediaRecorder should stop recording when the MediaStream is muted. If it is false, the MediaRecorder should record silence (for audio) or black frames(for video) when the source MediaStream is muted. The default value for this property is true.

5. Error Handling

5.1 General Principles

Errors are indicated in two ways: exceptions and objects passed to error callbacks. In the former case, a DOMException is raised (see [DOM4]). An exception must be thrown when the error can be detected at the time that the call is made. In all other cases, an DOMError object(see [DOM4]) must be provided to the failure callback. The error name in the object provided must be picked from the RecordingErrorName enums. If recording has been started and not yet stopped when the error occurs, then after raising the error, the UA must raise a dataavailable event, containing any data that it has gathered, and then a stop event. The UA may set platform-specific limits, such those for the minimum and maximum Blob size that it will support, or the number of Tracks it will record at once. It must signal a fatal error if these limits are exceeded.

5.2 RecordingErrorNameEnum

enum RecordingErrorNameEnum {
    "InvalidState",
    "OutOfMemory",
    "IllegalStreamModification",
    "OtherRecordingError"
};
Enumeration description
InvalidStateThe MediaRecorder is not in a state in which the proposed operation is allowed to be executed.
OutOfMemoryThe UA has exhaused the available memory. User agents SHOULD provide as much additional information as possible in the message attribute.
IllegalStreamModificationA modification to the stream has occurred that makes it impossible to continue recording. An example would be the addition of a Track while recording is occurring. User agents SHOULD provide as much additional information as possible in the message attribute.
OtherRecordingErrorUsed for an fatal error other than those listed above. User agents SHOULD provide as much additional information as possible in the message attribute.

6. RecordingExceptionEnum

enum RecordingExceptionEnum {
    "UnsupportedOption"
};
Enumeration description
UnsupportedOptionThe UA cannot provide the codec or recording option that has been requested.

7. Event summary

This section is non-normative.

The following additional events fire on MediaRecorder objects:

Event name Interface Fired when...
start Event The UA has started recording data on the MediaStream.
stop Event The UA has stopped recording data on the MediaStream.
dataavailable BlobEvent The UA generates this even to return data to the application. The 'data' attribute of this event contains a Blob of recorded data.
pause Event The UA has paused recording data on the MediaStream.
resume Event The UA has resumed recording data on the MediaStream.
DOMError DOMError A fatal error has occurred and the UA has stopped recording. More detailed error information is available in the 'message' attribute.

Open Issues

  1. Do we need an MTI format?
  2. Do we need a "setSyncPoint()" operator and a "syncpoint" signal, so that the client can tell the recorder to insert a point at which a recording can be broken up (typically a new I-frame)?
  3. Do we want a general onstatechange handler in place of onstart, onpause, etc.?

A. References

A.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 8 May 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/dom/
[FILE-API]
Arun Ranganathan; Jonas Sicking. File API. 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/FileAPI/
[GETUSERMEDIA]
Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan. Media Capture and Streams. 3 September 2013. W3C Working Draft. URL: http://www.w3.org/TR/mediacapture-streams/
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/