VideoPlaybackQuality — Schnittstelle · JavaScript-Referenz

Signatur

interface VideoPlaybackQuality

Beschreibung

Ein VideoPlaybackQuality-Objekt ist eine Momentaufnahme der Wiedergabequalität eines <video>-Elements. Man erhält es ausschließlich über video.getVideoPlaybackQuality(). Einen öffentlichen Konstruktor gibt es nicht. Die Werte ändern sich nach dem Abruf nicht. Wer aktuelle Zahlen braucht, ruft die Methode erneut auf.

Das Objekt hat folgende schreibgeschützte Eigenschaften:

creationTime – Zeitstempel (DOMHighResTimeStamp, in ms relativ zu performance.timeOrigin), zu dem die Momentaufnahme erstellt wurde.
totalVideoFrames – Anzahl der Frames, die seit dem Laden des Mediums dekodiert und angezeigt bzw. verworfen wurden.
droppedVideoFrames – Anzahl der verworfenen Frames, etwa weil der Decoder zu langsam war oder Frames zu spät kamen.
corruptedVideoFrames – Anzahl beschädigter Frames (veraltet, oft immer 0).
totalFrameDelay – aufsummierte Verzögerung in Sekunden (veraltet, nicht standardisiert).

Typische Anwendungen sind adaptives Streaming (z. B. mit Media Source Extensions eine niedrigere Auflösung wählen, wenn die Drop-Rate steigt), Telemetrie und Qualitätsmonitoring in Playern sowie Performance-Diagnose beim Entwickeln.

Rückgabewert

Typ

VideoPlaybackQuality

Beschreibung

Wird von HTMLVideoElement.prototype.getVideoPlaybackQuality() zurückgegeben. Das Objekt enthält die schreibgeschützten Eigenschaften creationTime, totalVideoFrames, droppedVideoFrames und corruptedVideoFrames.

Beispiele

Momentaufnahme abrufen und auslesen

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

// Es gibt keinen Konstruktor – das Objekt kommt immer vom Video-Element
const quality = video.getVideoPlaybackQuality();

console.log(quality instanceof VideoPlaybackQuality);
console.log(`Erstellt bei: ${quality.creationTime.toFixed(0)} ms`);
console.log(`Frames gesamt: ${quality.totalVideoFrames}`);
console.log(`Verworfen: ${quality.droppedVideoFrames}`);

true Erstellt bei: 15342 ms Frames gesamt: 1480 Verworfen: 12

Drop-Rate regelmäßig überwachen

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;

  if (frames > 0) {
    const rate = (dropped / frames) * 100;
    console.log(`Drop-Rate im letzten Intervall: ${rate.toFixed(1)} %`);
  }
  last = now; // Momentaufnahmen aktualisieren sich nicht von selbst
}, 2000);

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

Drop-Rate im letzten Intervall: 0.8 %

Adaptive Qualität: Auflösung bei zu vielen verworfenen Frames senken

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

const checkQuality = () => {
  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 starten beim neuen Laden neu
    video.currentTime = time;
    video.play();
    console.log(`Wechsel auf ${sources[level]} (Drop-Rate ${(ratio * 100).toFixed(0)} %)`);
  }
};

setInterval(checkQuality, 5000);

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

// Wichtig · Fallstricke

Momentaufnahme, kein Live-Objekt: Die Werte ändern sich nach dem Abruf nicht. Für Verläufe sollte man die Methode wiederholt aufrufen und die Differenzen berechnen.
Kein Konstruktor: new VideoPlaybackQuality() löst einen TypeError aus.
Zählerstände sind kumulativ und beginnen neu, sobald das Medium neu geladen wird (z. B. durch Ändern von src oder Aufruf von load()).
corruptedVideoFrames und totalFrameDelay gelten als veraltet. totalFrameDelay wird kaum noch unterstützt, corruptedVideoFrames liefert in vielen Browsern immer 0. Man sollte sich nicht darauf verlassen.
Ältere WebKit- und Firefox-Versionen boten stattdessen die nicht standardisierten Eigenschaften webkitDroppedFrameCount bzw. mozParsedFrames/mozPresentedFrames an. Vor der Nutzung prüft man die Unterstützung mit 'getVideoPlaybackQuality' in HTMLVideoElement.prototype.
Einige verworfene Frames sind normal, z. B. beim Suchen (Seek) oder wenn der Tab im Hintergrund liegt. Deshalb sollte man Schwellwerte nicht zu knapp ansetzen.

Siehe auch

Performance.prototype.now() AudioPlaybackStats VideoTrackList IDBOpenDBRequest VRDisplayCapabilities