Proposed Resolution to Issue #84: Capabilities and Settings

In ORTC  API, we have Capabilities which describe what an implementation can do, and Parameters, which describe what the developer wants to do.

After having reworked the RTCRtpCapabilities object so as to be able to rewrite the Examples that formerly called the createParameters and filterParameters methods, we took a look at the implications for the RTCRtpParameters object.

In the last Editor's draft, the RTCRtpParameters object had made reference to the concepts of Capabilities and Settings from the getUserMedia() specification (specifically, the constrainable interface).

This concerned some folks because of the overall complexity of the constrainable interface.   For example, in Issue #84, Shijun Sun noted that " IMHO we should avoid the "Capabilities" stuff if it is not needed."

So we looked at whether we could simplify the RTCRtpParameters object.

Also, we went over the RTP Usage Draft to make sure that ORTC API could be used to set any configuration parameter which that document "required to be signaled".   A number of things were found to be missing, such as the ability to configure RTP/RTCP multiplexing and reduced-size RTCP.

Furthermore, we looked at what configuration information was necessary for RTCP feedback messages.  Some of these relate to the transport layer (e.g. Generic NACK and TMMBR/TMMBN) so that they can apply to any codec, whereas other payload-specific messages (e.g. SLI, PLI, RPSI) are sent and processed within the codec, so they need to be configured at the codec level.   Rather than enabling RTCP feedback messages to be configured at both the RTP and per-codec levels, we decided that all RTCP configuration should be done at the codec level, so as to avoid complexity.

With respect to Header Extensions, which could be configured for use with particular codecs, there was also a need for global consistency.  For example, the same header extension could be used with multiple codecs but with the same ID for all of them.  Therefore it made sense to have the ID reside at the RTP level, but there also needed to be a way of indicating whether the header extension would be used with a given codec or not.  For example, it would not make sense to use the Client to Mixer Audio extension with a video codec.

After we went through the RTCRtpParameters again with a fine tooth comb, we found that we could eliminate the use of Capabilities and Settings from getUserMedia entirely, while at the same time providing the appropriate configuration knobs.    Here is what the proposed new dictionaries look like:


dictionary RTCRtpParameters {
    DOMString                                 receiverId = "";
// Provide a sequence of codec configurations.
    sequence<RTCRtpCodecParameters>           codecs;
// Provide a sequence of all the header extensions to be supported on all the codecs.
    sequence<RTCRtpHeaderExtensionParameters> headerExtensions;
// Provide the encoding parameters for the codecs.
    sequence<RTCRtpEncodingParameters>        encodings;
// Provide information on RTCP settings applying to all codecs.
    RTCRtcpParameters                         rtcp;
};

dictionary RTCRtpCodecParameters {
// Specify the name of the codec.
    DOMString                 name = "";
// Specify the codec payload type.
    unsigned short            payloadType;
    unsigned long?            clockRate = null;
    unsigned short?           numChannels = 1;
// Indicate what RTCP feedback messages are to be used with this codec.
// This includes both Transport Layer and Payload-specific messages.
    sequence<RTCRtcpFeedback> rtcpFeedback;
// Allow setting of codec-specific parameters (e.g. fmtp parameters).
    Dictionary                parameters;
// Specify the header extensions to be used with this codec.  The header extension IDs
// are specified in RTCRtpParameters so they don't conflict.
    sequence<DOMString>       headerExtensionURIs;
};

dictionary RTCRtpHeaderExtensionParameters {
    DOMString      uri;
// The extension ID.  Must be the same for all codecs enabling the header extension.
    unsigned short id;
// Whether the header extension is encrypted or not.
    boolean        encrypt = false;
};

dictionary RTCRtpEncodingParameters {
// The SSRC to which the encoding parameters apply, if available.
    unsigned long?       ssrc = null;
// Payload Type (and therefore, codec) to which the encoding parameters apply.
    unsigned short?      codecPayloadType = null;
// FEC configuration details, if used.
    RTCRtpFecParameters? fec = null;
// Retransmission configuration details, if used.
    RTCRtpRtxParameters? rtx = null;
    double               priority = 1.0;
// Maximum bitrate.
    double?              maxBitrate = null;
    double               minQuality = 0;
    double               framerateBias = 0.5;
// Fraction of resolution to be used in this layer (for spatial scalability).
    double               resolutionScale = null;
// Fraction of framerate to be supported in this layer (for temporal scalability)
    double               framerateScale = null;
// Fraction of quality to be supported in this layer (for quality scalability)
    double               qualityScale = null;
// Whether this layer is active.
    boolean              active = true;
// The layer identifier (used for either simulcast or SVC layers)
    DOMString?           encodingId;
// The layers on which this layer depends (used only for SVC layers)
    sequence<DOMString>  dependencyEncodingIds;
};

dictionary RTCRtcpParameters {
// The SSRC used for RTCP.
    unsigned long ssrc;
// Whether compound RTCP is used, or reduced size RTCP as specified in RFC 5506 (false).
    boolean       compound = true;
// Whether RTP/RTCP multiplexing is used (as specified in RFC 5761).
    boolean       mux = true;
};