AudioDecoder.flush() — Methode · JavaScript-Referenz

Signatur

AudioDecoder.prototype.flush()

Beschreibung

Die Methode flush() der Schnittstelle AudioDecoder zwingt den Decoder, alle noch in der internen Warteschlange liegenden EncodedAudioChunk-Objekte zu verarbeiten. Das zurückgegebene Promise wird erst aufgelöst, wenn für jeden bis dahin mit decode() übergebenen Chunk der output-Callback aufgerufen wurde.

Typische Einsatzfälle sind das Ende eines Datenstroms (letzte Frames sollen nicht verloren gehen), das Umschalten der Konfiguration per configure() oder das saubere Beenden, bevor close() aufgerufen wird. Viele Decoder puffern intern einige Frames; ohne flush() erhält man diese letzten Ausgaben unter Umständen nie.

Nach einem flush() erwartet der Decoder als nächsten Chunk einen Schlüssel-Chunk (type: "key"). Die Methode ist nur gültig, wenn der Decoder im Zustand "configured" ist; andernfalls wird das Promise mit einem InvalidStateError abgelehnt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined aufgelöst wird, sobald alle ausstehenden Dekodier-Aufträge abgeschlossen und ausgegeben sind. Es wird abgelehnt, wenn der Decoder nicht konfiguriert ist, während des Flushens reset()/close() aufgerufen wird oder ein Dekodierfehler auftritt.

Beispiele

Letzte Frames am Stream-Ende abholen

const frames = [];

const decoder = new AudioDecoder({
  output: (audioData) => {
    frames.push(audioData.numberOfFrames);
    audioData.close(); // Speicher freigeben
  },
  error: (e) => console.error('Dekodierfehler:', e)
});

decoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2
});

// encodedChunks: Array von EncodedAudioChunk, z. B. aus einem Demuxer
const decodeAll = async (encodedChunks) => {
  for (const chunk of encodedChunks) {
    decoder.decode(chunk);
  }
  await decoder.flush(); // wartet, bis alle Ausgaben geliefert sind
  console.log(`Fertig: ${frames.length} AudioData-Blöcke`);
  decoder.close();
};

Fertig: 250 AudioData-Blöcke

Konfiguration sicher wechseln

const switchConfig = async (decoder, newConfig) => {
  // Ausstehende Chunks mit alter Konfiguration abschließen
  await decoder.flush();
  const { supported } = await AudioDecoder.isConfigSupported(newConfig);
  if (!supported) throw new Error('Konfiguration nicht unterstützt');
  decoder.configure(newConfig);
  // Danach muss ein Schlüssel-Chunk (type: 'key') folgen
};

Fehlerbehandlung bei falschem Zustand

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

try {
  await decoder.flush(); // noch nicht konfiguriert
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Zustand prüfen: Im Zustand "unconfigured" oder "closed" wird das Promise mit InvalidStateError abgelehnt. Wird während des Flushens reset() oder close() aufgerufen, wird es mit AbortError abgelehnt.
Schlüssel-Chunk erforderlich: Nach flush() muss der nächste an decode() übergebene Chunk vom Typ "key" sein, sonst wird ein DataError geworfen.
Nicht ständig flushen: flush() leert interne Puffer und kann die Pipeline ausbremsen. Für Gegendruck besser decodeQueueSize und das dequeue-Event nutzen.
Speicher: Jedes ausgegebene AudioData muss mit close() freigegeben werden.
Kompatibilität: WebCodecs ist nur in sicheren Kontexten (HTTPS) und in Window sowie dedizierten Workern verfügbar; Firefox und Safari unterstützen AudioDecoder erst seit neueren Versionen. Vorher per 'AudioDecoder' in globalThis prüfen.

Siehe auch

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