AudioDecoder.reset() — Methode · JavaScript-Referenz

Signatur

AudioDecoder.prototype.reset()

Beschreibung

Die Methode reset() bricht alle laufenden und wartenden Arbeiten eines AudioDecoder ab. Alle Steuerungsnachrichten in der Warteschlange, also noch nicht verarbeitete decode()- und configure()-Aufrufe, werden verworfen, decodeQueueSize fällt auf 0 und die aktuelle Konfiguration wird gelöscht. Danach steht state auf "unconfigured".

Alle noch offenen Promises von flush() werden mit einer DOMException vom Typ AbortError abgelehnt. Bereits dekodierte, aber noch nicht ausgegebene AudioData-Frames werden nicht mehr an den output-Rückruf übergeben. Der error-Rückruf wird durch reset() nicht ausgelöst.

Typische Einsatzfälle sind Sprünge (Seeking) in einem Audio-Player, ein Wechsel des Codecs oder der Quelle und das Verwerfen veralteter Daten, etwa bei Live-Streams mit hoher Latenz. Im Gegensatz zu close() bleibt der Decoder nutzbar: Nach einem erneuten configure() kann er sofort weiterdekodieren. Das spart das Anlegen eines neuen Objekts samt Rückrufen.

Nach reset() muss der erste dekodierte Chunk ein Schlüssel-Chunk sein (type: "key"), weil der Decoder keinen Kontext aus früheren Daten mehr hat.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode arbeitet synchron. Offene flush()-Promises werden mit AbortError abgelehnt.

Beispiele

Seeking in einem Audio-Player

const config = { codec: 'opus', sampleRate: 48000, numberOfChannels: 2 };

const decoder = new AudioDecoder({
  output: (audioData) => {
    // hier z. B. an einen AudioWorklet übergeben
    audioData.close();
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});
decoder.configure(config);

// chunks: Array aus { timestamp, data: ArrayBuffer } (z. B. aus einem Demuxer)
const seekTo = (chunks, zielMikrosekunden) => {
  decoder.reset();             // alte Daten und Warteschlange verwerfen
  console.log(decoder.state);  // "unconfigured"
  decoder.configure(config);   // neu konfigurieren

  chunks
    .filter((c) => c.timestamp >= zielMikrosekunden)
    .forEach((c) => decoder.decode(new EncodedAudioChunk({
      type: 'key',
      timestamp: c.timestamp,
      data: c.data
    })));
};

unconfigured

Abgebrochenes flush() abfangen

const decoder = new AudioDecoder({
  output: (data) => data.close(),
  error: (e) => console.error(e)
});
decoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 2 });

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

try {
  await flushPromise;
} catch (err) {
  console.log(err.name);                // "AbortError"
  console.log(decoder.decodeQueueSize);  // 0
}

AbortError 0

Sicheres Zurücksetzen mit Zustandsprüfung

const safeReset = (decoder) => {
  if (decoder.state === 'closed') {
    console.warn('Decoder ist geschlossen, reset() nicht möglich.');
    return false;
  }
  decoder.reset();
  return true;
};

const decoder = new AudioDecoder({ output: (d) => d.close(), error: console.error });
decoder.close();
console.log(safeReset(decoder));

Decoder ist geschlossen, reset() nicht möglich. false

// Wichtig · Fallstricke

InvalidStateError: Ist der Decoder bereits "closed", wirft reset() eine DOMException vom Typ InvalidStateError. Auf einem Decoder im Zustand "unconfigured" ist der Aufruf dagegen erlaubt und bewirkt praktisch nichts.
Neu konfigurieren: Nach reset() wirft jeder decode()-Aufruf einen InvalidStateError, bis wieder configure() aufgerufen wurde.
Schlüssel-Chunk: Der erste Chunk nach dem Neukonfigurieren muss type: "key" haben, sonst tritt ein DataError auf.
Speicher: AudioData-Objekte, die schon an output übergeben wurden, bleiben gültig und müssen weiterhin selbst mit close() freigegeben werden.
reset() oder close(): reset() behält die Decoder-Instanz. close() gibt die Ressourcen endgültig frei. Wird der Decoder nicht mehr gebraucht, solltest du close() nutzen.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in dedizierten Workern. Chromium-Browser unterstützen sie seit Version 94, Firefox seit 130, Safari erst in neueren Versionen. Prüfe vorher die Verfügbarkeit mit 'AudioDecoder' in globalThis.

Siehe auch

AudioDecoder AudioDecoder.configure() AudioDecoder.decode() AudioDecoder.flush() AudioDecoder.close() AudioDecoder.state EncodedAudioChunk VideoDecoder.reset()