Media Recording API

2.1 Attributes

mediaStream of type MediaStream, readonly

The MediaStream passed in to the constructor.

state of type Recordingstate, readonly

The current state of the MediaRecorder object.

onrecording of type EventHandler

Called to handle the recording event.

onstoprecording of type EventHandler

Called to handle the stoprecording event.

ondataavailable of type EventHandler

Called to handle the dataavailable event. Note that the Blob (see FILEAPI) of recorded data is contained in this event and can be accessed via the 'detail' attribute.

onpause of type EventHandler

Called to handle the pause event.

onresume of type EventHandler

Called to handle the resume event.

onmutetrackrecording of type EventHandler

Called to handle the mutetrackrecording event.

onunmutetrackrecording of type EventHandler

Called to handle the unmutetrackrecording event.

onphoto of type EventHandler

Called to handle the photo event. The photo event returns a photo (as a Blob) in a compressed format (for example: PNG/JPEG) rather than a raw ImageData object due to the expected large, uncompressed size of the resulting photos.

onrecordingerror of type EventHandler

Called to handle the recordingerror event.

onrecordingwarning of type EventHandler

Called to handle the recordingwarning event.

2.2 Methods

record

When a 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:

1. Set state to 'recording' and wait until media becomes available from mediaStream.
2. Once data becomes available raise a recordingevent and start gathering the data into a Blob (see FILEAPI).
3. If the timeSlice argument has been provided, then once timeSlice milliseconds of data have been colleced, 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.
4. When the mediaStream is ended set recording to 'false' and stop gathering data.
5. Then raise a dataavailable event containing the Blob of data.
6. Finally, raise a stoprecording event.

Note that stopRecording(), 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 contine recording, it must raise a recordingerror event, follwowed by a dataavailable event containing the Blob it has gathered, follwed by the stoprecording event.

stopRecording

When a 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:

1. Set state to 'inactive' and stop gathering data.
2. Raise a dataavailable event containing the Blob of data that has been gathered.
3. Raise a recordingdone event

requestData

When a 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:

1. Raise a dataavailable event containing the current Blob of saved data.
2. Creat a new Blob and gather subsequent data into it.

pause

When a 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:

1. Set state to "paused".
2. Stop gathering data into its current Blob (but keep the Blob available so that recording can be resumed in the future).
3. Raise a pause event

resume

When a 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:

1. Set state to "recording".
2. Resume (or continue) gathering data into its current Blob.
3. Raise a resume event.

muteTrack

When a 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 mediaStream'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:

1. If the specified Track is a video track, begin inserting black frames into the Blob in place of any data coming from the underlying source. Otherwise (the Track is an audio track) insert silence into the Blob in place of any data coming from the underlying source.
2. Raise a mutetrackrecording event.

unmuteTrack

When a 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 mediaStream'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:

1. Until such time as data is available for this Track from the underlying media source, insert black frames (for a video track) or silence (for an audio track) into the current Blob.
2. Once data is available for this Track from the underlying media source, start collecting it into the current Blob.
3. Raise an unmutetrackrecording event.

takePhoto

When a MediaRecorder object’s takePhoto() 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 mediaStream's videoTrackList with a source type of "photo-camera", 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:

1. Gather data from the Track into a Blob containing a single still image. The method of doing this will depend on the underlying device. Some devices may just do a frame grab, while others may temporarilly stop streaming data, reconfigure themselves with the appropriate photo settings, take the photo, and then resume streaming. In this case, the stopping and restarting of streaming should cause mute and unmute events to fire on the Track in question.
2. Raise an photo event containing the Blob.

getRecordingOptions

When a MediaRecorder object’s getRecordingOptions() method is invoked, the user agent must return a availableRecordingFormats structure containing the set of recording formats that it supports.

setRecordingOptions

When a MediaRecorder object’s setRecordingOptions() 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:

1. Let encodings be the current set of encodings that are specified to be used for recording by the MediaRecorder. (If setRecordingOptions() has not yet been called, these will be the UA's defaults.)
2. For each encoding format that is specified in the requestedFormats argument, if the UA does not support it, raise a UNSUPPORTED_OPTION exception, set encodings back to its value in step 2, and terminate these steps. Otherwise replace the corresponding member of encodings with the specified value.

3.0 RecordingState Enum

enum RecordingState {
    "inactive",
    "recording",
    "paused",
};

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

dictionary BlobEventInit : EventInit {
    Blob data;
};

dictionary AvailableRecordingFormats {
    sequence<DOMString> containerEncodingFormats;
    sequence<DOMString> audioEncodingFormats;
    sequence<DOMString> videoEncodingFormats;
};

dictionary RecordingFormat {
    <DOMString> containerEncodingFormat;
    <DOMString> audioEncodingFormat;
    <DOMString> videoEncodingFormat;
};

interface RecordingError {
    readonly attribute DOMString  name;
    readonly attribute DOMString? message;
};

enum RTCExceptionName {
    "INVALID_MEDIASTREAM_TRACK_ID",
    "INVALID_STATE"
    "UNSUPPORTED_OPTION"
};

enum RecordingErrorName {
    "OUT_OF_MEMORY",
    "ILLEGAL_STREAM_MODIFICATION"
     "OTHER_RECORDING_ERROR"
};