Re: Mozilla/Cisco API Proposal

On 7/10/11 3:29 PM, Anant Narayanan wrote:
> It is based on the WHATWG RTC proposal [1] by Ian Hickson, as well as
> the MediaStream Processing API proposal [2] by Robert O'Callahan.

Hixie suggested that we write up where & why we diverged from the WhatWG 
spec - here is my take. Some of the changes are fairly trivial, others 
not. I'd like to emphasize that our proposal is merely an attempt at 
articulating what we'd *like* to see as an API, and I'm certain that as 
we dig down deeper changes will happen :-)

1. getUserMedia():
 - We renamed it to getMediaStream, simply to make it more clear that a 
successful invocation will return a MediaStream object.
 - The first argument was made into a JS object rather than a string, to 
allow for the application to specify more details as to what kind of 
inputs it would like. We've been using this model in our prototype 
(Rainbow) as well as other Mozilla project that expose APIs via 
navigator [1] and so far developers seem to like it. Keeping it an 
object also allows to extend functionality in the future without 
breaking the function signature.
 - We made the success and error callback into pure functions for 
simplicity, as opposed to events.

2. MediaStream:
 - We don't think it is necessary to differentiate between local and 
remote media streams, so we do not define a LocalMediaStream object. The 
stop() method for the local is emulated by setting the stream's 
readyState to ENDED (if this is done on a remote stream, it means that 
peer is no longer interested in that data).
 - Inputs (sources) and Outputs (sinks) are implied and thus not 
exposed. Assigning a stream to another object (or variable) implies 
adding a sink.
 - We added a BLOCKED state in addition to LIVE and ENDED, to allow a 
peer to say "I do not want data from this stream right now, but I may 
later" - eg. call hold.

3. StreamTrack:
 - Renamed to MediaStreamTrack to signify that it is hierarchically a 
part of MediaStream.
 -  Added a MediaStreamStackHints object to allow JS content to specify 
details about the media it wants to transport, this is to allow the 
platform (user-agent) to select an appropriate codec.
 - Sometimes, the ideal codec cannot be found until after the RTP 
connection is established, so we added an onTypeChanged event. A new 
MediaStreamTrack will be created with the new codec (if it was changed).
 - StreamTrack.kind was renamed to MediaStreamTrack.type and takes a 
IANA media string to allow for more flexibility and to allow specifying 
a codec.
 - MediaStreamTracks can be ENABLED or DISABLED. Eg. someone on a video 
call may choose to DISABLE video and only do audio without interruption 
due to bandwidth constraints.

4. PeerConnection:
 - Renamed signalingCallback -> sendSignal, signalingMessage -> 
receivedSignal, addStream -> addLocalStream, removeStream -> 
removeLocalStream, onaddstream -> onRemoteStreamAdded, onremovestream -> 
onRemoteStreamRemoved for additional clarity.
 - We added a LISTENING state (this means the PeerConnection can call 
accept() to open an incoming connection, the state is entered into by 
calling listen()), and added an open() call to allow a peer to 
explicitly "dial out".
 - This part is tricky because we want to support 1:many. There are a 
few concerns around if ICE even supports it and if it does how it works. 
If it were possible, API wise, we also put up an alternate proposal that 
adds a PeerListener object (this API looks very much like UNIX sockets): 
https://github.com/mozilla/rainbow/wiki/RTC_API_Proposal:PeerListener

5. MediaBuffer:
 - We added this completely new object to try & think about how it to 
make it possible to write decoders purely in JS (such as mp3.js).
 - This is possibly the most ambiguous part of the spec as we are not 
sure if this is worth doing or even possible without getting into codec 
specifics.
 - Tim and Robert have many valid concerns in trying to do this, Cullen 
has some ideas on how we can make it work.

> On 7/11/11 12:36 PM, Harald Alvestrand wrote:
>> I'd like you to give a very short preso on the call on what the core
>> differences are between your proposal and the Hixie one - and how much
>> we can read this as "replacement" versus "delta".
>> A lot of stuff seems very similar to me....

Yes, and above is the delta :-) However, we do think it might be better 
to adopt this as the starting point for the working draft since it 
already addresses all of this. Of course, we're probably quite wrong in 
certain aspects in which case we welcome discussion.

Regards,
-Anant

[1] For example, 
https://developer.mozilla.org/en/OpenWebApps/The_JavaScript_API

Received on Monday, 11 July 2011 20:10:44 UTC