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 von empfangenen Daten in absteigender Präferenzreihenfolge zulässt.

Die mit dieser Methode festgelegten Präferenzen beeinflussen, welche Codecs mit dem entfernten Peer für die Codierung der gesendeten Daten ausgehandelt werden, einschließlich derjenigen, die für die Übertragung, Redundanz und Fehlerkorrektur verwendet werden. Codecs, die nicht in der Präferenzliste enthalten sind, werden nicht Teil der Verhandlungen sein. Beachten Sie, dass die von diesem Transceiver verwendeten Präferenzen für das Senden von Inhalten von den Präferenzen des entfernten Peers abhängen.

Der empfohlene Weg, um die Codec-Präferenzen festzulegen, besteht darin, zuerst das Array der tatsächlich für das Dekodieren empfangener Daten unterstützten Codecs zu erhalten und sie dann in absteigender Präferenzreihenfolge neu zu ordnen. Dies stellt sicher, dass das Array in der erforderlichen Reihenfolge angeordnet ist, keine nicht unterstützten Codecs enthält und auch die benötigten Codecs für die Übertragung, Redundanz und Fehlerkorrektur enthält.

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

Beim Vorbereiten der Ö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 die Codec-Parameter aus der Standardkonfiguration des User Agents 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 initiieren. Eine WebRTC-Anwendung wird bereits Code dafür im negotiationneeded-Ereignishandler haben. Beachten Sie jedoch, dass zum Zeitpunkt der Erstellung dieses Dokuments das Ereignis nicht automatisch ausgelöst wird, wenn Sie setCodecPreferences() aufrufen. Sie müssen also onnegotiationneeded selbst aufrufen.

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

Syntax

js
setCodecPreferences(codecs)

Parameter

codecs

Ein Array von Objekten, die die Parameter für einen der vom Transceiver unterstützten Mediencodecs in der Reihenfolge der Präferenz bereitstellen. Wenn codecs leer ist, werden die Codec-Konfigurationen alle auf die Standardeinstellungen des User Agents zurückgesetzt.

Hinweis: Alle Codecs, die nicht in codecs enthalten sind, werden während der Verbindungsverhandlung nicht berücksichtigt. Dies ermöglicht es Ihnen, die Verwendung von Codecs zu 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 bei Audiocodecs ein Wert von 1 monauralen Ton an, während 2 Stereo angibt.

clockRate

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

mimeType

Ein String, der den MIME-Mediatyp und Subtyp des Codecs angibt und als String der Form "type/subtype" spezifiziert ist. Die MIME-Typ-Strings, 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 Details zu potenziellen Codecs, die hier referenziert werden könnten.

sdpFmtpLine Optional

Ein String, der das formatspezifische Parameterfeld der a=fmtp-Zeile im SDP angibt, das dem Codec entspricht, falls das Feld vorhanden ist. Wenn es kein Parameterfeld gibt, wird diese Eigenschaft ausgelassen.

Rückgabewert

None (undefined).

Ausnahmen

InvalidAccessError DOMException

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

InvalidModificationError DOMException

Die codecs-Liste enthält nur Einträge für RTX, RED, FEC oder Komfortgeräusch oder ist eine leere Menge. Die Codecs müssen immer einen Codec für die Medien enthalten.

Beispiele

Erstellen des Arrays bevorzugter Codecs

Der empfohlene Weg, um Codec-Präferenzen festzulegen, besteht darin, zuerst das Array der tatsächlich für das Dekodieren empfangener Daten unterstützten Codecs zu erhalten und dann die Liste in absteigender Präferenzreihenfolge neu zu ordnen.

Es ist wichtig, mit der Liste der unterstützten Codecs zu beginnen (und nicht mit einer fest codierten Liste Ihrer bevorzugten Codecs), da, wenn Sie welche einfügen, die vom zugeordneten RTCRtpReceiver nicht unterstützt werden, der Browser eine InvalidAccessError-Ausnahme auslöst, wenn Sie die setCodecPreferences()-Methode aufrufen. Darüber hinaus muss das Array geeignete Codecs für die Übertragung, Redundanz und Fehlerkorrektur enthalten, und das Starten mit der Liste der unterstützten Codecs stellt sicher, dass diese vorhanden sind.

Sie können die für die Daten-Dekodierung unterstützten Codecs mit der statischen Methode RTCRtpReceiver.getCapabilities() wie folgt abrufen:

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

Um das Codecs-Array in unsere bevorzugte Reihenfolge zu sortieren, können wir die folgende Sortierfunktion 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, das die bevorzugten MIME-Typen in absteigender Reihenfolge enthält, und gibt das Array sortiert zurück. Der untenstehende Code zeigt, wie dies verwendet wird, vorausgesetzt, Sie haben bereits eine Peer-Verbindung (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