MediaStream Recording

2.1 Attributes

imageHeight of type unsigned long, readonly

The height of the video or photo image to capture. The initial value will be a platform-supplied default.

imageWidth of type unsigned long, readonly

The width of the video or photo image to capture. The initial value will be a platform-supplied default.

mimeType of type DOMString, readonly

The MIME type for recording. It specifies the container format as well as the audio and video capture formats. The initial value will be a platform-supplied default.

ondataavailable of type EventHandler

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.

onerror of type EventHandler

Called to handle the recordingerror event.

onmutetrack of type EventHandler

Called to handle the mutetrack event.

onpause of type EventHandler

Called to handle the pause 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.

onrecording of type EventHandler

Called to handle the recording event.

onresume of type EventHandler

Called to handle the resume event.

onstop of type EventHandler

Called to handle the stop event.

onunmutetrack of type EventHandler

Called to handle the unmutetrack event.

onwarning of type EventHandler

Called to handle the recordingwarning event.

state of type RecordingStateEnum, readonly

The current state of the MediaRecorder object.

stream of type MediaStream, readonly

The MediaStream passed in to the constructor.

2.2 Methods

getOptions

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

No parameters.

Return type: AvailableSettings

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

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.

Parameter	Type	Nullable	Optional	Description
trackID	DOMString	✘	✘	The id of the audio or video track to mute.

Return type: void

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

No parameters.

Return type: void

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 stream.
2. Once data becomes available raise a recording event and start gathering the data into a Blob (see [FILE-API]).
3. If the 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.
4. When the stream 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 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.

Return type: void

requestData

When a MediaRecorderobject’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. Create a new Blob and gather subsequent data into it.

No parameters.

Return type: void

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.

No parameters.

Return type: void

setOptions

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

1. Let currentOptions be the current set of options that are specified to be used for recording by the MediaRecorder. (If setOptions() has not yet been called, these will be the UA's defaults.)
2. For each option that is specified in the 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	RecordingSettings	✘	✘

Return type: void

stop

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

No parameters.

Return type: void

takePhoto

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

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

Parameter	Type	Nullable	Optional	Description
trackID	DOMString	✘	✘	The id of the video track from which to take a snapshot.

Return type: void

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

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 unmutetrack event.

Parameter	Type	Nullable	Optional	Description
trackID	DOMString	✘	✘	The id of the audio or video track to unmute.

Return type: void

2.3 RecordingStateEnum

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

3.1 Attributes

data of type Blob, readonly

Returns a Blob object whose type attribute indicates the encoding of the blob data. An implementation must return a Blob in a format that is capable of being viewed in an HTML <img> tag. .

3.2 Dictionary BlobEventInit Members

data of type Blob

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

4.1 Dictionary AvailableSettings Members

MimeType of type CapabilityList

A list of the MIME types that can be selected as encodings for recording.

imageHeight of type CapabilityRange

The maximum and minimum height, in pixels, for the capture of video or photo images.

imageWidth of type CapabilityRange

The maximum and minimum width, in pixels, for the capture of video or photo images.

4.2 Dictionary RecordingSettings Members

MimeType of type DOMString, nullable

Used to set the value of mimeType.

imageHeight of type unsigned long, nullable

Used to set the value of imageWidth.

imageWidth of type unsigned long, nullable

Used to set the value of imageWidth.

5.1 General Principles

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:

• The type of any argument passed to a function did not match what was expected. An appropriate string from the RecordingExceptionName enum must be used as the error name.
• A function call was made when the Recorder is in an invalid state, or a state in which that particular function is not allowed to be executed. In this case, the string 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.

5.2 RecordingError

interface RecordingError : Error {
    readonly attribute RecordingErrorEnum name;
    readonly attribute DOMString?         message;
};

dictionary RecordingErrorInit {
    RecordingErrorEnum name;
    DOMString?         message;
};

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

5.3 RecordingExceptionEnum

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