MediaStreamTrackProcessor.totalFrames — Eigenschaft · JavaScript-Referenz

Signatur

MediaStreamTrackProcessor.totalFrames

Beschreibung

Die schreibgeschützte Eigenschaft totalFrames eines MediaStreamTrackProcessor zählt alle Frames, die der Prozessor seit seiner Erzeugung von der zugrunde liegenden MediaStreamTrack erhalten hat. Mitgezählt werden auch Frames, die nie bei Ihrem Code ankommen, zum Beispiel weil die Warteschlange voll war.

Nützlich ist die Eigenschaft vor allem zur Diagnose und Leistungsmessung. Den Wert vergleichen Sie mit der Zahl der Frames, die Sie selbst über processor.readable gelesen haben. Ist die Differenz groß, verarbeitet Ihre Pipeline zu langsam, sodass der Prozessor Frames verwirft (siehe maxBufferSize im Konstruktor).

Diese Eigenschaft steht nicht in der aktuellen Spezifikation „MediaStream Insertable Streams / mediacapture-transform“ und wird von vielen Browsern nicht angeboten. Prüfen Sie deshalb immer, ob sie vorhanden ist. Für standardisierte Frame-Statistiken gibt es MediaStreamTrack.stats mit totalFrames, deliveredFrames und discardedFrames.

Rückgabewert

Typ

number

Beschreibung

Eine nicht negative Ganzzahl: die Gesamtzahl der Frames, die der Prozessor empfangen hat. Wird die Eigenschaft nicht unterstützt, liefert der Zugriff undefined.

Beispiele

Unterstützung prüfen und Wert auslesen

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const processor = new MediaStreamTrackProcessor({ track });

if ('totalFrames' in processor) {
  console.log('Empfangene Frames:', processor.totalFrames);
} else {
  console.log('totalFrames wird nicht unterstützt');
}

Empfangene Frames: 0

Verworfene Frames ermitteln

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const processor = new MediaStreamTrackProcessor({ track, maxBufferSize: 2 });
const reader = processor.readable.getReader();

let gelesen = 0;
const start = performance.now();

while (performance.now() - start < 3000) {
  const { value: frame, done } = await reader.read();
  if (done) break;
  gelesen++;
  // Absichtlich langsame Verarbeitung simulieren
  await new Promise((r) => setTimeout(r, 50));
  frame.close(); // Frame immer freigeben!
}

const gesamt = processor.totalFrames ?? gelesen;
console.log(`Gelesen: ${gelesen}, empfangen: ${gesamt}, verworfen: ${gesamt - gelesen}`);
track.stop();

Gelesen: 55, empfangen: 90, verworfen: 35

Standardisierte Alternative über MediaStreamTrack.stats

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();

setTimeout(() => {
  if (track.stats) {
    const { totalFrames, deliveredFrames, discardedFrames } = track.stats;
    console.log({ totalFrames, deliveredFrames, discardedFrames });
  }
  track.stop();
}, 2000);

{ totalFrames: 60, deliveredFrames: 60, discardedFrames: 0 }

// Wichtig · Fallstricke

Kompatibilität: MediaStreamTrackProcessor gibt es vor allem in Chromium-Browsern. totalFrames selbst ist nicht standardisiert und fehlt in vielen Umgebungen. Prüfen Sie die Unterstützung immer vorher ('totalFrames' in processor).
Laut Spezifikation soll MediaStreamTrackProcessor nur in Workern verfügbar sein. Chromium erlaubt die Nutzung zusätzlich im Haupt-Thread. Für Code, der auch künftig funktionieren soll, übertragen Sie den Track per postMessage an einen Worker.
Den Zähler können Sie nicht zurücksetzen. Brauchen Sie Werte für einen bestimmten Zeitraum, merken Sie sich den Startwert und rechnen Sie mit Differenzen.
Wenn Sie VideoFrame-Objekte nicht mit close() freigeben, füllt sich der Puffer. Das erhöht die Zahl verworfener Frames und kann den Kamerastrom blockieren.

Siehe auch

MediaStreamAudioDestinationNode.stream MediaStreamTrack.readyState MediaStreamTrackProcessor.discardedFrames MediaStreamTrackProcessor.readable MediaStreamTrackEvent.track