VideoFrame.duration — Eigenschaft · JavaScript-Referenz

Signatur

VideoFrame.duration

Beschreibung

VideoFrame.duration gehört zur WebCodecs API und gibt an, wie lange ein einzelnes Videobild angezeigt werden soll. Der Wert ist eine ganze Zahl in Mikrosekunden (1 s = 1 000 000 µs). Er beschreibt also nicht die Länge des gesamten Videos, sondern nur die Dauer dieses einen Frames.

Die Dauer wird entweder beim Erzeugen über die Option duration im Konstruktor new VideoFrame(source, { timestamp, duration }) gesetzt oder vom VideoDecoder aus der Dauer des zugehörigen EncodedVideoChunk übernommen. Wurde keine Dauer angegeben, ist der Wert null.

Zusammen mit VideoFrame.timestamp nutzt man duration typischerweise für das zeitgenaue Rendern, zur Berechnung der Bildrate, zum Synchronisieren mit Audio oder beim Weitergeben von Frames an einen VideoEncoder, damit der erzeugte Stream korrekte Zeitangaben enthält.

Rückgabewert

Typ

number | null

Beschreibung

Ganzzahlige Dauer des Frames in Mikrosekunden oder null, wenn keine Dauer gesetzt wurde.

Beispiele

Dauer beim Erzeugen eines Frames setzen und auslesen

const canvas = new OffscreenCanvas(640, 360);
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'teal';
ctx.fillRect(0, 0, 640, 360);

// 30 fps → ca. 33 333 µs pro Frame
const frame = new VideoFrame(canvas, {
  timestamp: 0,
  duration: Math.round(1_000_000 / 30)
});

console.log(frame.duration);
console.log(`${frame.duration / 1000} ms`);
frame.close();

33333 33.333 ms

Ohne Dauer erzeugter Frame liefert null

const canvas = new OffscreenCanvas(320, 240);
canvas.getContext('2d').fillRect(0, 0, 320, 240);

const frame = new VideoFrame(canvas, { timestamp: 0 });
console.log(frame.duration); // keine Dauer angegeben
frame.close();

null

Bildrate aus dekodierten Frames ermitteln

const decoder = new VideoDecoder({
  output: (frame) => {
    if (frame.duration) {
      const fps = 1_000_000 / frame.duration;
      console.log(`t=${frame.timestamp} µs, Dauer=${frame.duration} µs, ~${fps.toFixed(2)} fps`);
    }
    frame.close(); // Speicher freigeben!
  },
  error: (e) => console.error('Dekodierfehler:', e)
});

// decoder.configure({...}) und decoder.decode(new EncodedVideoChunk({ type: 'key', timestamp: 0, duration: 40000, data })) 
// → Dauer wird aus dem Chunk übernommen

t=0 µs, Dauer=40000 µs, ~25.00 fps

// Wichtig · Fallstricke

Einheit Mikrosekunden: Nicht mit Millisekunden (performance.now()) oder Sekunden (HTMLMediaElement.currentTime) verwechseln – vor dem Vergleich umrechnen.
Kann null sein: Vor Berechnungen wie 1_000_000 / frame.duration immer auf null prüfen.
Die Eigenschaft ist schreibgeschützt. Um die Dauer zu ändern, erzeugt man einen neuen Frame: new VideoFrame(frame, { duration: … }).
Nach frame.close() sollte der Frame nicht mehr verwendet werden; vergessene close()-Aufrufe führen schnell zu Speicherengpässen und blockierten Decodern.
Kompatibilität: WebCodecs ist nur in sicheren Kontexten (HTTPS) verfügbar und wird in Chromium-Browsern vollständig, in Safari und Firefox erst in neueren Versionen unterstützt – per 'VideoFrame' in globalThis prüfen.

Siehe auch

VideoFrame VideoFrame.timestamp VideoFrame.close() EncodedVideoChunk.duration VideoDecoder AudioData.duration AnimationTimeline.duration