VideoDecoder.reset() — Methode · JavaScript-Referenz

Signatur

VideoDecoder.prototype.reset()

Beschreibung

Die Methode reset() bricht alle laufenden und wartenden Arbeiten eines VideoDecoder sofort ab. Die aktuelle Konfiguration wird verworfen, die Steuerungsnachrichten-Warteschlange (also noch nicht verarbeitete decode()- und configure()-Aufrufe) wird geleert, und decodeQueueSize fällt auf 0. Promises von ausstehenden flush()-Aufrufen werden mit einer DOMException vom Typ AbortError abgelehnt.

Anders als close() bleibt der Decoder danach benutzbar: Sein state ist "unconfigured" und er lässt sich mit configure() neu einrichten. Das ist vor allem beim Spulen (Seeking) in einem Videoplayer nützlich. Wenn der Nutzer an eine andere Stelle springt, sollen bereits eingereihte Chunks nicht mehr dekodiert werden. Stattdessen setzt man den Decoder zurück, konfiguriert ihn neu und beginnt beim nächsten Keyframe.

Weil die Konfiguration verloren geht, muss nach reset() immer zuerst configure() aufgerufen werden. Außerdem muss der erste dekodierte Chunk danach ein Keyframe sein (type: "key"). Andernfalls wirft decode() einen DataError.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Der Vorgang läuft synchron ab.

Beispiele

Decoder zurücksetzen und Zustand prüfen

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

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

decoder.reset();
console.log(decoder.state);
console.log(decoder.decodeQueueSize);

configured unconfigured 0

Spulen im Videoplayer: Warteschlange verwerfen und neu starten

// chunks: Array aus EncodedVideoChunk, config: VideoDecoderConfig (z. B. aus einem Demuxer)
const seekTo = (decoder, config, chunks, targetUs) => {
  // Laufende Arbeit abbrechen, Konfiguration geht verloren
  decoder.reset();
  decoder.configure(config);

  // Letzten Keyframe vor der Zielzeit suchen
  let start = 0;
  chunks.forEach((c, i) => {
    if (c.type === 'key' && c.timestamp <= targetUs) start = i;
  });

  // Ab dem Keyframe dekodieren
  for (const chunk of chunks.slice(start)) {
    decoder.decode(chunk);
  }
};

Ausstehendes flush() wird mit AbortError abgelehnt

const decoder = new VideoDecoder({
  output: (frame) => frame.close(),
  error: (e) => console.error(e)
});
decoder.configure({ codec: 'vp8', codedWidth: 320, codedHeight: 240 });

const pending = decoder.flush();
decoder.reset();

try {
  await pending;
} catch (err) {
  console.log(err.name);
}

AbortError

// Wichtig · Fallstricke

Geschlossener Decoder: Ist state gleich "closed", wirft reset() eine InvalidStateError-DOMException. Nach close() oder einem Fehler lässt sich der Decoder nicht mehr zurücksetzen. Dann muss eine neue Instanz erzeugt werden.
Neu konfigurieren ist Pflicht: Ein decode() direkt nach reset() ohne vorheriges configure() wirft einen InvalidStateError.
Keyframe erforderlich: Nach dem Zurücksetzen muss der erste Chunk ein Keyframe sein, sonst gibt es einen DataError.
VideoFrames freigeben: Frames, die schon an den output-Callback übergeben wurden, sind von reset() nicht betroffen. Du musst sie weiterhin selbst mit frame.close() freigeben, sonst läuft der Grafikspeicher voll.
reset() oder close(): Wenn du den Decoder wiederverwenden willst, nimm reset(). close() gibt dagegen alle Systemressourcen endgültig frei.
Kompatibilität: Die WebCodecs-API gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in Dedicated Workern. Vor der Nutzung mit 'VideoDecoder' in globalThis prüfen.

Siehe auch

VideoDecoder.close() VideoDecoder.decode() VideoDecoder.flush() VideoDecoder.configure() VideoDecoder.isConfigSupported()