RTCRtpSender: Methode setParameters()

Syntax

setParameters(parameters)

Parameter

parameters

Ein Parameterobjekt, das zuvor durch Aufrufen der Methode getParameters() desselben Senders abgerufen wurde und die gewünschten Änderungen an den Konfigurationsparametern des Senders enthält. Diese Parameter umfassen mögliche Codecs, die zur Kodierung des track des Senders verwendet werden könnten. Die verfügbaren Parameter sind:

encodings

Ein Array von Objekten, von denen jedes die Parameter für einen einzelnen Codec angibt, der zur Kodierung der Medien des Tracks verwendet werden könnte. Die Eigenschaften der Objekte umfassen:

active

Das Setzen dieses Werts auf true (der Standardwert) bewirkt, dass diese Kodierung gesendet wird, während false verhindert, dass sie gesendet und verwendet wird (führt jedoch nicht dazu, dass die SSRC entfernt wird).

codec Optional

Wählt den Medien-Codec aus, der für den RTP-Stream dieser Kodierung verwendet wird. Wenn nicht festgelegt, kann der User-Agent einen beliebigen für das Senden ausgehandelten Codec auswählen.

channels Optional

Eine positive Ganzzahl, die die Anzahl der vom Codec unterstützten Kanäle angibt. Beispielsweise gibt für Audio-Codecs ein Wert von 1 monauralen Klang an, während 2 Stereo angibt.

clockRate

Eine positive Ganzzahl, die die Clock-Rate des Codecs in Hertz (Hz) angibt. Die Clock-Rate ist die Rate, mit der der RTP-Zeitstempel des Codecs fortschreitet. Die meisten Codecs haben bestimmte Werte oder Wertebereiche, die sie zulassen. Die IANA pflegt eine Liste von Codecs und ihren Parametern, einschließlich ihrer Clock-Rates.

mimeType

Ein String, der den MIME-Medientyp und -Subtyp des Codecs angibt, in der Form "type/subtype". Die von RTP verwendeten MIME-Type-Strings unterscheiden sich von denen, die an anderer Stelle verwendet werden. Die IANA pflegt ein Register gültiger MIME-Typen. Siehe auch Von WebRTC verwendete Codecs für Details zu möglichen Codecs, auf die hier verwiesen werden könnte.

sdpFmtpLine Optional

Ein String, der die von der lokalen Beschreibung bereitgestellten formatspezifischen Parameter angibt.

dtx

Wird nur für einen RTCRtpSender verwendet, dessen kind audio ist. Diese Eigenschaft gibt an, ob diskontinuierliche Übertragung verwendet werden soll (eine Funktion, bei der ein Telefon ausgeschaltet oder das Mikrofon bei fehlender Sprachaktivität automatisch stummgeschaltet wird). Der Wert ist entweder enabled oder disabled.

maxBitrate

Eine positive Ganzzahl, die die maximale Anzahl von Bits pro Sekunde angibt, die der User-Agent Tracks gewähren darf, die mit dieser Kodierung kodiert werden. Andere Parameter können die Bitrate weiter einschränken, etwa der Wert von maxFramerate oder die für den Transport oder das physische Netzwerk verfügbare Bandbreite.

Der Wert wird unter Verwendung der standardmäßigen Transport Independent Application Specific Maximum (TIAS)-Bandbreite berechnet, wie in RFC 3890, Abschnitt 6.2.2 definiert; dies ist die maximal benötigte Bandbreite ohne Berücksichtigung von Protokoll-Overhead durch IP, TCP oder UDP usw.

Beachten Sie, dass die Bitrate je nach Medium und Kodierung auf verschiedene Arten erreicht werden kann. Beispielsweise kann bei Video eine niedrige Bitrate durch das Verwerfen von Frames erreicht werden (eine Bitrate von null könnte erlauben, nur einen Frame zu senden), während bei Audio der Track möglicherweise nicht mehr wiedergegeben werden kann, wenn die Bitrate für das Senden zu niedrig ist.

maxFramerate

Ein Wert, der die maximale Anzahl von Frames pro Sekunde angibt, die für diese Kodierung zulässig ist.

priority

Ein String, der die Priorität des RTCRtpSender angibt und bestimmen kann, wie der User-Agent die Bandbreite zwischen Sendern zuweist. Zulässige Werte sind very-low, low (Standard), medium, high.

rid

Ein String, der, falls festgelegt, eine RTP-Stream-ID (RID) angibt, die mithilfe der RID-Header-Erweiterung gesendet werden soll. Dieser Parameter kann nicht mit setParameters() geändert werden. Sein Wert kann nur beim ersten Erstellen des Transceivers festgelegt werden.

scaleResolutionDownBy

Wird nur für Sender verwendet, deren kind des Tracks video ist. Dies ist ein Gleitkommawert, der einen Faktor angibt, um den das Video während der Kodierung herunterskaliert wird. Der Standardwert 1.0 bedeutet, dass das Video in seiner ursprünglichen Größe kodiert wird. Ein Wert von 2.0 skaliert die Videoframes in jeder Dimension um den Faktor 2 herunter, wodurch ein Video mit 1/4 der Größe des Originals entsteht. Der Wert darf nicht kleiner als 1.0 sein (der Versuch, das Video auf eine größere Größe zu skalieren, löst einen RangeError aus).

transactionId

Ein String mit einer eindeutigen ID. Diese ID wird im vorherigen Aufruf von getParameters() festgelegt und stellt sicher, dass die Parameter aus einem vorherigen Aufruf von getParameters() stammen.

codecs

Ein Array von Objekten, die die Medien-Codecs beschreiben, aus denen der Sender auswählt. Dieser Parameter kann nach seiner anfänglichen Festlegung nicht mehr geändert werden.

Jedes Codec-Objekt im Array kann die folgenden Eigenschaften haben:

channels Optional

Eine positive Ganzzahl, die die Anzahl der vom Codec unterstützten Kanäle angibt. Beispielsweise gibt für Audio-Codecs ein Wert von 1 monauralen Klang an, während 2 Stereo angibt.

clockRate

Eine positive Ganzzahl, die die Clock-Rate des Codecs in Hertz (Hz) angibt. Die Clock-Rate ist die Rate, mit der der RTP-Zeitstempel des Codecs fortschreitet. Die meisten Codecs haben bestimmte Werte oder Wertebereiche, die sie zulassen. Die IANA pflegt eine Liste von Codecs und ihren Parametern, einschließlich ihrer Clock-Rates.

mimeType

Ein String, der den MIME-Medientyp und -Subtyp des Codecs angibt, in der Form "type/subtype". Die von RTP verwendeten MIME-Type-Strings unterscheiden sich von denen, die an anderer Stelle verwendet werden. Die IANA pflegt ein Register gültiger MIME-Typen. Siehe auch Von WebRTC verwendete Codecs für Details zu möglichen Codecs, auf die hier verwiesen werden könnte.

payloadType

Der RTP-Payload-Typ, der zur Identifizierung dieses Codecs verwendet wird.

sdpFmtpLine Optional

Ein String, der die von der lokalen Beschreibung bereitgestellten formatspezifischen Parameter angibt.

headerExtensions

Ein Array aus null oder mehr RTP-Header-Erweiterungen, von denen jede eine vom Sender unterstützte Erweiterung identifiziert. Header-Erweiterungen werden in RFC 3550, Abschnitt 5.3.1 beschrieben. Dieser Parameter kann nicht geändert werden.

rtcp

Ein Objekt, das die Konfigurationsparameter für RTCP beim Sender bereitstellt. Dieser Parameter kann nicht geändert werden.

Das Objekt kann die folgenden Eigenschaften haben:

cname

Ein schreibgeschützter String, der den von RTCP verwendeten kanonischen Namen (CNAME) angibt, etwa in SDES-Nachrichten.

reducedSize

Ein schreibgeschützter boolescher Wert, der True ist, wenn RTCP mit reduzierter Größe konfiguriert ist (RFC 5506), und False, wenn zusammengesetztes RTCP angegeben ist (RFC 3550).

degradationPreference Optional

Gibt die bevorzugte Weise an, auf die die WebRTC-Schicht die Leistungsoptimierung in Situationen mit eingeschränkter Bandbreite handhaben soll. Die möglichen Werte sind:

balanced

Der Standardwert. Der Browser gleicht die Verringerung von Framerate und Auflösung aus.

maintain-framerate

Der Browser verringert die Auflösung, um die Framerate beizubehalten.

maintain-resolution

Der Browser verringert die Framerate, um die Auflösung beizubehalten.

maintain-framerate-and-resolution

Der Browser behält Framerate und Auflösung unabhängig von der Videoqualität bei. Dies kann dazu führen, dass Frames bei Bedarf vor der Kodierung verworfen werden, um Netzwerk- und Encoder-Ressourcen nicht übermäßig zu beanspruchen. Diese Einstellung ist für Anwendungen nützlich, die ihren eigenen Mechanismus zur Optimierung von Videokodierungsqualität und -leistung implementieren und nicht möchten, dass der interne Mechanismus des Browsers diesen beeinträchtigt.

Rückgabewert

Ein Promise, das erfüllt wird, wenn die Eigenschaft RTCRtpSender.track mit den angegebenen Parametern aktualisiert wird.

Ausnahmen

Wenn ein Fehler auftritt, wird das zurückgegebene Promise mit der passenden Ausnahme aus der folgenden Liste abgelehnt.

InvalidModificationError DOMException

Wird zurückgegeben, wenn eines der folgenden Probleme erkannt wird:

• Die Anzahl der in der Eigenschaft encodings des Objekts parameters angegebenen Kodierungen stimmt nicht mit der Anzahl der aktuell für den RTCRtpSender aufgeführten Kodierungen überein. Sie können die Anzahl der Kodierungsoptionen nicht ändern, nachdem der Sender erstellt wurde.
• Die Reihenfolge der angegebenen encodings wurde gegenüber der Reihenfolge der aktuellen Liste geändert.
• Es wurde versucht, eine Eigenschaft zu ändern, die nach der ersten Erstellung des Senders nicht mehr geändert werden kann.

InvalidStateError DOMException

Wird zurückgegeben, wenn der Transceiver, zu dem der RTCRtpSender gehört, nicht läuft oder keine festzulegenden Parameter hat.

OperationError DOMException

Wird zurückgegeben, wenn ein Fehler auftritt, der keinem der hier angegebenen Fehler entspricht.

RangeError

Wird zurückgegeben, wenn der für die Option scaleResolutionDownBy angegebene Wert kleiner als 1.0 ist — was zu einer Vergrößerung statt zu einer Verkleinerung führen würde und nicht zulässig ist — oder wenn einer oder mehrere der angegebenen maxFramerate-Werte von encodings kleiner als 0.0 sind.

Wenn außerdem ein WebRTC-Fehler beim Konfigurieren oder Zugreifen auf die Medien auftritt, wird ein RTCError ausgelöst, dessen errorDetail auf hardware-encoder-error gesetzt ist.

Beschreibung

Es ist wichtig, zu beachten, dass Sie das Objekt parameters nicht selbst erstellen und erwarten können, dass es funktioniert. Stattdessen müssen Sie zuerst getParameters() aufrufen, das empfangene Parameterobjekt ändern und dieses Objekt dann an setParameters() übergeben. WebRTC verwendet die Eigenschaft transactionId des Parameterobjekts, um sicherzustellen, dass Ihre Änderungen beim Festlegen von Parametern auf den aktuellsten Parametern und nicht auf einer veralteten Konfiguration basieren.

Beispiele

Ein Anwendungsfall für setParameters() besteht darin, zu versuchen, die in Umgebungen mit eingeschränkter Bandbreite verwendete Netzwerkbandbreite zu reduzieren, indem die Auflösung und/oder Bitrate der vom RTCRtpSender übertragenen Medien geändert wird.

Derzeit haben einige Browser Einschränkungen in ihren Implementierungen, die Probleme verursachen können. Aus diesem Grund werden hier zwei Beispiele angegeben. Das erste zeigt, wie setParameters() verwendet wird, wenn alle Browser die verwendeten Parameter vollständig unterstützen, während das zweite Beispiel Workarounds zur Behebung von Einschränkungen in Browsern mit unvollständiger Unterstützung für die Parameter maxBitrate und scaleResolutionDownBy zeigt.

Gemäß der Spezifikation

Sobald alle Browser die Spezifikation vollständig implementieren, erledigt diese Implementierung von setVideoParams() die Aufgabe. Sie zeigt, wie alles funktionieren sollte. Vorerst sollten Sie wahrscheinlich das zweite Beispiel weiter unten verwenden. Dieses Beispiel veranschaulicht jedoch klarer das Grundkonzept: zuerst die Parameter abrufen, dann ändern und anschließend festlegen.

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

Beim Aufrufen dieser Funktion geben Sie einen Sender sowie die Höhe an, auf die Sie das Video des Senders skalieren möchten, und außerdem eine maximale Bitrate, mit der der Sender übertragen darf. Es wird ein Skalierungsfaktor für die Größe des Videos, scaleRatio, berechnet. Anschließend werden die aktuellen Parameter des Senders mit getParameters() abgerufen.

Die Parameter werden dann geändert, indem scaleResolutionDownBy und maxBitrate des ersten Objekts in encodings auf den berechneten Skalierungsfaktor bzw. die angegebene maximale bitrate gesetzt werden.

Die geänderten Parameter werden anschließend durch Aufrufen der Methode setParameters() des Senders gespeichert.

Derzeit kompatible Implementierung

Wie oben erwähnt, zeigt das vorherige Beispiel, wie die Funktionsweise vorgesehen ist. Leider verhindern Implementierungsprobleme dies derzeit in vielen Browsern. Wenn Sie daher mit iPhone und anderen Geräten mit Safari sowie mit Firefox kompatibel sein möchten, verwenden Sie Code, der eher diesem entspricht:

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

Die Unterschiede:

• Wenn encodings null ist, erstellen wir es, um sicherzustellen, dass wir die Parameter anschließend erfolgreich festlegen können, ohne abzustürzen.
• Wenn der Wert von scaleResolutionDownBy nach dem Festlegen der Parameter weiterhin 1 ist, rufen wir die Methode applyConstraints() des Tracks des Senders auf, um die Höhe des Tracks auf height zu beschränken. Dies gleicht ein nicht implementiertes scaleResolutionDownBy aus (wie es zum Zeitpunkt der Erstellung dieses Textes bei Safari der Fall ist).

Dieser Code greift sauber auf die normale Funktionsweise zurück und funktioniert auf diese Weise, wenn der Browser die verwendeten Funktionen vollständig implementiert.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• WebRTC API
• Von WebRTC verwendete Codecs
• Web-Medientechnologien