RTCRtpSender.setParameters()

在此页

句法
描述
范例
规范
浏览器兼容性
另请参阅
相关话题

setParameters() 方法在 RTCRtpSender interface applies changes the configuration of sender's track , which is the MediaStreamTrack for which the RTCRtpSender is responsible.

换句话说， setParameters() updates the configuration of the RTP transmission as well as the encoding configuration for a specific outgoing media track on the WebRTC 连接。

句法

var promise = rtcRtpSender.setParameters(parameters)

参数

参数


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 for the last set of parameters applied; this value is used to ensure that setParameters() can only be called to alter changes made by a specific previous call to getParameters() . Once this parameter is initially set, it cannot be changed.

过时特性

degradationPreference: Specifies the preferred way the WebRTC layer should handle optimizing bandwidth against quality in constrained-bandwidth situations; the value comes from the RTCDegradationPreference enumerated string type, and the default is balanced .
priority: A string from the RTCPriorityType enumerated type which indicates the encoding's priority. The default value is low .

返回值

A Promise that resolves when the RTCRtpSender.track property is updated with the given parameters.

异常

If an error occurs, the returned promise is rejected with the appropriate exception from the list below.

InvalidModificationError

One of the following problems was detected:

The number of encodings specified in the 参数 对象的 encodings property does not match the number of encodings currently listed for the RTCRtpSender . You cannot change the number of encoding options once 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

The transceiver of which the


								RTCRtpSender

is a part is not running, or has no parameters to set.

OperationError

Any error condition which occurs that isn't covered by one of the other error codes results in an


								OperationError

RangeError

The value specified for


									scaleResolutionDownBy

is less than 1.0, which would result in scaling up rather than down, which is not allowed; or 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 设为 hardware-encoder-error .

描述

It's important to keep in mind that you can't simply create an RTCRtpSendParameters 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.

范例

One use case for setParameters() is to try to reduce network bandwidth use 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 参数。

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.

async function setVideoParams(sender, height, bitrate) {
  const scaleRatio = sender.track.getSettings().height/height;
  const params = sender.getParameters();
  params.encodings[0].scaleResolutionDownBy = Math.max(ratio, 1);
  params.encodings[0].maxBitrate = bitrate;
  await sender.setParameters(params);
}

In calling this function, you specify a sender, as w.ell 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 对象的 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() 方法。

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:

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(ratio, 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:

若 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.

规范

规范	状态	注释
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'RTCRtpSender.setParameters()' in that specification.	候选推荐	初始定义。

浏览器兼容性

The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`setParameters()`	Chrome Yes	Edge ≤79	Firefox 64 64 Changes to parameters that should update live now do so starting in Firefox 64. 46	IE No	Opera Yes	Safari ?	WebView Android Yes	Chrome Android Yes	Firefox Android 64 64 Changes to parameters that should update live now do so starting in Firefox 64. 46	Opera Android Yes	Safari iOS ?	Samsung Internet Android Yes

图例

完整支持
不支持
兼容性未知 ?

另请参阅

元数据

最后修改： Aug 27, 2020

RTCRtpSender
特性
方法
1. getCapabilities() static function
2. getParameters()
3. getStats()
4. replaceTrack()
5. setParameters()
6. setStreams()

在此页

句法

参数

过时特性

返回值

异常

描述

范例

By the specification

Currently compatible implementation

规范

浏览器兼容性

图例

另请参阅

相关话题