RTCCodecStats — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCCodecStats extends RTCStats

Beschreibung

RTCCodecStats ist ein Wörterbuch (Dictionary) der WebRTC-Statistik-API. Man erzeugt es nicht selbst. Es steckt als Eintrag im RTCStatsReport, den RTCPeerConnection.getStats(), RTCRtpSender.getStats() oder RTCRtpReceiver.getStats() zurückgibt. Solche Einträge erkennt man an type === "codec".

Ein Codec-Eintrag gibt an, welcher Codec tatsächlich ausgehandelt und genutzt wird, zum Beispiel video/VP8, video/H264 oder audio/opus. Dazu kommen der RTP-Payload-Typ, die Taktrate, die Anzahl der Kanäle und die SDP-Parameterzeile (a=fmtp). Das ist nützlich für Diagnose-Dashboards, für Qualitätsmonitoring und zur Prüfung, ob Codec-Vorgaben (etwa über setCodecPreferences()) gegriffen haben.

Die RTP-Stream-Statistiken (RTCInboundRtpStreamStats, RTCOutboundRtpStreamStats) enthalten die Eigenschaft codecId. Sie verweist auf die id des passenden RTCCodecStats-Eintrags. So ordnet man jedem Stream seinen Codec zu. Über transportId verweist der Codec-Eintrag wiederum auf den zugehörigen RTCTransportStats-Eintrag.

Neben den geerbten Feldern id, timestamp und type aus RTCStats stellt das Wörterbuch die unten aufgeführten Eigenschaften bereit.

Parameter

Name	Typ	Default	Beschreibung
$payloadType Pflicht	number		RTP-Payload-Typ (0–127), unter dem dieser Codec in RTP-Paketen gekennzeichnet wird, z. B. `111` für Opus.
$mimeType Pflicht	string		MIME-Typ des Codecs im Format `typ/untertyp`, z. B. `"video/VP8"` oder `"audio/opus"`.
$clockRate	number		RTP-Taktrate in Hertz, z. B. `90000` bei Video oder `48000` bei Opus.
$channels	number		Anzahl der Audiokanäle (`1` = Mono, `2` = Stereo). Fehlt bei Video-Codecs.
$sdpFmtpLine	string		Parameter aus der SDP-Zeile `a=fmtp` ohne Präfix und Payload-Typ, z. B. `"minptime=10;useinbandfec=1"`.
$transportId Pflicht	string		`id` des `RTCTransportStats`-Eintrags für den Transport, über den dieser Codec läuft.
$id Pflicht	string		Eindeutige Kennung des Eintrags im Bericht (geerbt von `RTCStats`).
$timestamp Pflicht	DOMHighResTimeStamp		Zeitpunkt, zu dem die Statistik erfasst wurde (geerbt von `RTCStats`).
$type Pflicht	string	"codec"	Art des Statistikeintrags. Bei diesem Wörterbuch immer `"codec"`.

Rückgabewert

Typ

RTCCodecStats

Beschreibung

Ein einfaches Objekt mit den oben aufgeführten Eigenschaften. Man erhält es als Wert aus der Map des RTCStatsReport.

Beispiele

Alle verwendeten Codecs einer Verbindung auflisten

// pc ist eine verbundene RTCPeerConnection
const listCodecs = async (pc) => {
  const report = await pc.getStats();
  const codecs = [];
  report.forEach((stat) => {
    if (stat.type === 'codec') {
      codecs.push({
        mimeType: stat.mimeType,
        payloadType: stat.payloadType,
        clockRate: stat.clockRate,
        channels: stat.channels ?? '-',
        fmtp: stat.sdpFmtpLine ?? ''
      });
    }
  });
  console.table(codecs);
  return codecs;
};

await listCodecs(pc);

┌─────────┬──────────────┬─────────────┬───────────┬──────────┬────────────────────────────────┐ │ (index) │ mimeType │ payloadType │ clockRate │ channels │ fmtp │ │ 0 │ 'audio/opus' │ 111 │ 48000 │ 2 │ 'minptime=10;useinbandfec=1' │ │ 1 │ 'video/VP8' │ 96 │ 90000 │ '-' │ '' │ └─────────┴──────────────┴─────────────┴───────────┴──────────┴────────────────────────────────┘

Codec des gesendeten Videostreams über codecId ermitteln

const getOutgoingVideoCodec = async (pc) => {
  const report = await pc.getStats();
  for (const stat of report.values()) {
    if (stat.type === 'outbound-rtp' && stat.kind === 'video' && stat.codecId) {
      // codecId verweist auf den RTCCodecStats-Eintrag
      const codec = report.get(stat.codecId);
      return codec?.mimeType ?? null;
    }
  }
  return null;
};

console.log('Sende-Codec:', await getOutgoingVideoCodec(pc));

Sende-Codec: video/VP8

Prüfen, ob die Codec-Vorgabe gegriffen hat

// Vorher: H.264 per setCodecPreferences bevorzugt
const checkPreferredCodec = async (sender, wanted = 'video/H264') => {
  const report = await sender.getStats();
  const codec = [...report.values()].find((s) => s.type === 'codec');
  if (!codec) {
    console.warn('Noch kein Codec ausgehandelt');
    return false;
  }
  const ok = codec.mimeType.toLowerCase() === wanted.toLowerCase();
  console.log(ok ? `OK: ${codec.mimeType}` : `Abweichung: ${codec.mimeType}`);
  return ok;
};

const [videoSender] = pc.getSenders().filter((s) => s.track?.kind === 'video');
await checkPreferredCodec(videoSender);

OK: video/H264

// Wichtig · Fallstricke

Nur ausgehandelte, genutzte Codecs: Der Bericht enthält Codec-Einträge meist erst, wenn sie von einem RTP-Stream verwendet werden, nicht schon für alle im SDP angebotenen. Direkt nach setRemoteDescription() kann der Bericht deshalb noch keine Codec-Einträge haben.
Groß- und Kleinschreibung: mimeType kann je nach Browser unterschiedlich geschrieben sein (video/H264 oder video/h264). Vergleiche daher ohne Rücksicht auf Groß- und Kleinschreibung.
Veraltete Felder: Ältere Spezifikationsstände und Browser kannten codecType ("encode"/"decode") und implementation. Beide wurden entfernt. Die Richtung ergibt sich heute aus dem verweisenden inbound-rtp- oder outbound-rtp-Eintrag. Den Encoder bzw. Decoder liefern encoderImplementation und decoderImplementation.
Optionale Felder: channels, clockRate und sdpFmtpLine können fehlen. Verwende deshalb Optional Chaining oder ??.
Browser-Kompatibilität: Chromium-Browser und Safari unterstützen Codec-Statistiken schon länger, Firefox erst ab Version 117. Die id-Werte sind browserspezifisch und dürfen nicht geparst werden.
Datenschutz: Statistiken können Rückschlüsse auf Hardware-Codecs erlauben und damit Fingerprinting ermöglichen. Einige Browser schränken deshalb bestimmte Felder ein.

Siehe auch

XRRenderState RTCCertificate RTCVideoSourceStats AudioData AudioDecoder