RTCRtpTransceiver: setCodecPreferences() Methode

Baseline 2024
Newly available

Since July 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Die setCodecPreferences()-Methode der RTCRtpTransceiver-Schnittstelle 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 entfernten Peer zum Encodieren der gesendeten Daten ausgehandelt werden, einschließlich derjenigen, die für Wiederübertragung, Redundanz und Vorwärtsfehlerkorrektur verwendet werden. Codecs, die nicht in der Präferenzliste enthalten sind, werden nicht Teil der Verhandlung sein. Beachten Sie, dass die Präferenzen, die dieser Transceiver für das Senden von Inhalten verwendet, von den Präferenzen des entfernten Peers abhängen.

Der empfohlene Weg, um Codec-Präferenzen festzulegen, besteht darin, zuerst das Array der Codecs zu holen, die tatsächlich zum Dekodieren empfangener Daten unterstützt werden, und dann diese in absteigender Präferenzordnung neu zu ordnen. Dies stellt sicher, dass das Array in der erforderlichen Reihenfolge geordnet ist, keine nicht unterstützten Codecs enthält und auch die Codecs umfasst, die für Wiederübertragung, Redundanz und Vorwärtsfehlerkorrektur benötigt werden.

Die angegebene Menge an Codecs wird für alle zukünftigen Verbindungen verwendet, die diesen Transceiver beinhalten, bis diese Methode erneut aufgerufen wird.

Beim Vorbereiten der Eröffnung einer RTCPeerConnection sollten die Codecs mit setCodecPreferences() vor dem Aufruf von entweder RTCPeerConnection.createOffer() oder createAnswer() festgelegt werden, da diese die Verhandlung initiieren (und standardmäßig Codec-Parameter aus der Benutzeragentur Standardkonfiguration verwenden).

Die Codecs können geändert werden, wenn Sie eine laufende Kommunikation haben, aber Sie müssen zuerst setCodecPreferences() aufrufen und dann eine neue Verhandlung einleiten. Eine WebRTC-Anwendung wird dafür bereits Code im negotiationneeded Event-Handler haben. Beachten Sie jedoch, dass zum Zeitpunkt des Schreibens das Ereignis nicht automatisch ausgelöst wird, wenn Sie setCodecPreferences() aufrufen, daher müssen Sie onnegotiationneeded selbst aufrufen.

Ein Leitfaden zu den von WebRTC unterstützten Codecs—und den positiven und negativen Eigenschaften jedes Codecs—finden Sie unter Codecs used by WebRTC.

Syntax

js
setCodecPreferences(codecs)

Parameter

codecs

Ein Array von Objekten, die jeweils die Parameter eines der vom Transceiver unterstützten Mediencodecs bereitstellen, in Präferenzreihenfolge sortiert. Wenn codecs leer ist, werden die Codec-Konfigurationen auf die Standardeinstellungen der Benutzeragentur zurückgesetzt.

Hinweis: Alle Codecs, die nicht in codecs enthalten sind, werden bei der Aushandlung einer Verbindung nicht berücksichtigt. So können Sie die Verwendung von Codecs verhindern, die Sie nicht verwenden möchten.

Jedes Codec-Objekt im Array hat die folgenden Eigenschaften:

channels Optional

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

clockRate

Eine positive ganze Zahl, die die Abtastrate des Codecs in Hertz (Hz) angibt. Die Abtastrate ist die Rate, mit der der RTP-Zeitstempel des Codecs fortschreitet. Die meisten Codecs haben spezifische Werte oder Wertebereiche, die sie zulassen. Die IANA führt eine Liste von Codecs und ihren Parametern, einschließlich ihrer Abtastraten.

mimeType

Eine Zeichenkette, die den MIME-Medientyp und -Untertyp des Codecs angibt und als Zeichenkette in der Form "type/subtype" spezifiziert ist. Die MIME-Typzeichenketten, die von RTP verwendet werden, unterscheiden sich von denen, die anderswo verwendet werden. Die IANA führt ein Register gültiger MIME-Typen. Siehe auch Codecs used by WebRTC für weitere Informationen zu potenziellen Codecs, die hier referenziert werden könnten.

sdpFmtpLine Optional

Eine Zeichenkette, die das formatspezifische Parameterfeld von der a=fmtp-Zeile im SDP angibt, das dem Codec entspricht, falls vorhanden. Wenn kein Parameterfeld vorhanden ist, wird diese Eigenschaft weggelassen.

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidAccessError DOMException

Die codecs-Liste enthält einen oder mehrere Codecs, die vom RTCRtpReceiver, der dem Transceiver zugeordnet ist, nicht unterstützt werden.

InvalidModificationError DOMException

Die codecs-Liste enthält nur Einträge für RTX, RED, FEC oder Comfort Noise oder ist ein leeres Set. Die Codecs müssen immer einen Codec für die Medien enthalten.

Beispiele

Das Array bevorzugter Codecs erstellen

Der empfohlene Weg, um Codec-Präferenzen festzulegen, besteht darin, zuerst das Array der Codecs zu holen, die tatsächlich zum Dekodieren empfangener Daten unterstützt werden, und dann die Liste in absteigender Präferenzordnung neu zu ordnen.

Es ist wichtig, mit der Liste der unterstützten Codecs zu beginnen (und nicht mit einer fest kodierten Liste Ihrer bevorzugten Codecs), da der Browser eine InvalidAccessError-Ausnahme wirft, wenn Sie einen einbeziehen, der vom zugehörigen RTCRtpReceiver nicht unterstützt wird, wenn Sie die setCodecPreferences()-Methode aufrufen. Außerdem muss das Array geeignete Codecs für Wiederübertragung, Redundanz und Vorwärtsfehlerkorrektur enthalten, und der Start mit der Liste der unterstützten Codecs stellt sicher, dass diese vorhanden sind.

Sie können die Codecs, die zum Dekodieren von Daten unterstützt werden, mit der statischen Methode RTCRtpReceiver.getCapabilities() abrufen, wie unten gezeigt:

js
const availReceiveCodecs = transceiver.receiver.getCapabilities("video").codecs;

Um das Codec-Array in unserer bevorzugten Reihenfolge neu zu ordnen, können wir die unten stehende Sortierungsmethode verwenden, um nach MIME-Typ zu sortieren (dies stammt aus setCodecPreferences is now in all browsers! auf blog.mozilla.org (2024)).

js
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 und gibt das in-place sortierte Array zurück. Der folgende Code zeigt, wie dies verwendet wird, vorausgesetzt, Sie haben bereits eine Peerverbindung (peerConnection) eingerichtet:

js
// 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

Specification
WebRTC: Real-Time Communication in Browsers
# dom-rtcrtptransceiver-setcodecpreferences

Browser-Kompatibilität

Siehe auch