Proposed Resolution to Issue 136: Handling of RTCRtpParameters

Peter Thatcher said:

"And now I'm contradicting myself, because the more I think about it, the more I think we should just let the JS leave things blank, and there's no reason to let the JS know what was "filled in" because it doesn't matter."

[BA] Working on that assumption, here is the proposed text for the RTCRtpSender.send() and RTCRtpReceiver.receive() methods as well as RTCRtpEncodingParameters:

send
Media to be sent is controlled by parameters. If send() is called with invalid RTCRtpParameters, throw an InvalidParameters exception. The send() method does not update parameters based on what is currently being sent, so that the value of parameters remains that last passed to the send() method. The RTCRtpSender object starts sending when send() is called for the first time, and changes the sending parameters when send() is called again. The RTCRtpSender object stops sending when stop() is called.

receive
Media to be received is controlled by parameters. If receive() is called with invalid RTCRtpParameters, throw an InvalidParameters exception. The receive() method does not update parameters based on what is currently being received, so that the value of parameters remains that last passed to the receive() method. The RTCRtpReceiver object starts receiving when receive() is called for the first time, and changes the receiving parameters when receive() is called again. The RTCRtpReceiver object stops receiving when stop() is called. After receive returns, track is set, and the value of track.kind is determined based on the kind of the codecs provided in parameters.codecs. If parameters.codecs are all of a single kind then track.kind is set to that kind. If parameters.codecs are of mixed kind, throw an InvalidParameters exception.

9.8 dictionary RTCRtpEncodingParameters

dictionary RTCRtpEncodingParameters {
    unsigned long       ssrc;
    payloadtype         codecPayloadType;
    RTCRtpFecParameters fec;
    RTCRtpRtxParameters rtx;
    double              priority = 1.0;
    double              maxBitrate;
    double              minQuality = 0;
    double              framerateBias = 0.5;
    double              resolutionScale;
    double              framerateScale;
    boolean             active = true;
    DOMString           encodingId;
    sequence<DOMString> dependencyEncodingIds;
};

9.8.1 Dictionary RTCRtpEncodingParameters Members

active of type boolean, defaulting to true
Whether the sender or receiver is active. If false, don't send any media right now. Disable is different than omitting the encoding; it can keep resources available to re-enable more quickly than re-adding. Plus, it still sends RTCP. If unset, the default is assumed.

codecPayloadType of type payloadtype
For per-encoding codec specifications, give the codec Payload Type here. If unset, the browser will choose.

dependencyEncodingIds of type sequence<DOMString>
The encodingIds on which this layer depends. Within this specification encodingIds are permitted only within the same RTCRtpEncodingParameters sequence. In the future if MST were to be supported, then if searching within an RTCRtpEncodingParameters sequence did not produce a match, then a global search would be carried out.

encodingId of type DOMString
An identifier for the encoding object. This identifier should be unique within the scope of the localized sequence of RTCRtpEncodingParameters for any given RTCRtpParameters object.

fec of type RTCRtpFecParameters
Specifies the FEC mechanism if set.

framerateBias of type double, defaulting to 0.5
What to give more bits to, if available. 0.0 = strongly favor resolution or 1.0 = strongly favor framerate. 0.5 = neither (default). For scalable video coding, this parameter is only relevant for the base layer. This parameter is ignored in an RTCRtpReceiver object. If unset, the default is assumed.

framerateScale of type double
Inverse of the input framerate fraction to be encoded. Example: 1.0 = full framerate, 2.0 = one half of the full framerate. For scalable video coding, framerateScale refers to the inverse of the aggregate fraction of input framerate achieved by this layer when combined with all dependent layers.

maxBitrate of type double
Ramp up resolution/quality/framerate until this bitrate, if set. Summed when using dependent layers. This parameter is ignored in scalable video coding, or in an RTCRtpReceiver object. If unset, there is no maximum bitrate.

minQuality of type double, defaulting to 0
Never send less than this quality. 1.0 = maximum attainable quality. For scalable video coding, this parameter is only relevant for the base layer. This parameter is ignored in an RTCRtpReceiver object.
priority of type double, defaulting to 1.0
The higher the value, the more the bits will be given to each as available bandwidth goes up. Default is 1.0. For scalable video coding, this parameter is only relevant for the base layer. This parameter is ignored in an RTCRtpReceiver object. If unset, the default is assumed.

resolutionScale of type double
Inverse of the input resolution fraction to be encoded, or die trying. Example: 1.0 = full resolution, 2.0 = one half of the full resolution. For scalable video coding, resolutionScale refers to the inverse aggregate fraction of the input resolution achieved by this layer when combined with all dependent layers.

rtx of type RTCRtpRtxParameters
Specifies the RTX [RFC4588] parameters if set.

ssrc of type unsigned long
The SSRC for this layering/encoding. If an SSRC is unset in a RTCRtpEncodingParameters object passed to the RTCRtpReceiver.receive method, the next unhandled SSRC will match, and an RTCRtpUnhandledEvent will not be fired. If an SSRC is unset in a RTCRtpEncodingParameters object passed to the RTCRtpSender.send method, the browser will choose, and the chosen value is not reflected in RTCRtpEncodingParameters.ssrc.  If the browser chooses the SSRC, it may change it due to a collision without firing an RTCSsrcConflictEvent.  If the SSRC is set in the RTCRtpEncodingParameters object passed to the RTCRtpSender.send method and an SSRC conflict is detected, then an RTCSsrcConflictEvent is fired (see Section 6.4).

9.6 dictionary RTCRtcpParameters

RTCRtcpParameters provides information on RTCP settings.

dictionary RTCRtcpParameters {
    unsigned long ssrc;
    DOMString     cname;
    boolean       reducedSize = false;
    boolean       mux = true;
};

9.6.1 Dictionary RTCRtcpParameters Members

cname of type DOMString
The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Guidelines for CNAME generation are provided in [RTP-USAGE] Section 4.9. By default, ORTC implementations SHOULD set the CNAME to be the same within all RTCRtcpParameter objects created within the same Javascript sandbox. For backward compatibility with WebRTC 1.0, applications MAY set the CNAME; if unset, the CNAME is chosen by the browser.
mux of type boolean, defaulting to true
Whether RTP and RTCP are multiplexed, as specified in [RFC5761]. The default is true. If set to false, the RTCIceTransport MUST have an associated RTCIceTransport object with a component of "RTCP", in which case RTCP will be sent on the associated RTCIceTransport.

reducedSize of type boolean, defaulting to false
Whether reduced size RTCP [RFC5506] is configured (if true) or compound RTCP as specified in [RFC3550] (if false). The default is false.

ssrc of type unsigned long
The SSRC to be used in the Receiver Report "SSRC of packet sender" field as defined in [RFC3550] Section 6.4.2. If unset, the SSRC is chosen by the browser and the chosen value is not reflected in RTCRtcpParameters.ssrc.