RTCRtpSender: setParameters() 方法

語法

setParameters(parameters)

引數

parameters

一個引數物件，該物件之前是透過呼叫同一傳送方的 getParameters() 方法獲得的，幷包含對傳送方配置引數所需的更改。這些引數包括可用於編碼傳送方 track 的潛在編解碼器。可用引數包括：

encodings

一個物件陣列，每個物件指定一個可用於編碼 track 媒體的編解碼器的引數。物件的屬性包括：

啟用

將此值設定為 true（預設值）會使此編碼被髮送，而 false 會停止傳送和使用它（但不會導致 SSRC 被移除）。

codec 可選

選擇用於此編碼的 RTP 流的 媒體編解碼器。如果未設定，使用者代理可以選擇任何已協商用於傳送的編解碼器。

channels 可選

一個正整數，指示編解碼器支援的通道數。例如，對於音訊編解碼器，值為 1 表示單聲道，值為 2 表示立體聲。

clockRate

一個正整數，指定編解碼器的時鐘頻率（以赫茲 (Hz) 為單位）。時鐘頻率是編解碼器的 RTP 時間戳前進的速率。大多數編解碼器都有特定的允許值或允許值範圍。IANA 維護著一個編解碼器及其引數列表，包括其時鐘頻率。

mimeType

一個字串，指示編解碼器的 MIME 媒體型別和子型別，格式為 "type/subtype"。RTP 使用的 MIME 型別字串與別處使用的不同。IANA 維護著一個有效 MIME 型別登錄檔。另請參閱 WebRTC 使用的編解碼器，瞭解可能在此引用的潛在編解碼器的詳細資訊。

sdpFmtpLine 可選

一個字串，提供本地描述提供的格式特定引數。

dtx 已棄用 非標準

僅用於 RTCRtpSender 且其 kind 為 audio 的情況。此屬性指示是否使用不間斷傳輸（一種透過在沒有語音活動時自動關閉電話或靜音麥克風的功能）。值可以是 enabled 或 disabled。

maxBitrate

一個正整數，指示使用者代理允許分配給使用此編碼編碼的軌道的每秒最大位元數。其他引數可能會進一步限制位元率，例如 maxFramerate 的值，或者可用於傳輸或物理網路的頻寬。

該值使用標準“傳輸獨立應用程式特定最大值 (TIAS)”頻寬計算，如 RFC 3890，第 6.2.2 節所定義；這是在不考慮 IP、TCP 或 UDP 等協議開銷的情況下所需的最大頻寬。

請注意，位元率可以透過多種方式實現，具體取決於媒體和編碼。例如，對於影片，低位元率可以透過丟幀來實現（零位元率可能只允許傳送一幀），而對於音訊，如果位元率過低無法傳送，則軌道可能不得不停止播放。

maxFramerate

一個值，指定允許此編碼的最大每秒幀數。

優先順序

一個字串，指示 RTCRtpSender 的優先順序，這可能會決定使用者代理如何在傳送方之間分配頻寬。允許的值為 very-low、low（預設）、medium、high。

rid

一個字串，如果設定，指定要使用 RID 頭部擴充套件傳送的RTP 流 ID（RID）。此引數不能透過 setParameters() 修改。其值只能在收發信器首次建立時設定。

scaleResolutionDownBy

僅用於 track 的 kind 為 video 的傳送方，這是一個浮點值，指定編碼過程中影片縮小的係數。預設值 1.0 表示影片將以原始大小進行編碼。值為 2.0 表示將影片幀的每個維度縮小 2 倍，resulting in a video 1/4 the size of the original。該值不得小於 1.0（嘗試將影片放大到更大的尺寸將引發 RangeError）。

transactionId

一個包含唯一 ID 的字串。此 ID 在之前的 getParameters() 呼叫中設定，並確保引數源自之前對 getParameters() 的呼叫。

codecs

一個物件陣列，描述傳送方將從中選擇的 媒體編解碼器。此引數在初始設定後無法更改。

陣列中的每個編解碼器物件可能具有以下屬性：

channels 可選

一個正整數，指示編解碼器支援的通道數。例如，對於音訊編解碼器，值為 1 表示單聲道，值為 2 表示立體聲。

clockRate

一個正整數，指定編解碼器的時鐘頻率（以赫茲 (Hz) 為單位）。時鐘頻率是編解碼器的 RTP 時間戳前進的速率。大多數編解碼器都有特定的允許值或允許值範圍。IANA 維護著一個編解碼器及其引數列表，包括其時鐘頻率。

mimeType

一個字串，指示編解碼器的 MIME 媒體型別和子型別，格式為 "type/subtype"。RTP 使用的 MIME 型別字串與別處使用的不同。IANA 維護著一個有效 MIME 型別登錄檔。另請參閱 WebRTC 使用的編解碼器，瞭解可能在此引用的潛在編解碼器的詳細資訊。

payloadType

用於標識此編解碼器的 RTP 有效載荷型別。

sdpFmtpLine 可選

一個字串，提供本地描述提供的格式特定引數。

headerExtensions

零個或多個 RTP 頭部擴充套件的陣列，每個擴充套件標識傳送方支援的擴充套件。頭部擴充套件在 RFC 3550，第 5.3.1 節中有描述。此引數無法更改。

rtcp

一個物件，提供用於傳送方上 RTCP 的配置引數。此引數無法更改。

該物件可能具有以下屬性：

cname

一個只讀字串，提供 RTCP 使用的規範名稱 (CNAME)（例如，在 SDES 訊息中）。

reducedSize

一個只讀布林值，如果配置了精簡型 RTCP（RFC 5506），則為 true；如果指定了複合型 RTCP（RFC 3550），則為 false。

degradationPreference 已棄用

指定 WebRTC 層在頻寬受限情況下最佳化頻寬與質量的首選方式。可能的值為 maintain-framerate（保持幀率）、maintain-resolution（保持解析度）或 balanced（平衡）。預設值為 balanced。

返回值

一個 Promise，當 RTCRtpSender.track 屬性使用給定引數更新時，該 Promise 會解決。

異常

如果發生錯誤，返回的 Promise 將以以下列表中的相應異常被拒絕。

InvalidModificationError DOMException

當檢測到以下問題之一時返回：

• parameters 物件中的 encodings 屬性指定的編碼數量與 RTCRtpSender 當前列出的編碼數量不匹配。傳送方建立後，您無法更改編碼選項的數量。
• 指定的 encodings 的順序與當前列表的順序不同。
• 嘗試修改傳送方首次建立後無法更改的屬性。

InvalidStateError DOMException

當傳送方所在的收發信器未執行或沒有要設定的引數時返回。

OperationError DOMException

當發生此處未指定的錯誤時返回。

RangeError

當 scaleResolutionDownBy 選項的值小於 1.0（這將導致放大而不是縮小，這是不允許的）時返回；或者當指定的一個或多個 encodings maxFramerate 值小於 0.0 時返回。

此外，如果在配置或訪問媒體時發生 WebRTC 錯誤，將丟擲 RTCError，其 errorDetail 設定為 hardware-encoder-error。

描述

重要的是要記住，您無法自己建立 parameters 物件並期望它能正常工作。相反，您必須先呼叫 getParameters()，修改接收到的引數物件，然後將該物件傳遞給 setParameters()。WebRTC 使用引數物件的 transactionId 屬性來確保當您設定引數時，您的更改是基於最新的引數而不是過時的配置。

示例

setParameters() 的一個用例是在頻寬受限的環境中，透過更改 RTCRtpSender 傳輸的媒體的解析度和/或位元率來嘗試減少網路頻寬使用。

目前，一些瀏覽器對其實現存在限制，可能導致問題。因此，這裡給出了兩個示例。第一個示例展示了當所有瀏覽器完全支援所使用的引數時如何使用 setParameters()，而第二個示例演示瞭如何使用解決方法來幫助解決對 maxBitrate 和 scaleResolutionDownBy 引數支援不完整的瀏覽器中的問題。

根據規範

一旦所有瀏覽器都完全實現規範，setVideoParams() 的此實現將完成工作。這演示了所有應該如何工作。目前，您可能應該使用下面的第二個示例。但這更清晰地展示了首先獲取引數，然後修改它們，然後設定它們的という基本概念。

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);
}

透過呼叫此函式，您可以指定一個傳送方，以及您希望將傳送方的影片縮放到哪個高度，以及允許傳送方傳輸的最大位元率。將計算出影片尺寸的縮放因子 scaleRatio。然後使用 getParameters() 獲取傳送方的當前引數。

然後透過更改第一個 encodings 物件的 scaleResolutionDownBy 和 maxBitrate 分別設定為計算出的縮放因子和指定的最高 bitrate 來修改引數。

然後透過呼叫傳送方的 setParameters() 方法來儲存已更改的引數。

當前相容的實現

如上所述，前面的示例展示了事情的本應如何工作。不幸的是，目前許多瀏覽器中存在實現問題。因此，如果您想相容 iPhone 和執行 Safari 的其他裝置以及 Firefox，請使用更像這樣的程式碼：

async function setVideoParams(sender, height, bitrate) {
  const scaleRatio = sender.track.getSettings().height / height;
  const params = sender.getParameters();

  // If encodings is null, create it
  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 });
  }
}

這裡的主要區別

• 如果 encodings 為 null，我們將建立它，以確保隨後可以成功設定引數而不崩潰。
• 如果在設定引數後，scaleResolutionDownBy 的值仍然為 1，我們將呼叫傳送方 track 的 applyConstraints() 方法來將 track 的高度限制為 height。這可以彌補 scaleResolutionDownBy 的未實現（正如目前 Safari 的情況）。

如果瀏覽器完全實現了所使用的功能，此程式碼將乾淨地回退並正常工作。

規範

瀏覽器相容性

另見

• WebRTC API
• WebRTC 使用的編解碼器
• Web 媒體技術