HTMLVideoElement.getVideoPlaybackQuality() — Methode · JavaScript-Referenz

Signatur

HTMLVideoElement.prototype.getVideoPlaybackQuality()

Beschreibung

Die Methode getVideoPlaybackQuality() eines <video>-Elements liefert eine Momentaufnahme der Wiedergabequalität. Das zurückgegebene VideoPlaybackQuality-Objekt enthält die Eigenschaften creationTime (Zeitstempel in Millisekunden, relativ zu performance.timeOrigin), totalVideoFrames (seit dem Laden dekodierte bzw. dargestellte Frames), droppedVideoFrames (verworfene Frames) und das veraltete corruptedVideoFrames.

Typischer Einsatzzweck ist das Überwachen der Wiedergabeleistung, etwa bei adaptivem Streaming (MSE, HLS, DASH): Steigt der Anteil verworfener Frames, ist das Gerät mit der aktuellen Auflösung oder Bitrate überfordert, und der Player kann auf eine niedrigere Qualitätsstufe wechseln. Auch für Telemetrie und Qualitätsberichte (QoE-Messung) ist die Methode nützlich.

Jeder Aufruf erzeugt ein neues Objekt – die Werte aktualisieren sich nicht von selbst. Für eine Verlaufsbetrachtung muss man die Methode daher periodisch aufrufen und die Differenzen zwischen zwei Messungen auswerten. Die Zähler sind kumulativ und werden erst zurückgesetzt, wenn das Medium neu geladen wird (z. B. durch Ändern von src oder Aufruf von load()).

Rückgabewert

Typ

VideoPlaybackQuality

Beschreibung

Ein neu erzeugtes VideoPlaybackQuality-Objekt mit den Eigenschaften creationTime, totalVideoFrames, droppedVideoFrames und (veraltet) corruptedVideoFrames.

Beispiele

Aktuelle Wiedergabe-Metriken auslesen

const video = document.querySelector('video');

const quality = video.getVideoPlaybackQuality();
const { totalVideoFrames, droppedVideoFrames, creationTime } = quality;

const dropRate = totalVideoFrames > 0
  ? (droppedVideoFrames / totalVideoFrames) * 100
  : 0;

console.log(`Frames gesamt: ${totalVideoFrames}`);
console.log(`Verworfen: ${droppedVideoFrames} (${dropRate.toFixed(2)} %)`);
console.log(`Gemessen bei: ${creationTime.toFixed(0)} ms`);

Frames gesamt: 1800 Verworfen: 12 (0.67 %) Gemessen bei: 60213 ms

Periodische Überwachung mit Differenzen zwischen Messungen

const video = document.querySelector('video');
let last = video.getVideoPlaybackQuality();

const timer = setInterval(() => {
  const now = video.getVideoPlaybackQuality();
  const frames = now.totalVideoFrames - last.totalVideoFrames;
  const dropped = now.droppedVideoFrames - last.droppedVideoFrames;
  const seconds = (now.creationTime - last.creationTime) / 1000;

  if (frames > 0) {
    console.log(
      `${(frames / seconds).toFixed(1)} fps, ${dropped} verworfen im Intervall`
    );
  }
  last = now;
}, 2000);

video.addEventListener('ended', () => clearInterval(timer));

29.9 fps, 0 verworfen im Intervall 28.4 fps, 3 verworfen im Intervall

Adaptive Qualitätsstufe bei zu vielen verworfenen Frames

const video = document.querySelector('#player');
const sources = ['video-1080p.mp4', 'video-720p.mp4', 'video-480p.mp4'];
let level = 0;

const downgradeIfNeeded = () => {
  if (typeof video.getVideoPlaybackQuality !== 'function') return;

  const { totalVideoFrames, droppedVideoFrames } = video.getVideoPlaybackQuality();
  if (totalVideoFrames < 300) return; // zu wenig Daten

  const ratio = droppedVideoFrames / totalVideoFrames;
  if (ratio > 0.1 && level < sources.length - 1) {
    const time = video.currentTime;
    level += 1;
    video.src = sources[level]; // Zähler werden dabei zurückgesetzt
    video.currentTime = time;
    video.play();
    console.log(`Wechsel auf ${sources[level]} (Drop-Rate ${(ratio * 100).toFixed(1)} %)`);
  }
};

setInterval(downgradeIfNeeded, 5000);

Wechsel auf video-720p.mp4 (Drop-Rate 14.2 %)

// Wichtig · Fallstricke

Momentaufnahme: Das Rückgabeobjekt ist statisch. Für aktuelle Werte muss die Methode erneut aufgerufen werden.
Kumulative Zähler: totalVideoFrames und droppedVideoFrames zählen seit dem letzten Laden des Mediums. Für Aussagen über die aktuelle Leistung Differenzen zwischen zwei Messungen bilden.
corruptedVideoFrames ist veraltet und liefert in vielen Browsern immer 0 – nicht darauf verlassen.
Die Zählweise unterscheidet sich zwischen Browsern (z. B. ob Frames im Hintergrund-Tab oder beim Suchen mitgezählt werden). Werte daher als Tendenz, nicht als exakte Messung betrachten.
Kompatibilität: Chrome/Edge (Chromium) unterstützen die Methode erst seit Version 107; ältere Chromium-Versionen boten nur die nicht standardisierten Eigenschaften webkitDroppedFrameCount und webkitDecodedFrameCount. Vorher per typeof video.getVideoPlaybackQuality === 'function' prüfen.
Firefox kann bei aktiviertem privacy.resistFingerprinting gerundete bzw. verfälschte Werte liefern.

Siehe auch

Performance.now() HTMLVideoElement.cancelVideoFrameCallback() HTMLVideoElement.requestVideoFrameCallback() HTMLVideoElement.requestPictureInPicture() HTMLEmbedElement.getSVGDocument()