Proposal for API surface to control how a MediaStreamTrack is sent over the network

We have been discussing this topic for some time. We have for example 
been discussing _what_ aspects the app should be able to influence in v1 
and v2 (and have documented that at 
http://www.w3.org/2011/04/webrtc/wiki/Transport_Control).

I decided to draft _how_ this could be done, and I've used the recently 
proposed 
(http://lists.w3.org/Archives/Public/public-media-capture/2013Oct/att-0027/Constrainable.pdf) 
constrainable interface, and modeled this as on object that can be 
obtained from PeerConnection using a MediaStreamTrack as argument - very 
similar to the DTMFSender in fact.

So, here we go:

Addition to PeerConnection:
---------------------------
partial interface RTCPeerConnection {
       RTCTransportHandler getTransportHandler (MediaStreamTrack track);
};

Method:

getTransportHandler

       The getTransportHandler() method creates an RTCTransportHandler
that references the given MediaStreamTrack. The MediaStreamTrack MUST be
an element of a MediaStream that's currently in the RTCPeerConnection
object's local streams set; if not, throw an
InvalidMediaStreamTrackError exception and abort these steps.

Parameter Type   Nullable Optional Description
track  MediaStreamTrack   ✘  ✘ 
Return type:  RTCTransportHandler


New object:
-----------
interface RTCTransportHandler {
 readonly attribute MediaStreamTrack track;
};
RTCTransportHandler implements Constrainable;

The initial constraints - and settings and capabilities - to support
could be:
* priority (either 0 - 4 or very-low/low/medium/high/very-high)
* maxBitrate (in kpbs - how to calculate need TBD)
(note, possibly "bitrate" defined as a PropertyValueRange would be better)

Conceptually, the RTCTransportHandler always exists. If it doesn't have
a handler for the overconstrained event, the overconstrained event
simply disappears.

With this surface it would be quite simple to add both new constraints
(e.g. minBitrate, select a subset of codec's to be offered, bundle
only) and new methods (e.g. pause/resume sending) in the future without
breaking existing apps.

Note that of with the initially proposed constraints, changing
max-bitrate could influence the SDP (b=AS). We need to document what
would happen if this constraint is changed before the negotiation
(presumable b=AS would be affected) and during an ongoing session (i.e.
would negotiationneeded be fired? (I don't think so)).

This proposal has the drawback that we need some way to check - or an 
error reported - if the MediaStreamTrack in question is no longer 
associated with this PeerConnection. But I guess that could be handled 
in the same way as for DTMFSender.

=========================================================================
Example: Assume that a MediaStream, containing (video) track X, has been
added to PeerConnection PC.

We'd like to allow up to 400 kbps for transmission of this track over
the network, and give it priority "high" (4). But none of those 
constraints are mandatory - we use optional ones.

var Xtransport = PC.getTransporthandler(X);

var XtransportConstraints = {
 optional: [
  {"maxBitrate" : 400},   //max 400 kbps
  {"priority" : 4}
 ]
}

Xtransport.applyConstraints(XtransportConstraints, success, error);

function success (appliedConstr) {
 console.log("transport constraints successfully applied");
 console.log("settings: ");
 var settings = Xtransport.settings();
 if (settings.maxBitrate)
  console.log("maxBitate setting currently: " + settings.maxBitrate);
 if (settings.priority)
  console.log("priority setting currently: " + settings.priority);
}

function error (failedConstraint) {
 //Deal with the error
}
 

/* At some later point in time, the app somehow gets the information
that higher bandwidth is available, and therefore increases maxBitrate */

XtransportConstraints.optional[0] = {"maxBitrate" : 800};

Xtransport.applyConstraints(XtransportConstraints, success, error);

=================================================================

What do you think, could this be a model to use?


Stefan

Received on Thursday, 10 October 2013 07:34:28 UTC