RTCRtpTransceiver.setCodecPreferences() — Methode · JavaScript-Referenz

Signatur

RTCRtpTransceiver.prototype.setCodecPreferences(codecs)

Beschreibung

Mit setCodecPreferences() steuern Sie, welche Codecs ein RTCRtpTransceiver bei der SDP-Aushandlung anbietet und in welcher Reihenfolge. Die Liste bestimmt die Payload-Typen in der m=-Zeile des lokalen SDP. Damit gilt sie in erster Linie für die Empfangsrichtung: Sie teilen der Gegenseite mit, welche Codecs Sie dekodieren können und welche Sie bevorzugen. Die Gegenseite richtet ihre Sendecodecs normalerweise nach dieser Präferenz.

Typische Einsatzfälle:

Einen bestimmten Videocodec erzwingen oder bevorzugen, zum Beispiel VP9, AV1 oder H.264 für Hardware-Beschleunigung.
Einen Audiocodec wie Opus nach vorne stellen.
Unerwünschte Codecs ausschließen.

Früher hat man für all das die SDP-Zeichenkette manuell bearbeitet („SDP-Munging“). Diese Methode ist dafür der saubere, standardisierte Ersatz.

Die Codec-Objekte sollten Sie immer aus RTCRtpReceiver.getCapabilities(kind).codecs beziehen. Sie können sie umsortieren oder filtern, dürfen aber keine neuen Codecs erfinden. Die Methode muss vor createOffer() bzw. createAnswer() aufgerufen werden, damit die Präferenz im erzeugten SDP landet. Bei einer bestehenden Verbindung braucht es danach eine Neuaushandlung.

Wenn Sie ein leeres Array übergeben, setzen Sie die Präferenzen zurück. Dann gilt wieder die Standardreihenfolge des Browsers.

Parameter

Name	Typ	Default	Beschreibung
$codecs Pflicht	Array<RTCRtpCodec>		Liste von Codec-Objekten (`mimeType`, `clockRate`, optional `channels`, `sdpFmtpLine`) in absteigender Präferenz. Die Objekte müssen aus `RTCRtpReceiver.getCapabilities()` stammen. Ein leeres Array setzt die Präferenzen auf die Standardwerte zurück.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Präferenz wirkt sich erst auf das nächste erzeugte Angebot bzw. die nächste erzeugte Antwort aus.

Beispiele

VP9 als bevorzugten Videocodec festlegen

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const transceiver = pc.addTransceiver(track, { direction: 'sendrecv' });

const { codecs } = RTCRtpReceiver.getCapabilities('video');
// VP9 nach vorne, Rest in Originalreihenfolge dahinter
const preferred = [
  ...codecs.filter((c) => c.mimeType === 'video/VP9'),
  ...codecs.filter((c) => c.mimeType !== 'video/VP9')
];
transceiver.setCodecPreferences(preferred);

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
console.log(offer.sdp.match(/^m=video.*$/m)[0]);

m=video 9 UDP/TLS/RTP/SAVPF 98 99 96 97 ... (VP9-Payload-Typen zuerst)

Nur H.264 zulassen (Hilfscodecs wie RTX behalten)

const pc = new RTCPeerConnection();
const transceiver = pc.addTransceiver('video', { direction: 'recvonly' });

const { codecs } = RTCRtpReceiver.getCapabilities('video');
const allowed = codecs.filter((c) =>
  ['video/H264', 'video/rtx', 'video/red', 'video/ulpfec'].includes(c.mimeType)
);

try {
  transceiver.setCodecPreferences(allowed);
} catch (err) {
  console.error('Codec-Präferenz abgelehnt:', err.name);
}

const offer = await pc.createOffer();
console.log(offer.sdp.includes('VP8') ? 'VP8 noch enthalten' : 'Nur H.264 angeboten');

Nur H.264 angeboten

Feature-Detection und Zurücksetzen der Präferenzen

const pc = new RTCPeerConnection();
const transceiver = pc.addTransceiver('audio');

if ('setCodecPreferences' in RTCRtpTransceiver.prototype) {
  const { codecs } = RTCRtpReceiver.getCapabilities('audio');
  const opusFirst = [...codecs].sort((a, b) =>
    (b.mimeType === 'audio/opus') - (a.mimeType === 'audio/opus')
  );
  transceiver.setCodecPreferences(opusFirst);
  console.log('Erster Codec:', opusFirst[0].mimeType);

  // Später: Standardreihenfolge des Browsers wiederherstellen
  transceiver.setCodecPreferences([]);
} else {
  console.warn('setCodecPreferences nicht unterstützt – Fallback: SDP-Munging');
}

Erster Codec: audio/opus

// Wichtig · Fallstricke

Fehler: Die Methode wirft InvalidModificationError, wenn die Liste Codecs enthält, die nicht in RTCRtpReceiver.getCapabilities() vorkommen, oder wenn nur Hilfscodecs wie RTX, RED oder FEC übrig bleiben. Ist der Transceiver bereits gestoppt, wirft sie InvalidStateError.
Empfangs- und Sendeseite: Die Präferenz beschreibt, was Sie empfangen wollen. Welchen Codec die Gegenseite tatsächlich zum Senden verwendet, entscheidet sich erst in der Aushandlung. Prüfen Sie das Ergebnis über sender.getParameters().codecs oder getStats().
Reihenfolge der Aufrufe: Rufen Sie die Methode vor createOffer()/createAnswer() auf. Bei laufenden Verbindungen ist eine Neuaushandlung nötig, zum Beispiel über negotiationneeded.
Hilfscodecs: Filtern Sie video/rtx, video/red und video/ulpfec nicht versehentlich heraus. Sonst gehen Paketwiederholung und Fehlerkorrektur verloren.
Kompatibilität: Chromium und Safari unterstützen die Methode seit Längerem. Firefox unterstützt sie erst ab Version 128. Nutzen Sie für ältere Browser eine Feature-Detection.
Nur Sendecodecs festlegen: Dafür gibt es neuere Browser-APIs, etwa den Parameter codec in RTCRtpSender.setParameters(). Diese werden noch nicht überall unterstützt.

Siehe auch

RTCRtpTransceiver RTCRtpReceiver.getCapabilities() RTCRtpSender.getCapabilities() RTCPeerConnection.addTransceiver() RTCPeerConnection.createOffer() RTCRtpSender.setParameters()