RTCRtpTransceiver: Methode setCodecPreferences()
Baseline 2024
Neu verfügbar
Seit Juli 2024 funktioniert diese Funktion auf aktuellen Geräten und in aktuellen Browserversionen. Auf älteren Geräten oder in älteren Browsern funktioniert sie möglicherweise nicht.
Die Methode setCodecPreferences() der Schnittstelle RTCRtpTransceiver wird verwendet, um die Codecs festzulegen, die der Transceiver zum Dekodieren empfangener Daten zulässt, in absteigender Präferenzreihenfolge.
Die mit dieser Methode festgelegten Präferenzen beeinflussen, welche Codecs mit dem Remote-Peer für die Kodierung der von ihm gesendeten Daten ausgehandelt werden, einschließlich der für Neuübertragung, Redundanz und Vorwärtsfehlerkorrektur verwendeten Codecs. Codecs, die nicht in der Präferenzliste enthalten sind, werden nicht Teil der Aushandlung sein. Beachten Sie, dass die von diesem Transceiver zum Senden von Inhalten verwendeten Präferenzen von den Präferenzen des Remote-Peers abhängen.
Die empfohlene Methode zum Festlegen von Codec-Präferenzen besteht darin, zunächst das Array von Codecs abzurufen, die tatsächlich zum Dekodieren empfangener Daten unterstützt werden, und sie dann in absteigender Präferenzreihenfolge neu anzuordnen. Dadurch wird sichergestellt, dass das Array wie erforderlich sortiert ist, keine nicht unterstützten Codecs enthält und auch Codecs umfasst, die für Neuübertragung, Redundanz und Vorwärtsfehlerkorrektur benötigt werden.
Der angegebene Satz von Codecs wird für alle zukünftigen Verbindungen verwendet, die diesen Transceiver einschließen, bis diese Methode erneut aufgerufen wird.
Bei der Vorbereitung zum Öffnen einer RTCPeerConnection sollten die Codecs mit setCodecPreferences() festgelegt werden, bevor entweder RTCPeerConnection.createOffer() oder createAnswer() aufgerufen wird, da diese die Aushandlung starten (und standardmäßig Codec-Parameter aus der Standardkonfiguration des User-Agents verwenden).
Die Codecs können während einer laufenden Kommunikation geändert werden, aber Sie müssen zuerst setCodecPreferences() aufrufen und dann eine neue Aushandlung starten.
Eine WebRTC-Anwendung verfügt bereits über Code dafür im Event-Handler für das Ereignis negotiationneeded.
Beachten Sie jedoch, dass das Ereignis zum Zeitpunkt der Erstellung dieses Dokuments nicht automatisch ausgelöst wird, wenn Sie setCodecPreferences() aufrufen. Sie müssen onnegotiationneeded daher selbst aufrufen.
Einen Leitfaden zu den von WebRTC unterstützten Codecs – und den positiven und negativen Eigenschaften jedes Codecs – finden Sie unter Von WebRTC verwendete Codecs.
Syntax
setCodecPreferences(codecs)
Parameter
codecs-
Ein Array von Objekten, die jeweils die Parameter für einen der vom Transceiver unterstützten Medien-Codecs bereitstellen, nach Präferenz sortiert. Wenn
codecsleer ist, werden alle Codec-Konfigurationen auf die Standardwerte des User-Agents zurückgesetzt.Hinweis: Alle Codecs, die nicht in
codecsenthalten sind, werden während der Aushandlung einer Verbindung nicht berücksichtigt. Dadurch können Sie die Verwendung von Codecs verhindern, die Sie nicht verwenden möchten.Jedes Codec-Objekt im Array hat die folgenden Eigenschaften:
channelsOptional-
Eine positive Ganzzahl, die die Anzahl der vom Codec unterstützten Kanäle angibt. Bei Audio-Codecs gibt beispielsweise der Wert 1 monauralen Klang an, während 2 Stereo angibt.
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 Wertebereiche, 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 String der Form
"type/subtype". Die von RTP verwendeten MIME-Typ-Strings unterscheiden sich von denen, die andernorts 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. sdpFmtpLineOptional-
Ein String, der das formatspezifische Parameterfeld aus der
a=fmtp-Zeile in der SDP angibt, das dem Codec entspricht, sofern das Feld vorhanden ist. Wenn es kein Parameterfeld gibt, wird diese Eigenschaft ausgelassen.
Rückgabewert
Keiner (undefined).
Ausnahmen
InvalidAccessErrorDOMException-
Die Liste
codecsenthält einen oder mehrere Codecs, die vom mit dem Transceiver verknüpftenRTCRtpReceivernicht unterstützt werden. InvalidModificationErrorDOMException-
Die Liste
codecsenthält nur Einträge für RTX, RED, FEC oder Comfort Noise oder ist eine leere Menge. Die Codecs müssen immer einen Codec für die Medien enthalten.
Beispiele
Erstellen des Arrays bevorzugter Codecs
Die empfohlene Methode zum Festlegen von Codec-Präferenzen besteht darin, zunächst das Array der Codecs abzurufen, die tatsächlich zum Dekodieren empfangener Daten unterstützt werden, und die Liste dann in absteigender Präferenzreihenfolge neu anzuordnen.
Es ist wichtig, mit der Liste der unterstützten Codecs zu beginnen (und nicht mit einer fest codierten Liste Ihrer bevorzugten Codecs), denn wenn Sie Codecs einschließen, die vom zugehörigen RTCRtpReceiver nicht unterstützt werden, löst der Browser beim Aufruf der Methode setCodecPreferences() eine InvalidAccessError-Ausnahme aus.
Außerdem muss das Array geeignete Codecs für Neuübertragung, Redundanz und Vorwärtsfehlerkorrektur enthalten; mit der Liste der unterstützten Codecs zu beginnen, stellt sicher, dass diese vorhanden sind.
Sie können die für die Dekodierung von Daten unterstützten Codecs mithilfe der statischen Methode RTCRtpReceiver.getCapabilities() abrufen, wie gezeigt:
const availReceiveCodecs = transceiver.receiver.getCapabilities("video").codecs;
Um das Codec-Array in unsere bevorzugte Reihenfolge zu bringen, können wir die untenstehende Sortierfunktion verwenden, um nach MIME-Typ zu sortieren (sie stammt aus setCodecPreferences is now in all browsers! auf blog.mozilla.org (2024)).
function sortByMimeTypes(codecs, preferredOrder) {
return codecs.sort((a, b) => {
const indexA = preferredOrder.indexOf(a.mimeType);
const indexB = preferredOrder.indexOf(b.mimeType);
const orderA = indexA >= 0 ? indexA : Number.MAX_VALUE;
const orderB = indexB >= 0 ? indexB : Number.MAX_VALUE;
return orderA - orderB;
});
}
Die Methode nimmt die Liste der unterstützten Codecs und ein Array mit den bevorzugten MIME-Typen in absteigender Reihenfolge entgegen und gibt das an Ort und Stelle sortierte Array zurück.
Der folgende Code zeigt, wie dies verwendet wird, vorausgesetzt, Sie haben bereits eine Peer-Verbindung (peerConnection) eingerichtet:
// Get supported codecs the sort using preferred codecs
const supportedCodecs = RTCRtpReceiver.getCapabilities("video").codecs;
const preferredCodecs = ["video/H264", "video/VP8", "video/VP9"];
const sortedCodecs = sortByMimeTypes(supportedCodecs, preferredCodecs);
// Get transceiver for connection and set the preferences
const [transceiver] = peerConnection.getTransceivers();
transceiver.setCodecPreferences(sortedCodecs); // <---
Spezifikationen
| Spezifikation |
|---|
| WebRTC: Real-Time Communication in Browsers # dom-rtcrtptransceiver-setcodecpreferences |