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 https://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 Device and Sensors Working Group and the Web Real-Time Communications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. 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 a Working 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 groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Device and Sensors Working Group) and a public list of any patent disclosures (Web Real-Time Communications Working Group) made in connection with the deliverables of each group; these pages also include 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 is governed by the 1 September 2015 W3C Process Document.

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 instantiates a MediaRecorder object, calls start() and then calls stop() or waits for the MediaStreamTrack(s) to be ended. The contents of the recording will be made available in the platform's default encoding via the ondataavailable 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.

2. Conformance

This section is non-normative.

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.

3. Media Recorder API 

[Constructor(MediaStream stream, optional MediaRecorderOptions options)]
interface MediaRecorder : EventTarget {
    readonly attribute MediaStream    stream;
    readonly attribute DOMString      mimeType;
    readonly attribute RecordingState state;
             attribute EventHandler   onstart;
             attribute EventHandler   onstop;
             attribute EventHandler   ondataavailable;
             attribute EventHandler   onpause;
             attribute EventHandler   onresume;
             attribute EventHandler   onerror;
             attribute boolean        ignoreMutedMedia;
    readonly attribute unsigned long  videoBitsPerSecond;
    readonly attribute unsigned long  audioBitsPerSecond;
    void    start(optional long timeslice);
    void    stop();
    void    pause();
    void    resume();
    void    requestData();
    static boolean isTypeSupported(DOMString type);
};

Constructors

MediaRecorder
Parameter Type Nullable Optional Description
stream MediaStream ✘ ✘ The MediaStream to be recorded. This will be the value of the stream attribute. See [ GETUSERMEDIA] for the definition of MediaStream.
options MediaRecorderOptions ✘ ✔ A dictionary of options to for the UA instructing how the recording will take part. options.mimeType, if present, will become the value of mimeType attribute.

Attributes

stream of type MediaStream, readonly
The MediaStream to be recorded.
mimeType of type DOMString, readonly
The MIME type [RFC2046] that has been 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 <video> tag. The default value for this property is platform-specific.
Note
mimeType specifies the media type and container format for the recording via a type/subtype combination, with the codecs and/or profiles parameters [RFC6381] specified where ambiguity might arise. Individual codecs might have further optional specific parameters.
state of type RecordingState, readonly
The current state of the MediaRecorder object. When the MediaRecorder is created, the UA MUST set this attribute to inactive.
onstart of type EventHandler
Called to handle the start event.
onstop of type EventHandler
Called to handle the stop event.
ondataavailable of type EventHandler
Called to handle the dataavailable event. The Blob [ FILE-API] of recorded data is contained in this event and can be accessed via its data attribute.
onpause of type EventHandler
Called to handle the pause event.
onresume of type EventHandler
Called to handle the resume event.
onerror of type EventHandler
Called to handle an ErrorEvent.
ignoreMutedMedia of type boolean
If this attribute is set to true, MediaRecorder will not record any input when a given source MediaStreamTrack is muted. If this attribute is false, MediaRecorder will record silence (for audio) and black frames (for video) when the corresponding MediaStreamTrack is muted. When the MediaRecorder is created, the UA MUST set this attribute to false.
videoBitsPerSecond of type unsigned long, readonly
The value of the Video encoding target bit rate that was passed to the Platform (potentially truncated, rounded, etc), or the calculated one if the user has specified bitsPerSecond.
audioBitsPerSecond of type unsigned long, readonly
The value of the Audio encoding target bit rate that was passed to the Platform (potentially truncated, rounded, etc), or the calculated one if the user has specified bitsPerSecond.

Methods

start
When a MediaRecorder object’s start() method is invoked, the UA MUST run the following steps:
  1. Let target be the MediaRecorder context object.
  2. Let timeslice be the method's first argument, if provided, or undefined.
  3. If state is not inactive, throw an InvalidStateError DOMException and abort these steps.
  4. If the stream's isolation properties disallow access from this MediaRecorder, throw a SecurityError DOMException and abort these steps.
  5. Set state to recording, and run the following steps in parallel:
    1. Once media becomes available from one or more of the stream's tracks, start gathering the data into a Blob ([ FILE-API]) blob and queue a task, using the DOM manipulation task source, to fire an event named start at target.
    2. If at any point the stream's isolation properties change so that MediaRecorder is no longer allowed access to it, the UA MUST immediately stop gathering data, discard any data that it has gathered, and queue a task, using the DOM manipulation task source, that runs the following steps:
      1. Set state to inactive.
      2. Fire an error event named SecurityError at target.
      3. Fire an event named stop at target.
    3. If the UA at any point is unable to continue gathering data for reasons other than isolation properties, it MUST stop gathering data, and queue a task, using the DOM manipulation task source, that runs the following steps:
      1. Set state to inactive.
      2. Fire an error event named UnknownError at target.
      3. Fire a blob event named dataavailable at target with blob.
      4. Fire an event named stop at target.
    4. If timeslice is not undefined, then once a minimum of timeslice milliseconds of data have been collected, or some minimum time slice imposed by the UA, whichever is greater, start gathering data into a a new Blob blob, and queue a task, using the DOM manipulation task source, that fires a blob event named dataavailable at target with blob. Note that an undefined value of timeslice will be understood as the largest long value.
    5. If all recorded tracks become ended [GETUSERMEDIA], then stop gathering data, and queue a task, using the DOM manipulation task source, that runs the following steps:
      1. Set state to inactive.
      2. Fire a blob event named dataavailable at target with blob.
      3. Fire an event named stop at target.
  6. return undefined.

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 muted flag is set to true), the UA MUST insert black frames or silence until the Track is unmuted, or record nothing, depending on the value of ignoreMutedMedia.

Parameter Type Nullable Optional Description
timeslice long ✘ ✔ The minimum 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 run the following steps:
  1. If state is inactive, throw an InvalidStateError DOMException and terminate these steps. Otherwise the UA MUST queue a task, using the DOM manipulation task source, that runs the following steps:
    1. Set state to inactive and stop gathering data.
    2. Let blob be the Blob of collected data so far and let target be the MediaRecorder context object, then fire a blob event named dataavailable at target with blob.
    3. Fire an event named stop at target.
  2. return undefined.
No parameters.
Return type: void
pause
When a MediaRecorder object’s pause()method is invoked, the UA MUST run the following steps:
  1. If state is inactive throw an InvalidStateError DOMException and terminate these steps. Otherwise the UA MUST queue a task, using the DOM manipulation task source, that runs the following steps:
    1. Set state to paused.
    2. Stop gathering data into blob (but keep it available so that recording can be resumed in the future).
    3. Let target be the MediaRecorder context object. Fire an event named pause at target.
  2. return undefined.
No parameters.
Return type: void
resume
When a MediaRecorder object’s resume() method is invoked, the UA MUST run the following steps:
  1. If state is inactive throw an InvalidStateError DOMException and terminate these steps. Otherwise the UA MUST queue a task, using the DOM manipulation task source, that runs the following steps:
    1. Set state to recording.
    2. Resume (or continue) gathering data into the current blob.
    3. Let target be the MediaRecorder context object. Fire an event named resume at target.
  2. return undefined.
No parameters.
Return type: void
requestData
When a MediaRecorderobject’s requestData() method is invoked, the UA MUST run the following steps:
  1. If state is not inactive throw an InvalidStateError DOMException and terminate these steps. Otherwise the UA MUST queue a task, using the DOM manipulation task source, that runs the following steps:
    1. Let blob be the Blob of collected data so far and let target be the MediaRecorder context object, then fire a blob event named dataavailable at target with blob. (Note that blob will be empty if no data has been gathered yet.)
    2. Create a new Blob and gather subsequent data into it.
  2. return undefined.
No parameters.
Return type: void
isTypeSupported, static
Check to see whether a MediaRecorder can record in a specified MIME type. If true is returned from this method, it only indicates that the MediaRecorder implementation is capable of recording Blob objects for the specified MIME type. Recording may still fail if sufficient resources are not available to support the concrete media encoding. When this method is invoked, the User Agent must run the following steps:
  1. If type is an empty string, then return true (note that this case is essentially equivalent to leaving up to the UA the choice of container and codecs on constructor).
  2. If type does not contain a valid MIME type string, then return false.
  3. If type contains a media type or media subtype that the MediaRecorder does not support, then return false.
  4. If type contains a media container that the MediaSource does not support, then return false.
  5. If type contains a codec that the MediaSource does not support, then return false.
  6. If the MediaRecorder does not support the specified combination of media type/subtype, codecs and container then return false.
  7. Return true.
Parameter Type Nullable Optional Description
type DOMString ✘ ✘ A MIME Type, including parameters, specifying a container and/or codec formats for recording.
Return type: boolean

3.1 Data handling

To fire a blob event with a Blob blob means firing an event at target using a BlobEvent with its data attribute initialized to blob.

Note
Usually blob will be the data gathered by the UA after the last transition to recording state.

3.2 MediaRecorderOptions 

dictionary MediaRecorderOptions {
    DOMString     mimeType;
    unsigned long audioBitsPerSecond;
    unsigned long videoBitsPerSecond;
    unsigned long bitsPerSecond;
};

Dictionary MediaRecorderOptions Members

mimeType of type DOMString
The container and codec format(s) [RFC2046] 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 throw a NotSupportedError DOMException. If this paramater is not specified, the UA will use a platform-specific default format. The container format, whether passed in to the constructor or defaulted, will be used as the value of the mimeType attribute.
Note
mimeType specifies the media type and container format for the recording via a type/subtype combination, with the codecs and/or profiles parameters [RFC6381] specified where ambiguity might arise. Individual codecs might have further optional specific parameters.
audioBitsPerSecond of type unsigned long
Aggregate target bits per second for encoding of the Audio track(s), if any. This is a hint for the encoder and the value might be surpassed, not achieved, or only be achieved over a long period of time.
videoBitsPerSecond of type unsigned long
Aggregate target bits per second for encoding of the Video track(s), if any. This is a hint for the encoder and the value might be surpassed, not achieved, or only be achieved over a long period of time.
bitsPerSecond of type unsigned long
Aggregate target bits per second for encoding of all Video and Audio Track(s) present. This parameter overrides either audioBitsPerSecond or videoBitsPerSecond if present, and might be distributed among the present track encoders as the UA sees fit. This parameter is a hint for the encoder(s) and the total value might be surpassed, not achieved, or only be achieved over a long period of time.

3.3 RecordingState 

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

4. Blob Event 

[Constructor(DOMString type, BlobEventInit eventInitDict)]
interface BlobEvent : Event {
    readonly attribute Blob data;
};

Constructors

BlobEvent
Parameter Type Nullable Optional Description
type DOMString ✘ ✘ Associated Event type.
eventInitDict BlobEventInit ✘ ✘ An initializer whose data field will be used to initialize the attribute of the same name.

Attributes

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

BlobEventInit

dictionary BlobEventInit {
    required Blob data;
};

Dictionary BlobEventInit Members

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

5. Error Handling

5.1 General Principles

This section is non-normative.

The UA will throw a DOMException ([ DOM]) when the error can be detected at the time that the call is made. In all other cases the UA will fire an event named ErrorEvent. If recording has been started and not yet stopped when the error occurs, let blob be the Blob of collected data so far; after raising the error, the UA will fire a dataavailable event with blob; immediately after the UA will then fire an event named stop. The UA may set platform-specific limits, such as those for the minimum and maximum Blob size that it will support, or the number of Tracks it will record at once. It will signal a fatal error if these limits are exceeded.

5.2 ErrorEvent

The ErrorEvent interface is defined for cases when an event is raised that could have been caused by an error.

To fire an error event named e with a DOMException named error means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the ErrorEvent interface with the error attribute set to error, must be created and dispatched at the given target. If no DOMException object is specified, the error attribute defaults to null.

[Exposed=Window,
 Constructor(DOMString type, ErrorEventInit eventInitDict)]
interface ErrorEvent : Event {
    readonly attribute DOMException? error;
};

Constructors

ErrorEvent
Constructs a new ErrorEvent .
Parameter Type Nullable Optional Description
type DOMString ✘ ✘
eventInitDict ErrorEventInit ✘ ✘

Attributes

error of type Error, readonly , nullable
If the event was raised because of an error, this attribute MAY be set to that error object.
dictionary ErrorEventInit : EventInit {
    Error? error = null;
};

Dictionary ErrorEventInit Members

error of type Error, nullable, defaulting to null
If the event was raised because of an error, this attribute MAY be set to that error object.

5.3 Exception summary

This section is non-normative.

Each of the exceptions defined in this document is a DOMException with a specific type. The exception types and properties such as code value are defined in [WEBIDL].

Name Description
InvalidStateError An operation was called on an object on which it is not allowed or at a time when it is not allowed, or if a request is made on a source object that has been deleted or removed.
NotSupportedError A MediaRecorder could not be created due to unsupported options (e.g. MIME type) specification. User agents should provide as much additional information as possible in the message attribute.
SecurityError The isolation properties of the MediaStream do not allow the MediaRecorder access to it.

6. 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 from the MediaStream.
stop Event The UA has stopped recording data from 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 from the MediaStream.
resume Event The UA has resumed recording data from the MediaStream.
ErrorEvent EventError An error has occurred, e.g. out of memory or a modification to the stream has occurred that makes it impossible to continue recording (e.g. a Track has been added to or removed from the said stream while recording is occurring).

7. Examples

This section is non-normative.

Note
Slightly modified versions of these examples can be found in e.g. this codepen collection.

7.1 Check for MediaRecorder and MIMEType.

Note
The following example can also be found in e.g. this codepen with minimal modifications.
Example 1
if (window.MediaRecorder == undefined) {
  console.error('MediaRecorder not supported, boo');
} else {
  var contentTypes = ["video/webm",
                      "video/webm;codecs=vp8",
                      "audio/webm",
                      "video/mp4;codecs=h264",
                      "video/invalid"];
  contentTypes.forEach(contentType => {
    console.log(contentType + ' is '
        + (MediaRecorder.isTypeSupported(contentType) ?
            'supported' : 'NOT supported '));
  });
}

7.2 Recording webcam video and audio

Note
The following example can also be found in e.g. this codepen with minimal modifications.
Example 2
<html>
<body>
<video autoplay/>
<script>
  var recordedChunks = [];

  function gotMedia(stream) {
    var video = document.querySelector('video');
    video.src = URL.createObjectURL(stream);
    var recorder = null;
    try {
      recorder = new MediaRecorder(stream, {mimeType : "video/webm"});
    } catch (e) {
      console.error('Exception while creating MediaRecorder: ' + e);
      return;
    }

    recorder.ondataavailable = (event) => {
      console.log(' Recorded chunk of size ' + event.data.size + "B");
      recordedChunks.push(event.data);
    };

    recorder.start(100);
  }

  navigator.mediaDevices.getUserMedia({video: true , audio: true})
      .then(gotMedia)
      .catch(e => { console.error('getUserMedia() failed: ' + e); });
</script>
</body>
</html>
Note
recordedChunks can be saved to a file using e.g. the function download() in the MediaRecorder Web Fundamentals article.

A. References

A.1 Normative references

[DOM]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: https://www.w3.org/TR/dom/
[FILE-API]
Arun Ranganathan; Jonas Sicking. W3C. File API. 21 April 2015. W3C Working Draft. URL: https://www.w3.org/TR/FileAPI/
[GETUSERMEDIA]
Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. Media Capture and Streams. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
[RFC2046]
N. Freed; N. Borenstein. IETF. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2046
[WEBIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. Web IDL. 15 September 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/

A.2 Informative references

[RFC6381]
R. Gellens; D. Singer; P. Frojdh. IETF. The 'Codecs' and 'Profiles' Parameters for "Bucket" Media Types. August 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6381