Copyright © 2012-2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines a recording API for use with MediaStreams as defined in [GETUSERMEDIA]
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.
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
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 MediaRecorder
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.
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.
[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);
};
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 |
|
✘ | ✔ | 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. |
stream
of type MediaStream, readonlymimeType
of type DOMString, readonlymimeType
. 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.
state
of type RecordingState
, readonlyonstart
of type EventHandleronstop
of type EventHandlerondataavailable
of type EventHandlerBlob
[
FILE-API] of recorded data is contained in this event and can be accessed via its data
attribute.onpause
of type EventHandleronresume
of type EventHandleronerror
of type EventHandlerErrorEvent
.ignoreMutedMedia
of type booleantrue
, 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, readonlybitsPerSecond
.audioBitsPerSecond
of type unsigned long, readonlybitsPerSecond
.start
MediaRecorder
object’s
start()
method is invoked, the UA MUST run the following steps:
undefined
. state
is not
inactive, throw an InvalidStateError
DOMException and abort these steps.SecurityError
DOMException and abort these steps.state
to
recording, and run the following steps in parallel:
start
at target.
state
to
inactive.SecurityError
at
target.
stop
at
target.state
to
inactive.UnknownError
at
target.
dataavailable
at target with
blob.stop
at
target.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.state
to
inactive.dataavailable
at target with
blob.stop
at
target.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. |
void
stop
MediaRecorder
object’s stop
method is invoked, the UA MUST run the following steps:
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:
state
to
inactive and stop gathering data.dataavailable
at target with
blob.stop
at target.undefined
.void
pause
MediaRecorder
object’s
pause()
method is invoked, the UA MUST run the following steps:
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:
state
to
paused.pause
at target.undefined
.void
resume
MediaRecorder
object’s resume()
method is invoked, the UA MUST run the following steps:
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:
state
to
recording.resume
at target.undefined
.void
requestData
MediaRecorder
object’s
requestData()
method is invoked, the UA MUST run the following steps:
state
is not
recording 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:
dataavailable
at target with
blob. (Note that blob will be empty if no data has been gathered yet.)undefined
.void
isTypeSupported
, staticMediaRecorder
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:
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).type
does not contain a valid MIME type string, then return false.type
contains a media type or media subtype that the MediaRecorder does not support, then return false.type
contains a media container that the MediaSource does not support, then return false.type
contains a codec that the MediaSource does not support, then return false.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | A MIME Type, including parameters, specifying a container and/or codec formats for recording. |
boolean
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.
dictionary MediaRecorderOptions {
DOMString mimeType
;
unsigned long audioBitsPerSecond
;
unsigned long videoBitsPerSecond
;
unsigned long bitsPerSecond
;
};
MediaRecorderOptions
MembersmimeType
of type DOMStringNotSupportedError
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.
audioBitsPerSecond
of type unsigned longvideoBitsPerSecond
of type unsigned longbitsPerSecond
of type unsigned longaudioBitsPerSecond
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.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. |
[Constructor(DOMString type, BlobEventInit
eventInitDict)]
interface BlobEvent
: Event {
readonly attribute Blob data
;
};
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.
|
data
of type Blob, readonlyBlob
object whose type attribute indicates the encoding of the blob data.
dictionary BlobEventInit {
required Blob data
;
};
BlobEventInit
Membersdata
of type Blob, requiredThis 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
. 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 ErrorEvent
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.
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
interface with the ErrorEvent
attribute set to
error, must be created and
dispatched
at the given target. If no error
DOMException
object is specified, the
attribute defaults to null.error
[Exposed=Window,
Constructor(DOMString type, ErrorEventInit
eventInitDict)]
interface ErrorEvent
: Event {
readonly attribute DOMException? error
;
};
ErrorEvent
ErrorEvent
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict | ErrorEventInit |
✘ | ✘ |
error
of type Error
, readonly , nullabledictionary ErrorEventInit : EventInit {
Error? error
= null;
};
ErrorEventInit
Memberserror
of type Error
, nullable, defaulting to
null
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 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. |
This section is non-normative.
The following additional events fire on
objects:MediaRecorder
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 |
|
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). |
This section is non-normative.
MediaRecorder
and MIMEType
.
if (window.MediaRecorder == undefined) {
console.error('MediaRecorder not supported, boo');
} else {
var codecs = ["video/webm",
"video/webm;codecs=vp8",
"audio/webm",
"video/mp4;codecs=h264",
"video/invalid"];
codecs.forEach( codec => {
console.log(codec + ' is ' + (MediaRecorder.isTypeSupported(codec) ?
'supported' : 'NOT supported '));
});
}
<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>
recordedChunks
can be saved to a file using e.g. the function
download()
in the
MediaRecorder Web Fundamentals article.