Recording Proposal

This proposal attempts to make basic recording very simple, while still allowing for more complex use cases. In the simplest case, the application just calls record() and then calls stopRecord() or waits for the Track 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. (This can be useful when doing media processing or working with a speech recognition system.) This proposal does not deal with resource limitations, but assumes that record() will fail generating an error event if the platform does not have the resources to carry out the requested operations.


partial interface MediaStreamTrack : EventTarget  {
    void        record (optional timeSliceType timeSlice);
    void        stopRecording ();
    readonly attribute Boolean recording;
    readonly attribute EventHandler onrecording;
    readonly attribute EventHandler onstoprecording;
    readonly attribute EventHandler ondataavailable;
    Formats     getRecordingOptions ();
    void        setRecordingOptions (Formats ChosenFormats);
    void        requestData();
};

1.1 Attributes

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 Track, 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 TBD error event instead. The UA must continue recording until stopRecord() is called or the Track is ended. If the Track is muted, the UA must paused gathering data until the Track is unmuted. When it is recording, the UA must gather the data obtained from the Track 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. The UA may garbage collect the original Blob of data once the dataavailable event that contains it has been processed.

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. An error TBD will be raised if unsupported or incompatible options are chosen. An error TBD 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.

1.5 Event summary

The following additional events fire on MediaStreamTrack objects that support the recording interface:

Event name	Interface	Fired when...
`recording`	`Event`	The UA has started recording data on the Track.
`stoprecording`	`Event`	The UA has stopped recording data on the Track.
`dataavailable`	`MediaStreamEvent`	The UA returns data to the application. This event contains a Blob of recorded data.
`various errors TBD`	`MediaStreamEvent`	TODO

1.6 Open issues

As this interface stands, each Track must be recorded separately. What if an application would like to record an audio and video Track into a single file? Is this a postprocessing step (and, if so, should we define it)? Or should we provide an API surface to let the application request that multiple Tracks be recorded as one?
Should recording be moved into a separate class?
We currently specify that the system should not record when the track is paused. Should we instead require it to record filler (silence for audio, black frames for video)?
What are the privacy implications of recording? Does the application need to request special permission?
What do we do if there are conflicts between the chosen encodings? Raise an error and not start recording, I would assume.