VideoPlaybackQuality.totalFrameDelay — Eigenschaft · JavaScript-Referenz

Signatur

VideoPlaybackQuality.totalFrameDelay

Beschreibung

Die schreibgeschützte Eigenschaft totalFrameDelay eines VideoPlaybackQuality-Objekts gibt an, wie viele Sekunden sich die Frames insgesamt verspätet haben. Gezählt wird ab der Erstellung des zugehörigen HTMLVideoElement. Die Verzögerung eines Frames ist der Abstand zwischen dem Zeitpunkt, zu dem er laut Zeitplan angezeigt werden sollte, und dem Zeitpunkt, zu dem er tatsächlich angezeigt wurde.

Ein VideoPlaybackQuality-Objekt bekommen Sie über HTMLVideoElement.prototype.getVideoPlaybackQuality(). Das Objekt ist eine Momentaufnahme: Die Werte ändern sich später nicht mehr. Wenn Sie die Wiedergabe dauerhaft überwachen wollen, rufen Sie die Methode deshalb in Abständen neu auf.

Gedacht war die Eigenschaft für die Analyse der Wiedergabequalität, etwa bei adaptivem Streaming mit Media Source Extensions: Steigt die Verzögerung stark an, ist das Endgerät überlastet und die Anwendung könnte eine niedrigere Bitrate wählen. Die Eigenschaft wurde aber aus der Spezifikation entfernt. Verwenden Sie stattdessen droppedFrames und totalVideoFrames, um die Qualität einzuschätzen.

Rückgabewert

Typ

number | undefined

Beschreibung

Eine Gleitkommazahl (double) mit der Summe aller Frame-Verzögerungen in Sekunden. Unterstützt der Browser die Eigenschaft nicht, ist der Wert undefined.

Beispiele

Unterstützung prüfen und Wert auslesen

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

const quality = video.getVideoPlaybackQuality?.();

if (quality && 'totalFrameDelay' in quality) {
  console.log(`Gesamtverzögerung: ${quality.totalFrameDelay.toFixed(3)} s`);
} else {
  console.log('totalFrameDelay wird nicht unterstützt');
}

totalFrameDelay wird nicht unterstützt

Qualität regelmäßig messen, mit Ersatzkennzahl

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

const reportQuality = () => {
  const q = video.getVideoPlaybackQuality();
  // Anteil verworfener Frames: die standardisierte Ersatzkennzahl
  const dropRate = q.totalVideoFrames > 0
    ? q.droppedVideoFrames / q.totalVideoFrames
    : 0;

  const delay = typeof q.totalFrameDelay === 'number'
    ? `${q.totalFrameDelay.toFixed(3)} s`
    : 'n. v.';

  console.log(`Verworfen: ${(dropRate * 100).toFixed(1)} % | Verzögerung: ${delay}`);
};

// Jedes Objekt ist eine Momentaufnahme, darum jede Sekunde neu abfragen
const timer = setInterval(reportQuality, 1000);
video.addEventListener('ended', () => clearInterval(timer), { once: true });

Verworfen: 0.4 % | Verzögerung: n. v.

Durchschnittliche Verzögerung pro Frame berechnen (falls verfügbar)

const averageFrameDelay = (video) => {
  const q = video.getVideoPlaybackQuality();
  if (typeof q.totalFrameDelay !== 'number' || q.totalVideoFrames === 0) {
    return null;
  }
  // Ergebnis in Millisekunden pro Frame
  return (q.totalFrameDelay / q.totalVideoFrames) * 1000;
};

const avg = averageFrameDelay(document.querySelector('video'));
console.log(avg === null ? 'Keine Daten' : `${avg.toFixed(2)} ms/Frame`);

Keine Daten

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Eigenschaft wurde aus der Spezifikation entfernt. Chrome, Firefox und Safari bieten sie in aktuellen Versionen nicht an; historisch gab es sie vor allem im Internet Explorer 11 und im alten Edge. Nutzen Sie sie nicht in Produktivcode.
Immer vorher prüfen: Testen Sie mit 'totalFrameDelay' in quality oder typeof, ob die Eigenschaft existiert. Ohne diese Prüfung liefern Rechnungen damit NaN.
Momentaufnahme: Ein einmal abgefragtes VideoPlaybackQuality-Objekt ändert sich nicht mehr. Für aktuelle Werte müssen Sie getVideoPlaybackQuality() erneut aufrufen.
Einheit: Der Wert wird in Sekunden angegeben, nicht in Millisekunden. Er zählt ab der Erstellung des Elements weiter und wird beim Wechsel der Quelle je nach Browser nicht unbedingt zurückgesetzt.
Alternativen: droppedVideoFrames und totalVideoFrames sind standardisiert. Für Analysen einzelner Frames eignet sich HTMLVideoElement.requestVideoFrameCallback().

Siehe auch

VideoPlaybackQuality.totalVideoFrames VideoPlaybackQuality.creationTime VideoPlaybackQuality.droppedVideoFrames VideoPlaybackQuality.corruptedVideoFrames AudioPlaybackStats.totalDuration