new EncodedVideoChunk() — Methode · JavaScript-Referenz

Signatur

new EncodedVideoChunk(options)

Beschreibung

Der Konstruktor EncodedVideoChunk() gehört zur WebCodecs API. Er verpackt rohe, bereits komprimierte Videodaten (z. B. einen H.264-, VP8/VP9- oder AV1-Frame) zusammen mit Metadaten wie Frame-Typ, Zeitstempel und Dauer in ein Objekt, das an VideoDecoder.prototype.decode() übergeben werden kann.

Typischerweise nutzt man den Konstruktor, wenn man Videodaten selbst aus einem Container (MP4, WebM) herauslöst – etwa mit einer Demuxer-Bibliothek wie mp4box.js – oder wenn kodierte Frames über das Netzwerk empfangen werden (WebTransport, WebSocket, WebRTC-Datenkanäle). Chunks, die ein VideoEncoder erzeugt, erhält man dagegen bereits fertig im output-Callback.

Ein erzeugtes Chunk ist unveränderlich: Die Daten werden beim Erzeugen kopiert (oder mit der Option transfer übertragen), und später lassen sie sich nur über copyTo() wieder auslesen. Zeitstempel und Dauer werden in Mikrosekunden angegeben.

Rückgabewert

Typ

EncodedVideoChunk

Beschreibung

Ein neues, unveränderliches EncodedVideoChunk-Objekt mit den Eigenschaften type, timestamp, duration und byteLength.

Beispiele

Chunk aus Rohdaten erzeugen

// Beispielhafte Bytes eines kodierten Keyframes
const bytes = new Uint8Array([0x00, 0x00, 0x00, 0x01, 0x65, 0x88, 0x84]);

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

console.log(chunk.type, chunk.timestamp, chunk.duration, chunk.byteLength);

key 0 33333 7

Demuxte Samples an einen VideoDecoder übergeben

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const decoder = new VideoDecoder({
  output: (frame) => {
    ctx.drawImage(frame, 0, 0);
    frame.close(); // Speicher sofort freigeben
  },
  error: (e) => console.error('Dekodierfehler:', e),
});

decoder.configure({ codec: 'vp8', codedWidth: 640, codedHeight: 480 });

// samples stammen z. B. aus einem WebM-Demuxer
const decodeSamples = async (samples) => {
  for (const s of samples) {
    decoder.decode(new EncodedVideoChunk({
      type: s.isKeyframe ? 'key' : 'delta',
      timestamp: s.timestampUs,
      duration: s.durationUs,
      data: s.data,
    }));
  }
  await decoder.flush();
  console.log('Alle Frames dekodiert');
};

Alle Frames dekodiert

Daten ohne Kopie übertragen (transfer)

const buffer = new ArrayBuffer(1024);

const chunk = new EncodedVideoChunk({
  type: 'delta',
  timestamp: 66_666,
  data: buffer,
  transfer: [buffer], // Puffer wird übernommen statt kopiert
});

console.log(chunk.byteLength);  // Daten im Chunk
console.log(buffer.byteLength); // Original ist jetzt abgetrennt

1024 0

Daten eines Chunks wieder auslesen

const chunk = new EncodedVideoChunk({
  type: 'key',
  timestamp: 0,
  data: new Uint8Array([1, 2, 3, 4]),
});

const copy = new Uint8Array(chunk.byteLength);
chunk.copyTo(copy);
console.log(copy);

Uint8Array(4) [1, 2, 3, 4]

// Wichtig · Fallstricke

Einheiten: timestamp und duration sind Mikrosekunden, nicht Millisekunden. Container wie MP4 nutzen eigene Zeitbasen (timescale) – umrechnen: sample.cts * 1e6 / sample.timescale.
Erster Chunk muss ein Keyframe sein: Nach configure() oder flush() erwartet der VideoDecoder einen Chunk mit type: 'key', sonst wird ein DataError ausgelöst.
Fehlen Pflichtfelder oder sind timestamp/duration ungültig, wirft der Konstruktor einen TypeError.
Ohne transfer werden die Daten kopiert – bei hohen Bitraten kann das spürbar Speicher und CPU kosten. Mit transfer ist der Originalpuffer danach unbrauchbar; die Option ist neuer und nicht in allen Browsern verfügbar.
Kompatibilität: Nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster und in Dedicated Workers. Firefox unterstützt WebCodecs erst ab Version 130, Safari ab 16.4. Vorher per 'EncodedVideoChunk' in globalThis prüfen.
Das Chunk-Format (Annex B oder AVCC bei H.264) muss zur Decoder-Konfiguration passen – bei AVCC ist ein description-Feld in configure() nötig.

Siehe auch

new EncodedAudioChunk() new RTCEncodedVideoFrame() new BarcodeDetector() new ErrorEvent() new RTCEncodedAudioFrame()