RTCRtpSender: Methode setParameters()
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
* Some parts of this feature may have varying levels of support.
Die setParameters()
-Methode des RTCRtpSender
-Interfaces ändert die Konfiguration des Senderstrack
, welches das MediaStreamTrack
ist, für das der RTCRtpSender
verantwortlich ist.
Mit anderen Worten, setParameters()
aktualisiert die Konfiguration der RTP-Übertragung sowie die Kodierungskonfiguration für einen bestimmten ausgehenden Medientrack in der WebRTC-Verbindung.
Syntax
setParameters(parameters)
Parameter
parameters
-
Ein Parameterobjekt, das zuvor durch Aufruf der gleichen Methode des Senders
getParameters()
erhalten wurde, mit den gewünschten Änderungen an den Konfigurationsparametern des Senders. Diese Parameter umfassen potenzielle Codecs, die zur Kodierung des Senderstrack
verwendet werden könnten. Die verfügbaren Parameter sind:encodings
-
Ein Array von Objekten, von denen jedes die Parameter für einen einzelnen Codec spezifiziert, der zur Kodierung des Medieninhalts des Tracks verwendet werden könnte. Die Eigenschaften der Objekte sind:
active
-
Festlegen dieses Wertes auf
true
(Standard) bewirkt, dass diese Kodierung gesendet wird, währendfalse
das Senden und Verwenden verhindert (aber nicht dazu führt, dass die SSRC entfernt wird). dtx
Veraltet Nicht standardisiert-
Nur verwendet für einen
RTCRtpSender
, dessenkind
audio
ist. Diese Eigenschaft gibt an, ob eine diskontinuierliche Übertragung verwendet werden soll (eine Funktion, bei der ein Telefon ausgeschaltet oder das Mikrofon automatisch stummgeschaltet wird, wenn keine Sprachaktivität vorliegt). Der Wert kann entwederenabled
oderdisabled
sein. maxBitrate
-
Eine positive Ganzzahl, die die maximale Anzahl von Bits pro Sekunde angibt, die der Benutzer-Agent Tracks zuweisen darf, die mit dieser Kodierung kodiert sind. Andere Parameter können die Bitrate weiter einschränken, wie z. B. der Wert von
maxFramerate
oder die für den Transport oder das physische Netzwerk verfügbare Bandbreite.Der Wert wird unter Verwendung des standardmäßigen Transport Independent Application Specific Maximum (TIAS) Bandbreite, wie definiert von RFC 3890, Abschnitt 6.2.2, berechnet; dies ist die maximale benötigte Bandbreite, ohne Protokolloverheads von IP, TCP oder UDP zu berücksichtigen usw.
Beachten Sie, dass die Bitrate auf verschiedene Weise erreicht werden kann, abhängig von den Medien und der Kodierung. Zum Beispiel könnte für Video eine niedrige Bitrate durch das Herunterfallen von Frames erreicht werden (eine Bitrate von null könnte nur einen Frame erlauben), während der Track bei Audio aufhören muss zu spielen, wenn die Bitrate zu niedrig ist, um gesendet zu werden.
maxFramerate
-
Ein Wert, der die maximale Anzahl von Frames pro Sekunde angibt, die für diese Kodierung zugelassen sind.
priority
-
Ein String, der die Priorität des
RTCRtpSender
angibt und möglicherweise bestimmt, wie der Benutzer-Agent die Bandbreite zwischen Sendern verteilt. Zulässige Werte sindvery-low
,low
(Standard),medium
,high
. rid
-
Ein String, der, wenn gesetzt, eine RTP stream ID (RID) angibt, die mit der RID-Headererweiterung gesendet wird. Dieser Parameter kann nicht mit
setParameters()
geändert werden. Sein Wert kann nur gesetzt werden, wenn der Transceiver zuerst erstellt wird. scaleResolutionDownBy
-
Nur verwendet für Sender, deren Track-
kind
video
ist, handelt es sich um einen Gleitkommawert, der einen Faktor angibt, um den das Video während der Kodierung verkleinert werden soll. Der Standardwert, 1.0, bedeutet, dass das Video in seiner ursprünglichen Größe kodiert wird. Ein Wert von 2.0 skaliert die Video-Frames um einen Faktor von 2 in jeder Dimension herunter, was zu einem Video führt, das 1/4 der ursprünglichen Größe beträgt. Der Wert darf nicht kleiner als 1.0 sein (der Versuch, das Video auf eine größere Größe zu skalieren, führt zu einemRangeError
).
transactionId
-
Ein String, der eine eindeutige ID enthält. Diese ID wird im vorherigen Aufruf von
getParameters()
gesetzt und stellt sicher, dass die Parameter von einem vorherigen Aufruf vongetParameters()
stammen. codecs
-
Ein Array von Objekten, die die Mediencodecs beschreiben, aus denen der Sender wählen wird. Dieser Parameter kann nicht geändert werden, nachdem er zuerst gesetzt wurde.
Jedes Codec-Objekt im Array kann folgende Eigenschaften haben:
channels
Optional-
Eine positive Ganzzahl, die die Anzahl der vom Codec unterstützten Kanäle angibt. Zum Beispiel gibt bei Audiocodecs ein Wert von 1 Mono-Sound an, während 2 Stereo bedeutet.
clockRate
-
Eine positive Ganzzahl, die die Taktfrequenz des Codecs in Hertz (Hz) angibt. Die Taktfrequenz ist die Rate, mit der der RTP-Zeitstempel des Codecs fortschreitet. Die meisten Codecs haben spezifische Werte oder Bereichswerte, die sie zulassen. Die IANA pflegt eine Liste von Codecs und ihren Parametern, einschließlich ihrer Taktfrequenzen.
mimeType
-
Ein String, der den MIME-Medientyp und Subtyp des Codecs angibt, spezifiziert als ein String in der Form
"type/subtype"
. Die im RTP verwendeten MIME-Typ-Strings unterscheiden sich von denen, die anderswo verwendet werden. Die IANA pflegt ein Register gültiger MIME-Typen. Siehe auch Codecs used by WebRTC für Details über potenzielle Codecs, die hier referenziert werden könnten. payloadType
-
Der RTP-Payload-Typ, der zur Identifizierung dieses Codecs verwendet wird.
sdpFmtpLine
Optional-
Ein String, der die format spezifischen Parameter angibt, die von der lokalen Beschreibung bereitgestellt werden.
headerExtensions
-
Ein Array von null oder mehr RTP-Headererweiterungen, die jeweils eine Erweiterung identifizieren, die vom Sender unterstützt wird. Header-Erweiterungen sind beschrieben in RFC 3550, Abschnitt 5.3.1. Dieser Parameter kann nicht geändert werden.
rtcp
-
Ein
RTCRtcpParameters
-Objekt, das die Konfigurationsparameter angibt, die für RTCP beim Sender verwendet werden. Dieser Parameter kann nicht geändert werden. degradationPreference
Veraltet-
Gibt an, wie die WebRTC-Schicht bevorzugt die Bandbreite gegenüber der Qualität in Situationen mit eingeschränkter Bandbreite optimieren soll. Die möglichen Werte sind
maintain-framerate
,maintain-resolution
oderbalanced
. Der Standardwert istbalanced
.
Rückgabewert
Ein Promise
, das aufgelöst wird, wenn die RTCRtpSender.track
-Eigenschaft mit den angegebenen Parametern aktualisiert wird.
Ausnahmen
Tritt ein Fehler auf, wird das zurückgegebene Promise mit der entsprechenden Ausnahme aus der unten stehenden Liste abgelehnt.
InvalidModificationError
DOMException
-
Wird zurückgegeben, wenn eines der folgenden Probleme erkannt wird:
- Die Anzahl der im
parameters
-Objekt angegebenenencodings
stimmt nicht mit der aktuell für denRTCRtpSender
aufgeführten Anzahl von Kodierungen überein. Sie können die Anzahl der Kodierungsoptionen nicht ändern, nachdem der Sender erstellt wurde. - Die Reihenfolge der angegebenen
encodings
hat sich von der Reihenfolge der aktuellen Liste geändert. - Es wurde versucht, eine Eigenschaft zu ändern, die nach der ersten Erstellung des Senders nicht geändert werden kann.
- Die Anzahl der im
InvalidStateError
DOMException
-
Wird zurückgegeben, wenn der Transceiver, zu dem der
RTCRtpSender
gehört, nicht aktiv ist oder keine Parameter zu setzen hat. OperationError
DOMException
-
Wird zurückgegeben, wenn ein Fehler auftritt, der nicht den hier angegebenen entspricht.
RangeError
-
Wird zurückgegeben, wenn der angegebene Wert für die
scaleResolutionDownBy
-Option weniger als 1.0 beträgt – was zu einer Hochskalierung anstatt einer Skalierung nach unten führen würde, was nicht erlaubt ist; oder wenn einer oder mehrere der angegebenenencodings
-maxFramerate
-Werte weniger als 0.0 sind.
Darüber hinaus wird, wenn ein WebRTC-Fehler beim Konfigurieren oder Zugreifen auf das Medium auftritt, ein RTCError
mit dessen errorDetail
auf hardware-encoder-error
gesetzt ausgelöst.
Beschreibung
Es ist wichtig zu beachten, dass Sie das parameters
-Objekt nicht selbst erstellen können und erwarten können, dass es funktioniert.
Stattdessen müssen Sie zuerst getParameters()
aufrufen, das empfangene Parameterobjekt ändern und dann dieses Objekt an setParameters()
übergeben.
WebRTC verwendet die transactionId
-Eigenschaft des Parameterobjekts, um sicherzustellen, dass Ihre Änderungen auf den neuesten Parametern basieren, anstatt auf einer veralteten Konfiguration.
Beispiele
Ein Anwendungsfall für setParameters()
besteht darin, den Netzwerkbandbreitenbedarf in begrenzten Umgebungen zu reduzieren, indem die Auflösung und/oder die Bitrate der Medien, die vom RTCRtpSender
gesendet werden, geändert werden.
Derzeit haben einige Browser Einschränkungen in ihren Implementierungen, die Probleme verursachen können.
Aus diesem Grund werden hier zwei Beispiele gegeben.
Das erste zeigt, wie setParameters()
verwendet werden sollte, wenn alle Browser die verwendeten Parameter vollständig unterstützen, während das zweite Beispiel Lösungen zeigt, um die Einschränkungen in Browsern mit unvollständiger Unterstützung für die Parameter maxBitrate
und scaleResolutionDownBy
zu überwinden.
Entsprechend der Spezifikation
Sobald alle Browser die Spezifikation vollständig implementieren, wird diese Implementierung von setVideoParams()
die Aufgabe erfüllen. Dies zeigt, wie alles funktionieren sollte.
Sie sollten wahrscheinlich das zweite Beispiel unten verwenden, für jetzt.
Aber dies ist eine klarere Darstellung des grundlegenden Konzepts, zunächst die Parameter abzurufen, dann sie zu ändern und sie dann zu setzen.
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 Aufruf dieser Funktion geben Sie einen Sender an sowie die Höhe, auf die Sie das Video des Senders skalieren möchten, und eine maximale Bitrate, die dem Sender erlaubt, die zu übertragen.
Ein Skalierungsfaktor für die Größe des Videos, scaleRatio
, wird berechnet.
Dann werden die aktuellen Parameter des Senders durch die Verwendung von getParameters()
abgerufen.
Die Parameter werden dann geändert, indem das erste encodings
-Objekts [
scaleResolutionDownBy](#scaleresolutiondownby) und [
maxBitrate](#maxbitrate) auf den berechneten Skalierungsfaktor und die angegebene maximale
bitrate` geändert werden.
Die geänderten Parameter werden dann gespeichert, indem die setParameters()
-Methode des Senders aufgerufen wird.
Aktuell kompatible Implementierung
Wie oben erwähnt, zeigt das vorherige Beispiel, wie die Dinge funktionieren sollen. Leider gibt es derzeit Implementierungsprobleme, die dies in vielen Browsern verhindern. Aus diesem Grund sollten Sie, wenn Sie kompatibel mit dem iPhone und anderen Geräten sein möchten, die Safari und Firefox ausführen, einen Code verwenden, der eher so aussieht:
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 });
}
}
Die Unterschiede hier:
- Wenn
encodings
null
ist, erstellen wir es, um sicherzustellen, dass wir die Parameter erfolgreich ohne Abstürze setzen können. - Wenn der Wert von
scaleResolutionDownBy
nach dem Setzen der Parameter immer noch 1 ist, rufen wir dieapplyConstraints()
-Methode des Tracks des Senders auf, um die Höhe des Tracks aufheight
zu beschränken. Dies kompensiert für eine unimplementiertescaleResolutionDownBy
(wie es zum Zeitpunkt des Schreibens in Safari der Fall ist).
Dieser Code wird sauber zurückfallen und den normalen Weg funktionieren, wenn der Browser die verwendeten Funktionen vollständig implementiert.
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcrtpsender-setparameters |
Browser-Kompatibilität
BCD tables only load in the browser