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() des Interfaces 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 derjenigen, die für Neuübertragung, Redundanz und Vorwärtsfehlerkorrektur verwendet werden. Codecs, die nicht in der Präferenzliste enthalten sind, sind nicht Teil der Aushandlung. 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 Vorgehensweise 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 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 die für Neuübertragung, Redundanz und Vorwärtsfehlerkorrektur erforderlichen Codecs enthält.
Die angegebene Gruppe 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 hierfür bereits über Code im negotiationneeded-Event-Handler.
Beachten Sie jedoch, dass das Event zum Zeitpunkt der Erstellung dieses Dokuments nicht automatisch ausgelöst wird, wenn Sie setCodecPreferences() aufrufen. Sie müssen daher onnegotiationneeded 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, sortiert nach Präferenz. Wenn
codecsleer ist, werden alle Codec-Konfigurationen auf die Standardwerte des User-Agents zurückgesetzt.Hinweis: Codecs, die nicht in
codecsenthalten sind, werden beim Aushandeln einer Verbindung nicht berücksichtigt. Damit 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 ganze Zahl, die die Anzahl der vom Codec unterstützten Kanäle angibt. Bei Audio-Codecs gibt beispielsweise ein Wert von 1 monauralen Klang an, während 2 Stereo angibt.
clockRate-
Eine positive ganze Zahl, 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 erlauben bestimmte Werte oder Wertebereiche. Die IANA führt eine Liste von Codecs und ihren Parametern, einschließlich ihrer Clock-Rates.
mimeType-
Ein String, der den MIME-Medientyp und -Untertyp des Codecs angibt, im Format
"type/subtype". Die von RTP verwendeten MIME-Type-Strings unterscheiden sich von denen, die andernorts verwendet werden. Die IANA führt ein Register gültiger MIME-Typen. Weitere Informationen zu möglichen Codecs, auf die hier verwiesen werden könnte, finden Sie auch unter Von WebRTC verwendete Codecs. sdpFmtpLineOptional-
Ein String, der das formatspezifische Parameterfeld aus der dem Codec entsprechenden
a=fmtp-Zeile in der SDP enthält, falls das Feld vorhanden ist. Wenn kein Parameterfeld vorhanden ist, wird diese Eigenschaft weggelassen.
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 das Medium enthalten.
Beispiele
Erstellen des Arrays bevorzugter Codecs
Die empfohlene Vorgehensweise 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 verknüpften RTCRtpReceiver nicht unterstützt werden, löst der Browser beim Aufruf der Methode setCodecPreferences() eine Ausnahme vom Typ InvalidAccessError aus.
Zusätzlich muss das Array geeignete Codecs für Neuübertragung, Redundanz und Vorwärtsfehlerkorrektur enthalten. Wenn Sie mit der Liste der unterstützten Codecs beginnen, wird sichergestellt, dass diese vorhanden sind.
Sie können die für das Dekodieren von Daten unterstützten Codecs mit 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 folgende Sortierfunktion verwenden, um nach MIME-Typ zu sortieren (diese 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 übernimmt die Liste unterstützter Codecs und ein Array mit den bevorzugten MIME-Typen in absteigender Reihenfolge und gibt das an Ort und Stelle sortierte Array zurück.
Der folgende Code zeigt, wie dies verwendet wird, unter der Annahme, dass Sie bereits eine Peer-Verbindung (peerConnection) eingerichtet haben:
// 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 |