VideoDecoder.state — Eigenschaft · JavaScript-Referenz

Signatur

get VideoDecoder.prototype.state

Beschreibung

Die schreibgeschützte Eigenschaft state gibt an, in welchem Zustand sich der zugrundeliegende Codec eines VideoDecoder gerade befindet. Sie ist die zentrale Prüfgröße, bevor man Methoden wie decode(), flush() oder configure() aufruft. Wer diese Methoden im falschen Zustand aufruft, bekommt eine InvalidStateError-DOMException.

Mögliche Werte:

"unconfigured" – Der Codec ist noch nicht für die Dekodierung eingerichtet. Das ist der Ausgangszustand nach new VideoDecoder() und der Zustand nach reset().
"configured" – configure() wurde erfolgreich aufgerufen, der Codec nimmt Daten über decode() an.
"closed" – Der Codec ist dauerhaft geschlossen und kann nicht weiter verwendet werden, entweder durch close() oder nach einem schweren Fehler (dann wird zusätzlich der error-Callback aufgerufen).

Beachte: Der Wechsel auf "configured" passiert synchron beim Aufruf von configure(), auch wenn die eigentliche Konfiguration asynchron abläuft. Scheitert sie später (z. B. bei nicht unterstütztem Codec), wechselt der Zustand auf "closed" und der error-Callback wird ausgelöst. Deshalb vorab mit VideoDecoder.isConfigSupported() prüfen.

Rückgabewert

Typ

"unconfigured" | "configured" | "closed"

Beschreibung

Eine Zeichenkette aus dem Enum CodecState, die den aktuellen Zustand des Decoders beschreibt.

Beispiele

Zustandswechsel im Lebenszyklus beobachten

const decoder = new VideoDecoder({
  output: (frame) => frame.close(),
  error: (e) => console.error('Decoder-Fehler:', e)
});

console.log(decoder.state); // direkt nach Erzeugung

decoder.configure({ codec: 'vp8', codedWidth: 640, codedHeight: 480 });
console.log(decoder.state); // nach configure()

decoder.reset();
console.log(decoder.state); // nach reset()

decoder.close();
console.log(decoder.state); // nach close()

unconfigured configured unconfigured closed

Sicheres Dekodieren nur im Zustand "configured"

const safeDecode = (decoder, chunk) => {
  if (decoder.state !== 'configured') {
    console.warn(`Chunk verworfen – Decoder ist "${decoder.state}"`);
    return false;
  }
  decoder.decode(chunk);
  return true;
};

const decoder = new VideoDecoder({
  output: (frame) => frame.close(),
  error: console.error
});

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

safeDecode(decoder, chunk);

Chunk verworfen – Decoder ist "unconfigured"

Decoder nach Fehler automatisch neu anlegen

const config = { codec: 'avc1.42E01E', codedWidth: 1280, codedHeight: 720 };
let decoder;

const createDecoder = async () => {
  const { supported } = await VideoDecoder.isConfigSupported(config);
  if (!supported) throw new Error('Codec nicht unterstützt');

  decoder = new VideoDecoder({
    output: (frame) => {
      // Frame z. B. auf Canvas zeichnen
      frame.close();
    },
    error: (e) => {
      console.error(e.message, '– Zustand:', decoder.state);
      // Nach einem Fehler ist der Decoder immer "closed"
      if (decoder.state === 'closed') createDecoder();
    }
  });
  decoder.configure(config);
};

await createDecoder();
console.log(decoder.state);

configured

// Wichtig · Fallstricke

Schreibgeschützt: decoder.state = 'configured' hat keine Wirkung (im Strict Mode TypeError). Den Zustand ändern nur configure(), reset() und close().
"closed" ist endgültig: Einen geschlossenen Decoder kann man nicht wieder öffnen. Man muss eine neue Instanz anlegen. configure(), decode(), flush() und reset() werfen dann einen InvalidStateError.
Kein Beleg für Erfolg: "configured" heißt nicht, dass die Konfiguration geklappt hat. Sie kann danach noch asynchron scheitern. Prüfe sie vorher mit VideoDecoder.isConfigSupported().
Kein Event für Zustandswechsel: Es gibt kein eigenes Event für Änderungen von state. Reagiere im error-Callback und prüfe den Zustand vor jedem Aufruf. Für die Auslastung gibt es decodeQueueSize und das Event dequeue.
Kompatibilität: WebCodecs gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in Dedicated Workern. Firefox unterstützt die API erst ab Version 130, ältere Safari-Versionen nicht. Prüfe die Unterstützung mit 'VideoDecoder' in globalThis.

Siehe auch

VideoDecoder.decodeQueueSize VideoEncoder.state AudioDecoder.state AudioEncoder.state MediaRecorder.state