VideoPlaybackQuality.droppedVideoFrames — Eigenschaft · JavaScript-Referenz

Signatur

VideoPlaybackQuality.droppedVideoFrames

Beschreibung

Die schreibgeschützte Eigenschaft droppedVideoFrames eines VideoPlaybackQuality-Objekts gibt an, wie viele Videoframes seit dem letzten Laden des Mediums verworfen wurden. Das heißt, sie wurden nicht angezeigt, meist weil sie zu spät dekodiert wurden oder das System überlastet war. Das Objekt bekommst du über HTMLVideoElement.prototype.getVideoPlaybackQuality().

Die Zahl steigt während der Wiedergabe immer weiter an. Sie wird erst zurückgesetzt, wenn das Medium neu geladen wird, zum Beispiel durch Ändern von src oder durch Aufruf von load(). Aussagekräftig ist sie vor allem im Verhältnis zu totalVideoFrames: Die Drop-Rate ist droppedVideoFrames / totalVideoFrames. Ein hoher Wert zeigt, dass das Gerät die aktuelle Auflösung oder Bitrate nicht flüssig schafft.

Typische Einsatzfälle sind adaptives Streaming (automatisch auf eine niedrigere Qualitätsstufe wechseln, wenn zu viele Frames verloren gehen), Messung der Wiedergabequalität im Praxisbetrieb (Telemetrie) und die Fehlersuche bei ruckelnder Wiedergabe.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative ganze Zahl (unsigned long): die Anzahl der verworfenen Frames seit dem letzten Laden des Mediums.

Beispiele

Verworfene Frames und Drop-Rate auslesen

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

const { droppedVideoFrames, totalVideoFrames } = video.getVideoPlaybackQuality();
const rate = totalVideoFrames > 0 ? droppedVideoFrames / totalVideoFrames : 0;

console.log(`Verworfen: ${droppedVideoFrames} von ${totalVideoFrames} (${(rate * 100).toFixed(1)} %)`);

Verworfen: 12 von 1500 (0.8 %)

Qualität automatisch senken, wenn zu viele Frames verloren gehen

const video = document.querySelector('video');
const quellen = ['video-1080p.mp4', 'video-720p.mp4', 'video-480p.mp4'];
let stufe = 0;
let letzte = { dropped: 0, total: 0 };

const pruefen = () => {
  const q = video.getVideoPlaybackQuality();
  // Nur das Intervall seit der letzten Messung betrachten
  const dropped = q.droppedVideoFrames - letzte.dropped;
  const total = q.totalVideoFrames - letzte.total;
  letzte = { dropped: q.droppedVideoFrames, total: q.totalVideoFrames };

  if (total > 0 && dropped / total > 0.1 && stufe < quellen.length - 1) {
    const zeit = video.currentTime;
    stufe++;
    video.src = quellen[stufe]; // setzt die Zähler zurück
    letzte = { dropped: 0, total: 0 };
    video.currentTime = zeit;
    video.play();
    console.log(`Wechsel auf ${quellen[stufe]}`);
  }
};

setInterval(pruefen, 5000);

Wechsel auf video-720p.mp4

Telemetrie beim Verlassen der Seite senden

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

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState !== 'hidden') return;
  const q = video.getVideoPlaybackQuality();
  const daten = JSON.stringify({
    dropped: q.droppedVideoFrames,
    total: q.totalVideoFrames,
    zeitpunkt: q.creationTime
  });
  navigator.sendBeacon('/api/playback-stats', daten);
});

// Wichtig · Fallstricke

Kumulativer Wert: Der Zähler steigt ab dem Laden immer weiter. Wenn du die aktuelle Qualität beurteilen willst, rechne mit Differenzen zwischen zwei Messungen und nicht mit dem Gesamtwert.
Momentaufnahme: Jeder Aufruf von getVideoPlaybackQuality() liefert ein neues Objekt. Die Werte eines bereits abgerufenen Objekts ändern sich danach nicht mehr.
Zurücksetzen: Ein neues src oder ein Aufruf von load() setzt den Zähler auf 0. Beim Wechsel der Qualitätsstufe in Media Source Extensions (MSE) bleibt er dagegen meist erhalten.
Unterschiede zwischen Browsern: Wann ein Frame als „verworfen“ gilt, legt jeder Browser selbst fest. Die Werte sind deshalb zwischen Browsern nur bedingt vergleichbar. Hintergrund-Tabs und ausgeblendete Videos können ebenfalls verworfene Frames erzeugen.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Ältere Browser boten nur Eigenschaften mit Präfix an, etwa webkitDroppedFrameCount oder mozParsedFrames. Prüfe die Unterstützung deshalb mit 'getVideoPlaybackQuality' in HTMLVideoElement.prototype.
Die Eigenschaft corruptedVideoFrames ist veraltet. Nutze stattdessen droppedVideoFrames.

Siehe auch

VideoPlaybackQuality.corruptedVideoFrames VideoPlaybackQuality.totalVideoFrames VideoPlaybackQuality.creationTime VideoPlaybackQuality.totalFrameDelay AudioPlaybackStats.totalDuration