EncodedVideoChunk.duration — Eigenschaft · JavaScript-Referenz

Signatur

EncodedVideoChunk.duration

Beschreibung

Die Eigenschaft duration eines EncodedVideoChunk gibt an, wie lange der kodierte Frame dargestellt werden soll. Der Wert wird in Mikrosekunden angegeben, also in derselben Einheit wie timestamp. Hat man beim Erzeugen des Chunks keine Dauer übergeben, ist der Wert null.

Gesetzt wird der Wert entweder über das Init-Objekt des Konstruktors new EncodedVideoChunk({ type, timestamp, duration, data }) oder automatisch vom VideoEncoder. Der Encoder übernimmt die Dauer des eingegebenen VideoFrame. Die Eigenschaft ist schreibgeschützt. Nach dem Erzeugen lässt sich der Wert nicht mehr ändern.

Gebraucht wird duration vor allem beim Muxen, also wenn man Chunks in Container wie MP4 oder WebM schreibt. Dort braucht jede Probe eine Dauer. Außerdem hilft der Wert beim Berechnen der Gesamtlänge eines Streams und bei der zeitlichen Steuerung der Wiedergabe. Beim Dekodieren wird die Dauer an den entstehenden VideoFrame weitergegeben.

Rückgabewert

Typ

number | null

Beschreibung

Die Dauer des Chunks in Mikrosekunden als nicht-negative Ganzzahl oder null, wenn keine Dauer festgelegt wurde.

Beispiele

Dauer eines manuell erzeugten Chunks auslesen

const data = new Uint8Array([0x00, 0x00, 0x00, 0x01, 0x65]); // Beispiel-Bytes

const chunk = new EncodedVideoChunk({
  type: 'key',
  timestamp: 0,
  duration: 33333, // ca. 1/30 Sekunde
  data
});

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

33333 33.333 ms

Ohne duration ist der Wert null

const chunk = new EncodedVideoChunk({
  type: 'delta',
  timestamp: 66666,
  data: new Uint8Array(16)
});

// Fallback: Dauer aus der Bildrate ableiten
const fps = 30;
const dauer = chunk.duration ?? Math.round(1_000_000 / fps);
console.log(chunk.duration, dauer);

null 33333

Gesamtdauer beim Encodieren aufsummieren

let gesamtUs = 0;

const encoder = new VideoEncoder({
  output: (chunk) => {
    gesamtUs += chunk.duration ?? 0;
  },
  error: (e) => console.error(e)
});

encoder.configure({ codec: 'vp8', width: 640, height: 480 });

const canvas = new OffscreenCanvas(640, 480);
const ctx = canvas.getContext('2d');

for (let i = 0; i < 30; i++) {
  ctx.fillStyle = `hsl(${i * 12}, 80%, 50%)`;
  ctx.fillRect(0, 0, 640, 480);
  const frame = new VideoFrame(canvas, {
    timestamp: i * 33333,
    duration: 33333
  });
  encoder.encode(frame, { keyFrame: i === 0 });
  frame.close();
}

await encoder.flush();
console.log(`Gesamtdauer: ${(gesamtUs / 1_000_000).toFixed(2)} s`);

Gesamtdauer: 1.00 s

// Wichtig · Fallstricke

Einheit: Der Wert ist in Mikrosekunden angegeben, nicht in Millisekunden. Für Sekunden teilt man durch 1_000_000. Container wie MP4 nutzen oft eine eigene Zeitbasis (timescale). Beim Muxen muss man den Wert daher umrechnen.
null-Wert: Wurde keine Dauer angegeben, ist der Wert null. Das gilt auch für Encoder-Ausgaben, wenn der Eingabe-VideoFrame keine Dauer hatte. Einen Fallback wie ?? 0 oder einen aus der Bildrate berechneten Wert sollte man deshalb immer einplanen.
Schreibgeschützt: Eine Zuweisung wie chunk.duration = 1000 wird still ignoriert (im Strict Mode gibt es einen TypeError). Wer eine andere Dauer braucht, erzeugt einen neuen Chunk.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS). Unterstützt wird sie in Chromium-Browsern ab Version 94, in Safari ab 16.4 und in Firefox ab 130. Vorher prüfen mit 'EncodedVideoChunk' in globalThis.

Siehe auch

EncodedVideoChunk.byteLength EncodedVideoChunk.type EncodedVideoChunk.timestamp EncodedAudioChunk.duration EncodedAudioChunk.type