VideoEncoder.reset() — Methode · JavaScript-Referenz

Signatur

VideoEncoder.prototype.reset()

Beschreibung

Mit reset() setzen Sie einen VideoEncoder sofort in den Zustand "unconfigured" zurück. Frames, die noch in der Warteschlange liegen, werden verworfen. Für sie gibt es keinen output-Rückruf mehr. Promises, die durch flush() entstanden und noch offen sind, werden mit einer AbortError-DOMException abgelehnt. Außerdem gibt der Encoder die zugrundeliegenden Codec-Ressourcen frei.

Anders als bei close() bleibt die Instanz nutzbar. Nach einem erneuten configure() kann sie wieder codieren. Das ist praktisch, wenn Sie die Codierung mitten im Lauf mit anderen Parametern neu starten wollen, etwa mit neuer Auflösung, anderer Bitrate oder einem anderen Codec. Es hilft auch, wenn Sie eine laufende Aufnahme ohne Ergebnis abbrechen möchten.

Die Methode arbeitet synchron und liefert kein Promise. Direkt nach dem Aufruf gilt encodeQueueSize === 0 und state === "unconfigured". Wenn Sie die bereits eingereihten Frames noch als Ausgabe brauchen, rufen Sie vorher await encoder.flush() auf.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Encoder zurücksetzen und mit neuer Auflösung neu konfigurieren

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

encoder.configure({ codec: 'vp8', width: 1280, height: 720, bitrate: 2_000_000 });
console.log(encoder.state);

// Nutzer wechselt auf niedrigere Qualität: alles verwerfen und neu starten
encoder.reset();
console.log(encoder.state, encoder.encodeQueueSize);

encoder.configure({ codec: 'vp8', width: 640, height: 360, bitrate: 800_000 });
console.log(encoder.state);

configured unconfigured 0 configured

Laufende Aufnahme abbrechen – offenes flush() wird abgelehnt

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

const canvas = new OffscreenCanvas(320, 240);
const ctx = canvas.getContext('2d');
for (let i = 0; i < 30; i++) {
  ctx.fillStyle = `hsl(${i * 12}, 80%, 50%)`;
  ctx.fillRect(0, 0, 320, 240);
  const frame = new VideoFrame(canvas, { timestamp: i * 33_333 });
  encoder.encode(frame);
  frame.close();
}

encoder.flush().catch((err) => console.log('flush abgebrochen:', err.name));
encoder.reset(); // synchroner Abbruch

flush abgebrochen: AbortError

Erst leeren, dann sicher zurücksetzen

const restartEncoder = async (encoder, newConfig) => {
  if (encoder.state === 'closed') throw new Error('Encoder bereits geschlossen');
  if (encoder.state === 'configured') {
    await encoder.flush(); // alle ausstehenden Chunks noch ausgeben
  }
  encoder.reset();
  const { supported } = await VideoEncoder.isConfigSupported(newConfig);
  if (!supported) throw new Error('Konfiguration nicht unterstützt');
  encoder.configure(newConfig);
};

// Aufruf:
// await restartEncoder(encoder, { codec: 'avc1.42001f', width: 1920, height: 1080 });

// Wichtig · Fallstricke

Ist der Encoder bereits geschlossen (state === "closed"), wirft reset() eine InvalidStateError-DOMException. Nach close() kommen Sie nur mit einer neuen Instanz weiter.
Nach reset() wirft jeder Aufruf von encode() eine InvalidStateError, bis Sie wieder configure() aufrufen.
Verworfene Frames erzeugen keinen output-Rückruf. Wenn Sie keine Daten verlieren wollen, rufen Sie vorher await flush() auf.
Offene flush()-Promises werden mit AbortError abgelehnt. Fangen Sie das mit .catch() ab, sonst erscheinen Warnungen zu nicht behandelten Ablehnungen.
Nach reset() muss der erste codierte Frame ein Schlüsselbild sein. Der Encoder erzeugt es in der Regel automatisch. Für Streaming-Empfänger ist ein neuer Decoder-Kontext trotzdem sinnvoll, gegebenenfalls mit decoderConfig aus den Metadaten.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in Workern. Die Unterstützung für einzelne Codecs unterscheidet sich je nach Browser. Prüfen Sie sie mit VideoEncoder.isConfigSupported().

Siehe auch

VideoEncoder.close() VideoEncoder.flush() VideoEncoder.encode() VideoEncoder.configure() VideoEncoder.isConfigSupported()