RTCVideoSourceStats — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCVideoSourceStats extends RTCMediaSourceStats

Beschreibung

RTCVideoSourceStats ist ein Wörterbuch (Dictionary) der WebRTC-Statistik-API. Es beschreibt die Video-Spur (MediaStreamTrack), die an einen oder mehrere RTCRtpSender angehängt ist. Die Werte zeigen, was die Quelle – also Kamera, Bildschirmfreigabe oder Canvas-Stream – tatsächlich liefert. Das ist der Zustand vor dem Encoder und damit vor Skalierung, Simulcast oder Bandbreitenanpassung.

Ein solches Objekt ist kein eigenständiger Konstruktor. Du bekommst es als Eintrag im RTCStatsReport, den RTCPeerConnection.getStats() oder RTCRtpSender.getStats() liefert. Erkennbar ist es an type === "media-source" und kind === "video". Neben den eigenen Feldern (width, height, frames, framesPerSecond) erbt es trackIdentifier und kind von RTCMediaSourceStats sowie id, timestamp und type von RTCStats.

Typischer Einsatz: Du vergleichst die Quell-Auflösung mit frameWidth/frameHeight des zugehörigen outbound-rtp-Eintrags. So siehst du, ob der Browser das Video wegen CPU- oder Bandbreitenmangel herunterskaliert. Außerdem kannst du prüfen, ob die Kamera überhaupt die angeforderte Bildrate liefert.

Parameter

Name	Typ	Beschreibung
$width	number	Breite des zuletzt von der Quelle gelieferten Bildes in Pixeln. Fehlt, solange noch kein Bild vorliegt.
$height	number	Höhe des zuletzt von der Quelle gelieferten Bildes in Pixeln.
$frames	number	Gesamtzahl der Bilder, die die Quelle seit dem Anhängen an den Sender geliefert hat (Zähler, steigt nur an).
$framesPerSecond	number	Bilder, die in der letzten Sekunde von der Quelle kamen. Fehlt in der ersten Sekunde.
$trackIdentifier Pflicht	string	Geerbt von `RTCMediaSourceStats`: entspricht `MediaStreamTrack.id` der Quellspur.
$kind Pflicht	"video"	Geerbt von `RTCMediaSourceStats`: bei diesem Wörterbuch immer `"video"`.
$id Pflicht	string	Geerbt von `RTCStats`: eindeutige ID des Eintrags im Bericht. Wird von `outbound-rtp` über `mediaSourceId` referenziert.
$timestamp Pflicht	DOMHighResTimeStamp	Geerbt von `RTCStats`: Zeitpunkt der Messung in Millisekunden.
$type Pflicht	"media-source"	Geerbt von `RTCStats`: immer `"media-source"`.

Rückgabewert

Typ

RTCVideoSourceStats

Beschreibung

Ein einfaches Objekt als Wert im RTCStatsReport (einer Map). Du erhältst es über await pc.getStats() oder await sender.getStats().

Beispiele

Video-Quellstatistik eines Senders auslesen

const stream = await navigator.mediaDevices.getUserMedia({ video: { width: 1280, height: 720 } });
const pc = new RTCPeerConnection();
const [track] = stream.getVideoTracks();
const sender = pc.addTrack(track, stream);

// Kurz warten, damit die Quelle Bilder geliefert hat
await new Promise((r) => setTimeout(r, 1500));

const report = await sender.getStats();
for (const stats of report.values()) {
  if (stats.type === 'media-source' && stats.kind === 'video') {
    console.log(`Quelle: ${stats.width}x${stats.height} @ ${stats.framesPerSecond} fps`);
    console.log('Bilder gesamt:', stats.frames);
    console.log('Spur passt:', stats.trackIdentifier === track.id);
  }
}

Quelle: 1280x720 @ 30 fps Bilder gesamt: 45 Spur passt: true

Herunterskalierung durch den Encoder erkennen

const checkScaling = async (pc) => {
  const report = await pc.getStats();
  for (const out of report.values()) {
    if (out.type !== 'outbound-rtp' || out.kind !== 'video') continue;
    const src = report.get(out.mediaSourceId); // RTCVideoSourceStats
    if (!src || !out.frameWidth) continue;
    const factor = src.width / out.frameWidth;
    console.log(
      `Quelle ${src.width}x${src.height} → gesendet ${out.frameWidth}x${out.frameHeight}`,
      `(Faktor ${factor.toFixed(2)}, Grund: ${out.qualityLimitationReason ?? 'unbekannt'})`
    );
  }
};

setInterval(() => checkScaling(pc), 5000);

Quelle 1280x720 → gesendet 640x360 (Faktor 2.00, Grund: bandwidth)

Eigene Bildrate aus zwei Messungen berechnen

const getVideoSource = async (sender) => {
  const report = await sender.getStats();
  return [...report.values()].find(
    (s) => s.type === 'media-source' && s.kind === 'video'
  );
};

const a = await getVideoSource(sender);
await new Promise((r) => setTimeout(r, 2000));
const b = await getVideoSource(sender);

const fps = ((b.frames - a.frames) / (b.timestamp - a.timestamp)) * 1000;
console.log(`Gemittelte Quell-Bildrate: ${fps.toFixed(1)} fps`);

Gemittelte Quell-Bildrate: 29.8 fps

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser und Safari liefern media-source-Einträge für Video. Firefox unterstützt sie nur teilweise oder gar nicht. Prüfe deshalb immer, ob der Eintrag und seine Felder existieren, bevor du sie benutzt.
Die Felder width, height und framesPerSecond sind optional. Sie fehlen, solange die Quelle noch keine Bilder geliefert hat, und framesPerSecond zusätzlich in der ersten Sekunde.
Die Werte beschreiben die Quelle, nicht den gesendeten Datenstrom. Wie viele Bilder und welche Auflösung tatsächlich gesendet werden, steht in RTCOutboundRtpStreamStats (framesSent, frameWidth). Bei Simulcast verweisen mehrere outbound-rtp-Einträge auf dieselbe Quelle.
Ist track.enabled = false gesetzt oder die Spur stummgeschaltet, liefert die Quelle weiterhin Bilder, nur schwarze. Die Zähler steigen also weiter.
Ältere Browser nutzten dafür den veralteten Typ "track" (RTCMediaStreamTrackStats). Dieser ist aus der Spezifikation entfernt worden und sollte nicht mehr verwendet werden.
Rufe getStats() nicht zu oft auf. Die Abfrage ist asynchron und kostet etwas Rechenzeit; ein Abstand von 1–5 Sekunden reicht für Überwachung in der Regel aus.

Siehe auch

RTCAudioSourceStats RTCCodecStats RTCTransportStats RTCCertificateStats RTCIceCandidateStats