Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:
© Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.
All subsequent changes since 26 July 2011 done by the W3C WebRTC Working Group and the Device APIs Working Group are under the following Copyright:
© 2011-2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. Document use rules apply.
For the entire publication on the W3C site the liability and trademark rules apply.
This document defines a recording API for use with MediaStreams as defined in Media Capture and Streams [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 http://www.w3.org/TR/.
The API this document describes derives from a proposal originally developed by Ian Hickson, then included in an early version of the WebRTC API. The API has significantly evolved based on the ongoing work on Media Capture and Streams [GETUSERMEDIA], and to take into account the requirements highlighted in MediaStream Capture Scenarios. This is its first publication as a Working Draft on its own.
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, a joint task force of the Device APIs and WebRTC Working Groups, expects this specification to evolve significantly based on:
This document was published by the Web Real-Time Communication Working Group and Device APIs Working Group as a First Public Working 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 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 (Web Real-Time Communication Working Group, Device APIs Working Group) made in connection with the deliverables of the groups; 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 API attempts to make basic recording very simple, while still allowing for more complex use cases. In the simplest case, the application instantiates the MediaRecorder object, calls record() and then calls stopRecord() 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.
[Constructor (MediaStream stream)]
interface MediaRecorder : EventTarget {
readonly attribute MediaStream stream;
readonly attribute RecordingStateEnum
state;
readonly attribute unsigned long imageWidth;
readonly attribute unsigned long imageHeight;
readonly attribute DOMString mimeType;
attribute EventHandler onrecording;
attribute EventHandler onstop;
attribute EventHandler ondataavailable;
attribute EventHandler onpause;
attribute EventHandler onresume;
attribute EventHandler onmutetrack;
attribute EventHandler onunmutetrack;
attribute EventHandler onphoto;
attribute EventHandler onerror;
attribute EventHandler onwarning;
void record (optional long? timeslice);
void stop ();
void pause ();
void resume ();
void muteTrack (DOMString trackID);
void unmuteTrack (DOMString trackID);
void takePhoto (DOMString trackID);
void requestData ();
AvailableSettings
getOptions ();
void setOptions (RecordingSettings
optionValues);
};
imageHeight
of type unsigned long, readonlyimageWidth
of type unsigned long, readonlymimeType
of type DOMString, readonlyondataavailable
of type EventHandleronerror
of type EventHandleronmutetrack
of type EventHandleronpause
of type EventHandleronphoto
of type EventHandleronrecording
of type EventHandleronresume
of type EventHandleronstop
of type EventHandleronunmutetrack
of type EventHandleronwarning
of type EventHandlerstate
of type RecordingStateEnum
, readonlystream
of type MediaStream, readonlygetOptions
MediaRecorder
object’s getOptions()
method is invoked,
the user agent must return an
AvailableSettings structure
containing the set of recording options that it supports. These are the legal
values that can be set via setOptions
.
AvailableSettings
muteTrack
MediaRecorder
object’s muteTrack()
method is invoked,
then if state
is not "recording"
the user agent must raise an INVALID_STATE exception
and return immediately. Otherwise if the trackID
provided is not the
id
of a Track object in stream
's audioTrackList
or videoTrackList
it must raise an INVALID_TRACK_ID exception
and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
mutetrackrecording
event.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
trackID | DOMString | ✘ | ✘ | The id of the audio or video track to mute. |
void
pause
MediaRecorder
object’s pause()
method is invoked,
then if state
is "inactive"
the user agent must raise an INVALID_STATE exception
and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
state
to "paused".pause
event void
record
MediaRecorder
object’s record()
method is invoked,
then, if the state
is not "inactive", the UA must
raise an INVALID_STATE
exception and return immediately.
Otherwise, it must queue a task, using the DOM manipulation task source,
that runs the following steps:
state
to 'recording' and wait until media
becomes available from stream
.recording
event and start gathering the
data into a Blob (see [FILE-API]). timeSlice
argument has been provided, then once timeSlice
milliseconds of data have been collected, 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.stream
is ended set recording
to 'false' and stop gathering data.dataavailable
event containing the Blob of data.stoprecording
event.Note that stop()
,
requestData()
, pause
,
and muteTrack
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. 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 continue recording, it must raise
a recordingerror
event, followed by a dataavailable
event containing
the Blob it has gathered, followed by the stoprecording
event.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
timeslice | long | ✔ | ✔ | The number of milliseconds of data to return in a single Blob. |
void
requestData
MediaRecorder
object’s requestData()
method is invoked,
then if state
is not "recording"
the user agent must raise an INVALID_STATE exception
and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
dataavailable
event containing the current Blob of saved data.void
resume
MediaRecorder
object’s resume()
method is invoked,
then if state
is "inactive"
the user agent must raise an INVALID_STATE exception
and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
state
to "recording".resume
event.void
setOptions
MediaRecorder
object’s setOptions()
method is invoked,
then if state
is not
"inactive", the user agent must raise an INVALID_STATE
exception and return immediately. Otherwise it must
run the following steps before returning:
optionVlaues
argument,
if the UA does not support it, raise a UNSUPPORTED_OPTION exception, set currentOptions
back to its value in step 2, and terminate these steps. Otherwise
replace the corresponding member of currentOptions with the specified value.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
optionValues |
| ✘ | ✘ |
void
stop
MediaRecorder
object’s stopRecording
method is invoked,
then if state
is "inactive", the user agent must
raise an INVALID_STATE exception and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
state
to 'inactive' and stop gathering data. dataavailable
event containing the Blob of data that has been gathered.recordingdone
eventvoid
takePhoto
MediaRecorder
object’s takePhoto()
method is invoked,
then if the trackID
provided is not the
id
of a Track object in stream
's videoTrackList
whose readyState
is "live", the UA must raise an INVALID_TRACK_ID exception
and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
mute
and unmute
events to fire on the Track in question. photo
event containing the Blob.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
trackID | DOMString | ✘ | ✘ | The id of the video track from which to take a snapshot. |
void
unmuteTrack
MediaRecorder
object’s unmuteTrack()
method is invoked,
then if state
is not "recording",
the user agent must raise an INVALID_STATE exception
and return immediately. Otherwise if the trackID
provided is not the
id
of a Track object in stream
's audioTrackList
or videoTrackList
it must raise an INVALID_TRACK_ID exception
and return immediately. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
unmutetrack
event.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
trackID | DOMString | ✘ | ✘ | The id of the audio or video track to unmute. |
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 stream attribute to be the provided MediaStream, set its state attribute to 'inactive'
and return the object.
enum RecordingStateEnum {
"inactive",
"recording",
"paused"
};
Enumeration description | |
---|---|
inactive | Recording is not occurring. (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]
interface BlobEvent : Event {
readonly attribute Blob data;
};
data
of type Blob, readonly<img>
tag. .
dictionary BlobEventInit {
Blob data;
};
BlobEventInit
Membersdata
of type Blobdictionary AvailableSettings {
CapabilityList MimeType;
CapabilityRange imageWidth;
CapabilityRange imageHeight;
};
AvailableSettings
MembersMimeType
of type CapabilityListimageHeight
of type CapabilityRangeimageWidth
of type CapabilityRangedictionary RecordingSettings {
DOMString? MimeType;
unsigned long? imageWidth;
unsigned long? imageHeight;
};
RecordingSettings
MembersMimeType
of type DOMString, nullablemimeType
.
imageHeight
of type unsigned long, nullableimageWidth
.imageWidth
of type unsigned long, nullableimageWidth
.Errors are indicated in two ways: exceptions and objects passed to
error callbacks. Both forms of error reporting must provide an object
of type RecordingError
. An exception must be thrown in the
following cases:
RecordingExceptionName
enum must be used as the error
name.INVALID_STATE
must be used as the error name.In all other cases, an error object must be provided to the failure
callback. The error name in the object provided must be picked from
the RecordingErrorName
enums. After raising the error, the UA must
raise a dataavailable event, containing any data that it has gathered,
and then a recordingdone 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. If a non-fatal error occurs during recording, the UA
should raise a recordingwarning event, with data indicating
the nature of the problem, and continue recording.
interface RecordingError : Error {
readonly attribute RecordingErrorEnum name;
readonly attribute DOMString? message;
};
message
of type DOMString, readonly, nullablename
of type RecordingErrorEnum, readonlydictionary RecordingErrorInit {
RecordingErrorEnum name;
DOMString? message;
};
RecordingErrorInit
Membersmessage
of type DOMString, nullablemessage
attribute.name
of type RecordingErrorEnumname
attribute.
enum RecordingErrorNameEnum {
"OUT_OF_MEMORY",
"ILLEGAL_STREAM_MODIFICATION",
""OTHER_RECORDING_ERROR""
};
Enumeration description | |
---|---|
OUT_OF_MEMORY | The UA has exhausted the available memory. User agents should provide as much additional information as possible in the message attribute. |
ILLEGAL_STREAM_MODIFICATION | A 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. |
"OTHER_RECORDING_ERROR" | Used for an fatal error other than those listed above. User agents should provide as much additional information as possible in the message attribute. |
enum RecordingExcedptionEnum {
"INVALID_STATE",
"INVALID_MEDIASTREAM_TRACK_ID",
"UNSUPPORTED_OPTION"
};
Enumeration description | |
---|---|
INVALID_STATE | The function was called on a MediaRecorder that
is an invalid state, or a state in which the function is not allowed
to be executed. |
INVALID_MEDIASTREAM_TRACK_ID | The argument provided is not the ID of any MediaStreamTrack belonging to the MediaRecorder 's stream . |
UNSUPPORTED_OPTION | The UA cannot provide the codec or recording option that has been requested. |
This section is non-normative.
The following additional events fire on
objects:MediaRecorder
Event name | Interface | Fired when... |
---|---|---|
recording |
Event |
The UA has started recording data on the MediaStream. |
stoprecording |
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. |
photo |
BlobEvent |
The UA uses this event to return a photo to the application (as a Blob). The 'data' attribute of this event contains a Blob of recorded snapshot data. |
pause |
Event |
The UA has paused recording data on the MediaStream. |
resume |
MediaStreamEvent |
The UA has resumed recording data on the MediaStream. |
mutetrack |
MediaStreamTrackEvent |
The MediaRecorder has muted recording on a Track. |
unmutetrack |
MediaStreamTrackEvent |
The MediaRecorder has unmuted recording on a Track. |
recordingerror |
RecordingError |
A fatal error has occurred and the UA has stopped recording. More detailed error information is available in the 'message' attribute. |
recordingwarning |
CustomEvent |
A problem has occurred, but the UA has not stopped recording. More detailed information is available in the 'message' attribute. [Not clear if we need this event.] |