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's `track`.
 The available parameters are:


`encodings`

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


`active`

Setting this value `true` (the default) causes this encoding to be sent, while `false` stops it from being sent and used (but does not cause the SSRC to be removed).

`dtx` 
Deprecated

Non-standard

 Only used for an `RTCRtpSender` whose `kind` is `audio`, this property indicates whether or not to use discontinuous transmission (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 ID is set in the previous `getParameters()` call, and ensures that the parameters originated from a previous call to `getParameters()`.


`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`, or `balanced`.
 The default value is `balanced`.



### 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's `encodings` property does not match the number of encodings currently listed for the `RTCRtpSender`.
 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.

`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 specified `encodings` `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` is `null`, 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's `applyConstraints()` method to constrain the track's height to `height`.
 This compensates for an unimplemented `scaleResolutionDownBy` (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 with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* Codecs used by WebRTC
* Web media technologies