VideoEncoder.state — Eigenschaft · JavaScript-Referenz

Signatur

VideoEncoder.state

Beschreibung

Die Eigenschaft VideoEncoder.state zeigt, in welchem Lebenszyklus-Zustand sich der zugrunde liegende Video-Encoder gerade befindet. Sie ist schreibgeschützt und ändert sich nur durch Methodenaufrufe wie configure(), reset() und close() oder durch einen schwerwiegenden Codec-Fehler.

Mögliche Werte:

"unconfigured" – Der Encoder ist noch nicht konfiguriert. Das ist der Ausgangszustand direkt nach new VideoEncoder() und der Zustand nach reset(). In diesem Zustand löst encode() eine InvalidStateError-DOMException aus.
"configured" – Nach einem erfolgreichen Aufruf von configure() ist der Encoder bereit, VideoFrame-Objekte zu kodieren.
"closed" – Der Encoder wurde mit close() dauerhaft geschlossen oder ist wegen eines Fehlers ausgefallen (der error-Callback wurde aufgerufen). Aus diesem Zustand gibt es keinen Weg zurück; es muss eine neue Instanz erstellt werden.

In der Praxis prüft man state vor dem Aufruf von encode(), flush() oder configure(), um Ausnahmen zu vermeiden – etwa wenn Frames asynchron aus einem Kamera-Stream eintreffen, während der Encoder parallel geschlossen oder neu konfiguriert wird.

Rückgabewert

Typ

"unconfigured" | "configured" | "closed"

Beschreibung

Ein String (CodecState), der den aktuellen Zustand des Encoders beschreibt.

Beispiele

Zustandsübergänge beobachten

const encoder = new VideoEncoder({
  output: (chunk) => console.log('Chunk:', chunk.byteLength, 'Bytes'),
  error: (e) => console.error('Encoder-Fehler:', e)
});

console.log(encoder.state); // Ausgangszustand

encoder.configure({
  codec: 'vp8',
  width: 640,
  height: 480,
  bitrate: 1_000_000,
  framerate: 30
});
console.log(encoder.state);

encoder.reset();
console.log(encoder.state);

encoder.close();
console.log(encoder.state);

unconfigured configured unconfigured closed

Frames nur im gültigen Zustand kodieren

const encodeFrame = (encoder, frame, keyFrame = false) => {
  if (encoder.state !== 'configured') {
    console.warn(`Frame verworfen – Encoder ist ${encoder.state}`);
    frame.close(); // Speicher trotzdem freigeben
    return false;
  }
  encoder.encode(frame, { keyFrame });
  frame.close();
  return true;
};

// Einsatz mit einem Canvas als Quelle
const canvas = new OffscreenCanvas(320, 240);
const frame = new VideoFrame(canvas, { timestamp: 0 });
const encoder = new VideoEncoder({ output: () => {}, error: console.error });
console.log(encodeFrame(encoder, frame));

Frame verworfen – Encoder ist unconfigured false

Sauberes Beenden mit flush() und close()

const finishEncoding = async (encoder) => {
  if (encoder.state === 'configured') {
    await encoder.flush(); // ausstehende Chunks ausgeben
  }
  if (encoder.state !== 'closed') {
    encoder.close();
  }
  console.log('Endzustand:', encoder.state);
};

const encoder = new VideoEncoder({ output: () => {}, error: console.error });
encoder.configure({ codec: 'vp8', width: 320, height: 240 });
await finishEncoding(encoder);

Endzustand: closed

Encoder nach Fehler neu erzeugen

let encoder;
const config = { codec: 'avc1.42001f', width: 1280, height: 720, bitrate: 2_000_000 };

const createEncoder = () => {
  encoder = new VideoEncoder({
    output: (chunk) => { /* Chunk an Muxer weitergeben */ },
    error: (e) => {
      console.error('Fehler, Zustand jetzt:', encoder.state);
      createEncoder(); // "closed" ist endgültig – neue Instanz nötig
    }
  });
  encoder.configure(config);
};

const { supported } = await VideoEncoder.isConfigSupported(config);
if (supported) createEncoder();

// Wichtig · Fallstricke

„closed“ ist endgültig: Nach close() oder einem Codec-Fehler lösen configure(), encode(), flush() und reset() eine InvalidStateError-Ausnahme aus. Es muss ein neuer VideoEncoder erzeugt werden.
Asynchrone Konfiguration: state wechselt direkt nach configure() auf "configured", obwohl die eigentliche Konfiguration asynchron läuft. Eine nicht unterstützte Konfiguration fällt erst später über den error-Callback auf, dann wechselt der Zustand zu "closed". Deshalb vorher mit VideoEncoder.isConfigSupported() prüfen.
Kein Event für Zustandswechsel: Es gibt kein statechange-Event. Auf Fehler reagiert man über den error-Callback, auf Rückstau über das dequeue-Event bzw. encodeQueueSize.
Die Eigenschaft ist schreibgeschützt: Eine Zuweisung wie encoder.state = "closed" wird ignoriert bzw. löst im Strict Mode einen TypeError aus.
Kompatibilität: Die WebCodecs API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, im Fenster und in Dedicated Workers. Firefox unterstützt VideoEncoder erst ab Version 130, Safari ab 16.4. Mit 'VideoEncoder' in globalThis auf Unterstützung prüfen.
Kodierte VideoFrame-Objekte immer mit frame.close() freigeben, auch wenn sie wegen eines falschen Zustands verworfen werden. Sonst droht ein Speicherleck bei GPU-Ressourcen.

Siehe auch

VideoEncoder.encodeQueueSize VideoDecoder.state AudioEncoder.state AudioDecoder.state MediaRecorder.state