RTCRtpSender: getParameters() method

The getParameters() method of the RTCRtpSender interface returns an object describing the current configuration for how the sender's track will be encoded and transmitted to a remote RTCRtpReceiver.

Syntax

getParameters()

Parameters

None.

Return value

An object indicating the current configuration of the sender.

encodings

An array of objects, each specifying the parameters and settings for a single codec that could be used to encode the track's media. The properties of the objects include:

active

true (the default) if the encoding is being sent, false if it is not being sent or used.

codec Optional

Selects the media codec that is used for this encoding's RTP stream. If not set, the user agent may select any codec negotiated for sending.

channels Optional

A positive integer indicating the number of channels supported by the codec. For example, for audio codecs a value of 1 specifies monaural sound, while 2 indicates stereo.

clockRate

A positive integer specifying the codec's clock rate in Hertz (Hz). The clock rate is the rate at which the codec's RTP timestamp advances. Most codecs have specific values or ranges of values they permit. The IANA maintains a list of codecs and their parameters, including their clock rates.

mimeType

A string indicating the codec's MIME media type and subtype, specified as a string of the form "type/subtype". The MIME type strings used by RTP differ from those used elsewhere. IANA maintains a registry of valid MIME types. Also see Codecs used by WebRTC for details about potential codecs that might be referenced here.

sdpFmtpLine Optional

A string giving the format specific parameters provided by the local description.

dtx Deprecated Non-standard

Only used for an RTCRtpSender whose kind is audio, this property indicates whether or not discontinuous transmission is being used (a feature by which a phone is turned off or the microphone muted automatically in the absence of voice activity). The value is taken either enabled or disabled.

maxBitrate

A positive integer indicating the maximum number of bits per second that the user agent is allowed to grant to tracks encoded with this encoding. Other parameters may further constrain the bit rate, such as the value of maxFramerate, or the bandwidth available for the transport or physical network.

The value is computed using the standard Transport Independent Application Specific Maximum (TIAS) bandwidth as defined by RFC 3890, section 6.2.2; this is the maximum bandwidth needed without considering protocol overheads from IP, TCP or UDP, and so forth.

Note that the bitrate can be achieved in a number of ways, depending on the media and encoding. For example, for video a low bit rate might be achieved by dropping frames (a bitrate of zero might allow just one frame to be sent), while for audio the track might have to stop playing if the bitrate is too low for it to be sent.

maxFramerate

A value specifying the maximum number of frames per second to allow for this encoding.

priority

A string indicating the priority of the RTCRtpSender, which may determine how the user agent allocates bandwidth between senders. Allowed values are very-low, low (default), medium, high.

rid

A string which, if set, specifies an RTP stream ID (RID) to be sent using the RID header extension. This parameter cannot be modified using setParameters(). Its value can only be set when the transceiver is first created.

scaleResolutionDownBy

Only used for senders whose track's kind is video, this is a floating-point value specifying a factor by which to scale down the video during encoding. The default value, 1.0, means that the video will be encoded at its original size. A value of 2.0 scales the video frames down by a factor of 2 in each dimension, resulting in a video 1/4 the size of the original. The value must not be less than 1.0 (attempting to scale the video to a larger size will throw a RangeError).

transactionId

A string containing a unique ID. This value is used to ensure that setParameters() can only be called to modify the parameters returned by a specific previous call to getParameters(). This parameter cannot be changed by the caller.

codecs

An array of objects describing the media codecs that the sender has set as enabled, and is prepared to use. This parameter cannot be changed once initially set.

Each codec object in the array may have the following properties:

channels Optional

A positive integer indicating the number of channels supported by the codec. For example, for audio codecs a value of 1 specifies monaural sound, while 2 indicates stereo.

clockRate

A positive integer specifying the codec's clock rate in Hertz (Hz). The clock rate is the rate at which the codec's RTP timestamp advances. Most codecs have specific values or ranges of values they permit. The IANA maintains a list of codecs and their parameters, including their clock rates.

mimeType

A string indicating the codec's MIME media type and subtype, specified as a string of the form "type/subtype". The MIME type strings used by RTP differ from those used elsewhere. IANA maintains a registry of valid MIME types. Also see Codecs used by WebRTC for details about potential codecs that might be referenced here.

payloadType

The RTP payload type used to identify this codec.

sdpFmtpLine Optional

A string giving the format specific parameters provided by the local description.

headerExtensions

An array of zero or more RTP header extensions, each identifying an extension supported by the sender or receiver. Header extensions are described in RFC 3550, section 5.3.1. This parameter cannot be changed once initially set.

rtcp

An object providing the configuration parameters used for RTCP on the sender. This parameter cannot be changed.

The object may have the following properties:

cname

A read-only string giving the canonical name (CNAME) used by RTCP (e.g., in SDES messages).

reducedSize

A read-only boolean that is True if reduced size RTCP is configured (RFC 5506), and False if compound RTCP is specified (RFC 3550).

degradationPreference Deprecated Optional

Specifies the preferred way the WebRTC layer should handle optimizing bandwidth against quality in constrained-bandwidth situations. The possible values are maintain-framerate, maintain-resolution, or balanced. The default value is balanced.

Examples

This example gets the sender's current transaction ID; the transaction ID uniquely identifies the current set of parameters, to ensure that calls to setParameters() are always handled in the correct order, avoiding inadvertently overwriting parameters with older parameters.

function getSenderTransactionID(sender) {
  let parameters = sender.getParameters();

  return parameters.transactionId;
}

In the same way, this code gets the canonical name (CNAME) being used for RTCP on an RTCRtpSender.

function getRtpCNAME(sender) {
  let parameters = sender.getParameters();

  return parameters.rtcp.cname;
}

Specifications

Browser compatibility

See also

• RTCRtpSender.setParameters()
• RTCRtpReceiver.getParameters()