RTCRtpSender.getCapabilities() — Methode · JavaScript-Referenz

Signatur

RTCRtpSender.getCapabilities(kind)

Beschreibung

RTCRtpSender.getCapabilities() ist eine statische Methode. Du rufst sie also direkt an der Klasse RTCRtpSender auf und nicht an einer Instanz. Sie zeigt, welche Medienformate der Browser senden kann: die unterstützten Codecs (etwa VP8, VP9, H.264, AV1 oder Opus) und die RTP-Header-Erweiterungen. Eine RTCPeerConnection brauchst du dafür nicht.

Meist setzt man die Methode zusammen mit RTCRtpTransceiver.setCodecPreferences() ein. Du fragst die Liste der Fähigkeiten ab, filterst oder sortierst sie und übergibst das Ergebnis an den Transceiver. So kannst du vor der SDP-Aushandlung zum Beispiel VP9 oder AV1 bevorzugen oder einen Codec ganz ausschließen. Außerdem eignet sich die Methode zur Funktionserkennung, etwa um vorab zu prüfen, ob Hardware-H.264 oder AV1 verfügbar ist.

Das Ergebnis gilt nur für die Senderichtung. Was der Browser empfangen kann, liefert RTCRtpReceiver.getCapabilities(). Beide Listen können sich unterscheiden, zum Beispiel wenn ein Codec nur dekodiert, aber nicht kodiert werden kann. Zusätzlich zu den eigentlichen Medien-Codecs enthält die Liste oft Hilfseinträge wie video/rtx, video/red oder video/ulpfec.

Parameter

Name	Typ	Default	Beschreibung
$kind Pflicht	"audio" \| "video"		Die Medienart, für die die Sende-Fähigkeiten abgefragt werden. Andere Werte führen zum Rückgabewert `null`.

Rückgabewert

Typ

RTCRtpCapabilities | null

Beschreibung

Ein Objekt mit zwei Arrays:

codecs: Objekte mit mimeType, clockRate, optional channels (nur Audio) und sdpFmtpLine
headerExtensions: Objekte mit uri

Bei einem ungültigen kind wird null zurückgegeben.

Beispiele

Unterstützte Video-Codecs auflisten

const caps = RTCRtpSender.getCapabilities('video');

// Eindeutige MIME-Typen ohne Hilfs-Codecs
const mimeTypes = [...new Set(
  caps.codecs
    .map((c) => c.mimeType)
    .filter((m) => !/rtx|red|ulpfec|flexfec/i.test(m))
)];

console.log(mimeTypes);

["video/VP8", "video/VP9", "video/H264", "video/AV1"] // je nach Browser

Codec-Priorität setzen: VP9 zuerst

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();

const transceiver = pc.addTransceiver(track, { direction: 'sendonly' });

const { codecs } = RTCRtpSender.getCapabilities('video');
const preferred = [
  ...codecs.filter((c) => c.mimeType === 'video/VP9'),
  ...codecs.filter((c) => c.mimeType !== 'video/VP9')
];

// Muss vor createOffer() gesetzt werden
transceiver.setCodecPreferences(preferred);

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

Funktionserkennung für AV1 und Header-Erweiterungen

const supportsSendCodec = (kind, mimeType) => {
  if (typeof RTCRtpSender === 'undefined' || !('getCapabilities' in RTCRtpSender)) {
    return false;
  }
  const caps = RTCRtpSender.getCapabilities(kind);
  return !!caps?.codecs.some(
    (c) => c.mimeType.toLowerCase() === mimeType.toLowerCase()
  );
};

console.log('AV1 senden:', supportsSendCodec('video', 'video/AV1'));
console.log('Opus senden:', supportsSendCodec('audio', 'audio/opus'));

const { headerExtensions } = RTCRtpSender.getCapabilities('audio');
console.log(headerExtensions.map((h) => h.uri));

AV1 senden: true Opus senden: true ["urn:ietf:params:rtp-hdrext:ssrc-audio-level", ...]

// Wichtig · Fallstricke

Statisch: sender.getCapabilities() an einer Instanz gibt es nicht und führt zu einem TypeError. Richtig ist RTCRtpSender.getCapabilities('video').
Groß- und Kleinschreibung: Die Schreibweise von mimeType unterscheidet sich je nach Browser (z. B. video/H264 und video/h264). Vergleiche deshalb immer ohne Beachtung der Groß- und Kleinschreibung.
Mehrere Einträge pro Codec: H.264 taucht oft mehrfach auf, mit verschiedenen Profilen und packetization-mode in sdpFmtpLine. Beim Filtern nicht versehentlich alle Varianten verwerfen.
setCodecPreferences: Übergib nur Einträge aus dem Rückgabewert, sonst wird ein InvalidModificationError ausgelöst. Firefox lehnt reine Sende-Codecs bei setCodecPreferences() teilweise ab, weil die Werte dort mit den Empfangs-Fähigkeiten abgeglichen werden. Ziehe im Zweifel RTCRtpReceiver.getCapabilities() heran.
Datenschutz: Die Codec-Liste verrät Details über Hardware und Plattform und kann für Browser-Fingerprinting genutzt werden. Manche Browser liefern deshalb eine reduzierte Liste.
Kompatibilität: Chromium und Safari unterstützen die Methode seit Längerem, Firefox erst ab Version 110. Prüfe in älteren Umgebungen vorher, ob die Methode existiert.
Das Ergebnis kann vom Gerät abhängen (Hardware-Encoder) und ist keine Garantie dafür, dass die Gegenstelle den Codec aushandelt.

Siehe auch

RTCRtpReceiver.getCapabilities() RTCRtpTransceiver.setCodecPreferences() RTCRtpSender RTCRtpSender.setParameters() RTCPeerConnection.addTransceiver() new InputDeviceCapabilities()