RTCRtpSender: setParameters() method
The setParameters()
method of the RTCRtpSender
interface applies changes the configuration of sender's track
, which is the MediaStreamTrack
for which the RTCRtpSender
is responsible.
In other words, setParameters()
updates the configuration of the RTP transmission as well as the encoding configuration for a specific outgoing media track on the WebRTC connection.
Syntax
js
setParameters(parameters)
Parameters
parameters
-
A parameters object previously obtained by calling the same sender's
getParameters()
method, with the desired changes to the sender's configuration parameters. These parameters include potential codecs that could be use for encoding the sender'strack
. The available parameters are:encodings
-
An array of
RTCRtpEncodingParameters
objects, each specifying the parameters for a single codec that could be used to encode the track's media. transactionId
-
A string containing a unique ID. This ID is set in the previous
getParameters()
call, and ensures that the parameters originated from a previous call togetParameters()
. codecs
-
An array of
RTCRtpCodecParameters
objects describing the set of codecs from which the sender will choose. This parameter cannot be changed. headerExtensions
-
An array of zero or more RTP header extensions, each identifying an extension supported by the sender. Header extensions are described in RFC 3550, section 5.3.1. This parameter cannot be changed.
rtcp
-
An
RTCRtcpParameters
object providing the configuration parameters used for RTCP on the sender. This parameter cannot be changed. degradationPreference
Deprecated-
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
, orbalanced
. The default value isbalanced
.
Return value
A Promise
that resolves when the RTCRtpSender.track
property is updated with the given parameters.
Exceptions
If an error occurs, the returned promise is rejected with the appropriate exception from the list below.
InvalidModificationError
DOMException
-
Returned if one of the following problems is detected:
-
The number of encodings specified in the
parameters
object'sencodings
property does not match the number of encodings currently listed for theRTCRtpSender
. You cannot change the number of encoding options after the sender has been created. - The order of the specified
encodings
has changed from the current list's order. - An attempt has been made to alter a property that cannot be changed after the sender is first created.
-
The number of encodings specified in the
InvalidStateError
DOMException
-
Returned if the transceiver, of which the
RTCRtpSender
is a part, is not running or has no parameters to set. OperationError
DOMException
-
Returned if an error occurs that does not match the ones specified here.
RangeError
-
Returned if the value specified for
scaleResolutionDownBy
option is less than 1.0 — which would result in scaling up rather than down, which is not allowed; or if one or more of the specifiedencodings
maxFramerate
values is less than 0.0.
In addition, if a WebRTC error occurs while configuring or accessing the media, an RTCError
is thrown with its errorDetail
set to hardware-encoder-error
.
Description
It's important to keep in mind that you can't create the parameters
object yourself and expect it to work.
Instead, you must first call getParameters()
, modify the received parameters object, then pass that object into setParameters()
.
WebRTC uses the parameters object's transactionId
property to ensure that when you set parameters, your changes are based on the most recent parameters rather than an out of date configuration.
Examples
One use case for setParameters()
is to try to reduce network bandwidth used in constrained environments by altering the resolution and/or bit rate of the media being transmitted by the RTCRtpSender
.
Currently, some browsers have limitations on their implementations that may cause issues.
For that reason, two examples are given here.
The first shows how to use setParameters()
when all browsers fully support the parameters being used, while the second example demonstrates workarounds to help solve limitations in browsers with incomplete support for the maxBitrate
and scaleResolutionDownBy
parameters.
By the specification
Once all browsers implement the spec fully, this implementation of setVideoParams()
will do the job. This demonstrates how everything should work.
You should probably use the second example, below, for now.
But this is a clearer demonstration of the basic concept of first fetching the parameters, then altering them, then setting them.
js
async function setVideoParams(sender, height, bitrate) {
const scaleRatio = sender.track.getSettings().height / height;
const params = sender.getParameters();
params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1);
params.encodings[0].maxBitrate = bitrate;
await sender.setParameters(params);
}
In calling this function, you specify a sender, as well as the height you wish to scale the sender's video to, as well as a maximum bitrate to permit the sender to transmit.
A scaling factor for the size of the video, scaleRatio
, is computed.
Then the sender's current parameters are fetched using getParameters()
.
The parameters are then altered by changing the first encodings
object's scaleResolutionDownBy
and maxBitrate
to the calculated scaling factor and the specified maximum bitrate
.
The changed parameters are then saved by calling the sender's setParameters()
method.
Currently compatible implementation
As mentioned above, the previous example shows how things are meant to work. Unfortunately, there are implementation issues preventing this in many browsers right now. For that reason, if you want to be compatible with iPhone and other devices running Safari, and with Firefox, use code more like this:
js
async function setVideoParams(sender, height, bitrate) {
const scaleRatio = sender.track.getSettings().height / height;
const params = sender.getParameters();
// If encodings is null, create it
if (!params.encodings) {
params.encodings = [{}];
}
params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1);
params.encodings[0].maxBitrate = bitrate;
await sender.setParameters(params);
// If the newly changed value of scaleResolutionDownBy is 1,
// use applyConstraints() to be sure the height is constrained,
// since scaleResolutionDownBy may not be implemented
if (sender.getParameters().encodings[0].scaleResolutionDownBy === 1) {
await sender.track.applyConstraints({ height });
}
}
The differences here:
- If
encodings
isnull
, we create it, in order to ensure that we can then set the parameters successfully without crashing. -
If, after setting the parameters, the value of
scaleResolutionDownBy
is still 1, we call the sender's track'sapplyConstraints()
method to constrain the track's height toheight
. This compensates for an unimplementedscaleResolutionDownBy
(as is the case in Safari as of this writing).
This code will cleanly fall back and work the normal way if the browser fully implements the used features.
Specifications
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcrtpsender-setparameters |
Browser compatibility
BCD tables only load in the browser