Recording Proposal

1.1 Attributes

mediaStream of type MediaStream, readonly

The MediaStream passed in to the constructor.

recording of type Boolean, readonly

True if 'record()' has been called and not stopped. Otherwise False.

onrecord of type EventHandler

Called to handle the record 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 of recorded data is contained in this event.

1.2 Methods

record

This method serves as a request to start recording and returns immediately. If recording is already occurring, it is a no-op. If media is not yet available on the MediaStream, it will wait until it becomes available, then start recording. Once recording starts, the UA must raise a recording event. If for some reason recording cannot be started, the UA must raise a recordingerror event instead. The UA must record each Track within the MediaStream separately. [This means no combining audio. Is this what we want? If the app wants the audio combined, shouldn't it put it into a single Track?] The UA must continue recording until stopRecord() is called or the MediaStream is ended. If any Track within the MediaStream is muted, the UA must insert black frames or silence until the Track is unmuted. [It seems to me that we need to do this for synchronization in cases where there are multiple streams. Are there container formats that could optimize out the filler and still provide synchronization across Tracks? If so, should we permit them to do so?] When it is recording, the UA must gather the data obtained from the MediaStream into a Blob. If timeslice is specified, then once timeslice milliseconds of data have been gathered, the UA must raise a dataavailable event containing that Blob of recorded data. It must also start collecting a new Blob of data.

If timeslice is not specified, the UA must continue gathering data into the Blob until recording stops. When recording stops, the UA must raise first the dataavailable event, containing its current Blob of data, and then the stoprecording event.

stopRecording

This method serves as a request to stop recording. It returns immediately. When it is called, then if recording is true, then the UA must stop recording and set recording to false. If recording is false, it is a no-op.

getRecordingOptions

Returns the set of the options that the platform supports.

setRecordingOptions

Can be used to select non-default recording options. A recordingerror will be raised if unsupported or incompatible options are chosen. A recordingwarning event will be raised if this is called while recording is occurring, and the call will have no effect.

requestData

This method is a request for the UA to generate a dataavailable event containing the data that it has currently gathered. This method thus allows the application to poll for data according to its own schedule. When this method is called, if recording is true, the UA must raise a dataavailable event containing its current Blob of data and then start collecting a new Blob. If recording is false, this method is a no-op.

1.3 TimeInterval timeSlice

The number of milliseconds of data to return in each dataavailable event. [Need more detail on this type, or a link to the relevant definition.]

1.4 Dictionary Formats

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

containerEncodingFormats of type sequence<DOMtring>

A list of the container encoding formats that the platform supports. When setting this format, containerEncodingFormats="auto" may be used to select the platform default.

audioEncodingFormats of type sequence<DOMtring>

A list of the audio encoding formats that the platform supports. When setting this format, audioEncodingFormats="auto" may be used to select the platform default.

videoEncodingFormats of type sequence<DOMtring>

A list of the video encoding formats that the platform supports. When setting this format, videoEncodingFormats="auto" may be used to select the platform default.

[What kind of type do we need here? The encoding formats will be Mime types, but there might be other settable parameters. Do we just want a general type that will cover all of these?]

The UA must be able to play back any encoding format that it can record into. The UA must support a container format capable of holding at least two video Tracks and two audio Tracks. [Is this worth stating even though it's trivial?]