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

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:

Overview

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.

Media Recorder API

Constructor(MediaStream stream, optional MediaRecorderOptions options)
MediaStream stream
The MediaStream to be recorded. This will be the value of the stream attribute. See [[!GETUSERMEDIA]] for the definition of MediaStream.
optional MediaRecorderOptions options
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.
readonly attribute MediaStream stream
The MediaStream to be recorded.
readonly attribute DOMString mimeType
The MIME type 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 that the mimeType specifies the container format for the recording, and that the codecs that the recording contains will normally be specified as parameters to it.
readonly attribute RecordingState state
The current state of the MediaRecorder object. When the MediaRecorder is created, the UA must set this attribute to inactive.
attribute EventHandler onstart
Called to handle the start event.
attribute EventHandler onstop
Called to handle the stop event.
attribute EventHandler ondataavailable
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.
attribute EventHandler onpause
Called to handle the pause event.
attribute EventHandler onresume
Called to handle the resume event.
attribute EventHandler onerror
Called to handle a ErrorEvent.
attribute boolean ignoreMutedMedia
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 MediaStream is muted. When the MediaRecorder is created, the UA must set this attribute to false.
readonly attribute unsigned long videoBitsPerSecond
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.
readonly attribute unsigned long audioBitsPerSecond
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.
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", throw a InvalidStateError DOMException and terminate these steps. Otherwise:
  2. Set state to 'recording' and wait until media becomes available from stream.
  3. Once data becomes available fire 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, fire 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 fire a dataavailable event containing the Blob of data.
  7. Finally, fire 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 at any point the stream's isolation properties change so that MediaRecorder is no longer allowed access to it, the UA must stop recording, discard any data that it has gathered and throw a SecurityError DOMException followed by the stop event. If the UA is unable to start recording or at any point is unable to continue recording (i.e., for reasons other than a security violation), it must throw an UnknownError DOMException, followed by a dataavailable event containing the Blob it has gathered, follwed by the stop event.

optional long timeslice
The number of milliseconds of data to return in a single Blob.
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", throw a InvalidStateError DOMException and terminate these steps. Otherwise:
  2. Set state to 'inactive' and stop gathering data.
  3. Fire a dataavailable event containing the Blob of data that has been gathered.
  4. Fire a stop event
void 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" throw an InvalidStateError DOMException 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. Fire a pause event
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" throw an InvalidStateError DOMException and terminate these steps. Otherwise:
  2. Set state to "recording".
  3. Resume (or continue) gathering data into its current Blob.
  4. Fire a resume event.
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" throw an InvalidStateError DOMException and terminate these steps. Otherwise:
  2. Fire 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.
static bool isTypeSupported(DOMString type)
Check to see whether a MediaRecorder can record in the 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.
DOMString type
A MIME Type, including parameters, specifying a container and/or codec formats for recording.

MediaRecorderOptions

DOMString mimeType
The container and codec(s) format(s) 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 an 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.
unsigned long audioBitsPerSecond
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.
unsigned long videoBitsPerSecond
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.
unsigned long bitsPerSecond
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.

RecordingState

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.

Blob Event

Constructor(DOMString type, BlobEventInit eventInitDict)
DOMString type
Associated Event type.
BlobEventInit eventInitDict
An initializer whose data field will be used to initialize the attribute of the same name.
readonly attribute Blob data
Returns a Blob object whose type attribute indicates the encoding of the blob data.

BlobEventInit

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

Error Handling

General Principles

The UA must throw a DOMException (see [[!DOM4]]) when the error can be detected at the time that the call is made. In all other cases, an ErrorEvent must be fired. If recording has been started and not yet stopped when the error occurs, then after raising the error, the UA must fire a dataavailable event, containing any data that it has gathered, and then a stop event. 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 must signal a fatal error if these limits are exceeded.

ErrorEvent

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

Firing an error event named e with an Error 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 Error object is specified, the error attribute defaults to null.

Constructor(DOMString type, ErrorEventInit eventInitDict)
Constructs a new ErrorEvent.
readonly attribute Error? error
If the event was raised because of an error, this attribute may be set to that error object.
Error? error = null
If the event was raised because of an error, this attribute may be set to that error object.

Exception summary

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]].

NameDescription
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.

Event summary

The following additional events fire on MediaRecorder objects:

Event nameInterfaceFired 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.
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).

Change Log

This section will be removed before publication.

Changes since October 6, 2014

  1. Correct statement about Patent Policy.
  2. Add MediaRecorderErrorEvent, remove reference to DOMError.
  3. Removed [TreatUndefinedAs=Missing] from Media Recorder IDL.
  4. Added missing constructor parameters to BlobEvent constructor.
  5. Updated Editors.
  6. Removed [NoInterfaceObject] from MediaRecorderErrorEvent.
  7. Removed unused RecordingExceptionEnum.
  8. Removed suffix Enum of RecordingStateEnum and RecordingErrorNameEnum.
  9. Corrected references to DOMExceptions where it used to say (MediaRecorderError)Events.
  10. Substituted MediaRecorderErrorEvent with a simple ErrorEvent, no error enum.
  11. mimeType does not need a default value; isTypeSupported() should be true.
  12. Removed UnknownError Exception; added ErrorEvent description.
  13. Added read-only attributes videoBitsPerSecond and audioBitsPerSecond.
  14. Removed MediaRecorder Properties Section, which was a TODO.