Re: A clarification on Capabilities, Parameters, createParameters, and filterParameters.

So, you're basically saying you want to:

1.  Remove filterParameters.
2.  Add an extra option to the end of createParameters.

I can sort of understand #1, since it isn't strictly necessary to be in the
API.  But I'd like to try implementing and using it first.  It just doesn't
sound that hard to me to implement, or to use.  It's basically
createParameters while reusing some information from the last time
createParameters was run.  And I'm not that worried about "all the use
cases", because if doesn't have to work for all use cases.  It just has to
work for some simple ones, and that's it.  If it doesn't work for your use
case, don't use it.

I can also understand #2, as I mentioned before.  But it would need to be
very simple, and every time I think of a simple set of options to pass in,
I think: why not just do this in a JS library, or learn how to use
RtpParameters?  Again, playing with RtpParameters isn't that hard.  It's
not SDP munging :).




On Fri, May 9, 2014 at 2:11 PM, Robin Raymond <robin@hookflash.com> wrote:

>
> I basically agree with everything said.
>
> I am suggesting though that:
> a) "filterParameters" is extremely difficult to standardize at this point
> in time will requires tremendous work to walk through all the use cases and
> make it future proof
> b) "filterParameters" is probably better suited as an abstraction layer
> (to give experimentation to what's needed to really make it work right)
> c) we can still keep the API usage convenient and simple with
> "createParameters" alone (which is much easier to scope and define
> predictable output and even has the side affect of an easier API to use if
> done right)
> d) "createParameters" as defined currently has marginal benefit because it
> only does a bit of "repackaging" into the "parameters" format and doesn't
> actually do much of value
> e) "createParameters" given a bit of extra "hints" to what is desired can
> be made a much more useful "convenience" function
> f) I don't think we can say "if you want a more sophisticated
> 'createParameters' with hints then do it in a JS abstraction layer" at this
> point in time because we are missing information to make that possible (see
> principle #2). We would need to expand what we intend to include inside our
> Capabilities object to not only include information intended for another
> engine to determine codec / RTP "feature" capability but also to include
> information on what each codec is able to do in a generic fashion with
> enough information for an abstraction layer to be able to take hints and
> spew out parameters.
>
> Bottom line, I suggest we postpone/remove "filterParameters" and make
> "createParameters" a bit more useful (at least until such a point we can
> define a generic Capabilities with enough information that a JS abstraction
> layer can be made spew out appropriate "parameter"s given any codec / RTP
> engine features "pre-known" or "unknown").
>
> If I had my way, I'd remove "createParameters" too, but I'm suspecting
> that's just not possible until Capabilities is a bit more "rich" with
> information.
>
> -Robin
>
>   Peter Thatcher <pthatcher@google.com>
>  May 9, 2014 at 1:54 PM
> Lately, there seems to be some confusion about what Capabilities,
> Parameters, createParameters, and filterParameters are and how they are
> meant to be used.  Since I'm the one that first proposed them, I'd like to
> clear up what they mean.
>
> Principle #1:  ORTC is a "do what I say" API, and Parameters are how the
> JS tells the browser "here's what to do".
>
> All signalling and negotiation ultimately result in the sender saying
> "send X" and the receiver saying "receive X", and the Parameters are how
> the JS says "X".  For RTP, "X" is RtpParameters, and the methods
> are RtpSender.send(RtpParameters) and RtpSender.receive(RtpParameters).
>
> If we get this mechanism right, then all signalling and negotation
> mechanisms can be built on top in JS.
>
>
> Principle #2:  Capablities are how the browser tells the JS "here's what I
> can do".
>
> The JS can't tell the browser what to do (well) if it doesn't now what the
> browser can do.  That last statement in Principle #1 about the JS being
> able to do all the negotiation isn't quite right because it cannot figure
> out how to create Parameters correctly if it doesn't know what is allowed
> and what isn't.  Thus, we need a way of expressing what the browser can do.
>  That's Capabilities.  For RTP, it's RtpCapabilities.
>
> Once we have getCapabilities, send(RtpParameters) and
> receive(RtpParameters), we have everything we need in the browser.
>  Everything else could be done in JS.
>
>
> Principle #3:  createParameters is a convenience function to make the
> simple use cases simple.
>
> It's nice to have a simple, powerful, low-level API of "here's what I can
> do" and "here's what I can do", but for simple use cases, it's a lot of
> work to fill in Parameters properly in the first place.  So, we create a
> convenience function which works for the simple use cases, so that
> developers don't need to fill in the Parameters manually.
>
> Note that we pass the capabilities into the createParameters as a
> convenience to 1.  Allow created parameters to match remote capabilities
> easily, and 2.  To have a convenient place to turn off certain things.  For
> example, if you don't want a specific codec or RTP feature, you can just
> remove it from the capabilities before calling createParameters.  At times
> this may be more convenient than removing it from the Parameters after
> calling createParameters.
>
> It's all about convenience.  We could implement createParameters purely in
> JS and leave it out of the browser entirely.  But it's a large benefit for
> simple use cases at a small complexity cost, so I think it's worth it.
>  More complex use cases can fill in Parameters in more advanced ways
> without using createParameters.
>
>
> Principle #4:  filterParameters is a convenience function to make certain
> simple use cases easier.
>
> If endpoints always exchange capabilities and then call createParameters
> with their respective capabilities, then filterParameters would never be
> needed.  We would only need createParameters.
>
> But sometimes, it's desirable to do signalling/negotiation in one round
> trip. And often to this means that the "initiator" must create and send
> parameters (sometimes called an "offer") with no knowledge of the
> "responder"'s capabilities. At some point, someone (either the initiator or
> responder) must alter the parameters according to the capabilities of the
> responder before telling the browser "here's what to do".
>
> This could be done entirely in JS, but for simple use cases, that's kind
> of a pain, so we introduce a second convenience function: filterParameters.
>  It has a simple meaning:
>
> filterParameters(createParameters(), C) == createParameters(C)
>
> In other words, if createParameters() called with no knowledge of
> capabilities produces P1, then filterParameters(P1, C) will give the
> parameters that createParameters(C) would have returned had the original
> caller of createParameters() known the capabilities.  We could call this
> createParameters(P, C) instead of filterParameters(P, C), if we think it's
> a better name.
>
> That's it.  It's pure convenience and could be done in JS.  If we feel
> like the complexity is too difficult to get right in the standard, then we
> can remove it from the standard and tell developrs "you have to exchange
> capabilities first and pass those down into createParameters or do the
> negotiations yourself".
>
>
> Principle #5:  These 4 things together (Capabilities, Parameters,
> createParameters, filterParameters) allow for lots of different
> signalling/negotiation mechanisms.  It isn't tied to just one.
>
> Sometimes we are used to a certain signalling/negotiation mechanism (such
> as offer/answer), and get all caught up trying to optimize things for the
> one we are used to or like.  For example, the WebRTC 1.0 API is heavily
> optimized for SDP offer/answer.  This model is the opposite.  It isn't tied
> to any signalling/negotiation mechanism.  It allows you to do any, and it
> allows you to do many without much inconvenience.
>
> For example, you can:
> 1.  Exchange capabilities, and then parameters use createParameters (2
> round trips, but extremely easy).
> 2.  Do offer/answer exchanging capabilities and parameters, using
> createParameters and filterParameters (1 round trip, but only a little more
> complex)
> 3.  Do offer/answer exchanging only parameters, using createParameters and
> filterParameters.
> 4.  Decide things apriori, create parameters manually, and have zero round
> trips of signalling.
> 5.  Do lots of advanced stuff manually using Capabilities and Parameters
> and not use createParameters or filterParameters at all.
>
>
> Principle #6:  We strike a balance between power, simplicity, and
> convenience.
>
> Parameters and Capabilities give the JS all the power it needs.
>
> createParameters and filterParameters give it much convenience at the cost
> of some simplicity.
>
> Anything more will need to justify the additional complexity with
> increases in power or convenience.  It filterParameters, for example, is
> too complex to justify the additional convenience, then we can remove it.
>
>
>
> I hope this clears things up.
>
>
>
>
>
>