AudioDecoder: dequeue — Ereignis · JavaScript-Referenz

Signatur

audioDecoder.addEventListener("dequeue", handler)

Beschreibung

Das dequeue-Ereignis der Schnittstelle AudioDecoder signalisiert, dass der Decoder einen oder mehrere zuvor per decode() übergebene EncodedAudioChunk-Objekte aus seiner internen Warteschlange entnommen hat. Dadurch ist AudioDecoder.decodeQueueSize gesunken. Es handelt sich um ein einfaches Event ohne zusätzliche Eigenschaften und es steigt nicht im Baum auf (keine Bubbling-Phase).

Der wichtigste Einsatzzweck ist die Gegendrucksteuerung (Backpressure): Statt alle Chunks auf einmal in den Decoder zu schieben und dadurch viel Speicher zu belegen, übergibt man nur so viele, bis decodeQueueSize einen Schwellwert erreicht, und wartet danach auf dequeue, um weitere Daten nachzuschieben. Das ersetzt aufwendiges Polling mit setTimeout.

Man registriert den Handler entweder per addEventListener("dequeue", handler) oder über die Eigenschaft ondequeue. Der Browser kann mehrere Entnahmen zu einem einzigen Ereignis zusammenfassen – man sollte also im Handler immer den aktuellen Wert von decodeQueueSize lesen und nicht davon ausgehen, dass pro Ereignis genau ein Chunk verarbeitet wurde.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"dequeue"`.
$handler Pflicht	(event: Event) => void		Callback, der mit einem einfachen `Event`-Objekt aufgerufen wird. `event.target` ist der auslösende `AudioDecoder`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event ohne zusätzliche Daten.

Beispiele

Warteschlangengröße per addEventListener beobachten

const decoder = new AudioDecoder({
  output: (audioData) => {
    // Dekodierte Samples weiterverarbeiten
    audioData.close();
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

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

decoder.addEventListener('dequeue', () => {
  console.log('Verbleibend in der Warteschlange:', decoder.decodeQueueSize);
});

Verbleibend in der Warteschlange: 3 Verbleibend in der Warteschlange: 2 …

Backpressure: Chunks nur bei freier Kapazität nachschieben

const MAX_QUEUE = 8;

const decodeAll = async (decoder, chunks) => {
  // Wartet, bis der Decoder wieder Platz hat
  const waitForDequeue = () =>
    new Promise((resolve) =>
      decoder.addEventListener('dequeue', resolve, { once: true })
    );

  for (const chunk of chunks) {
    while (decoder.decodeQueueSize >= MAX_QUEUE) {
      await waitForDequeue();
    }
    decoder.decode(chunk);
  }
  await decoder.flush();
  console.log('Alle Chunks dekodiert');
};

Alle Chunks dekodiert

ondequeue-Eigenschaft setzen und wieder entfernen

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

decoder.ondequeue = () => {
  if (decoder.decodeQueueSize === 0) {
    console.log('Warteschlange leer – neue Daten anfordern');
  }
};

// Später: Handler abmelden
decoder.ondequeue = null;

Warteschlange leer – neue Daten anfordern

Listener per AbortController entfernen

const controller = new AbortController();
const onDequeue = () => console.log('Größe:', decoder.decodeQueueSize);

decoder.addEventListener('dequeue', onDequeue, { signal: controller.signal });

// Alternativ: decoder.removeEventListener('dequeue', onDequeue);
controller.abort();

// Wichtig · Fallstricke

Zusammengefasste Ereignisse: Mehrere Entnahmen können ein einziges dequeue auslösen. Immer decodeQueueSize neu auslesen, nicht mitzählen.
Kein Hinweis auf fertige Ausgabe: dequeue bedeutet nur, dass ein Chunk aus der Warteschlange übernommen wurde – die dekodierten AudioData-Objekte kommen separat über den output-Callback.
Nach close() oder reset(): Wartende Promises, die auf dequeue hoffen, können hängen bleiben. Bei Abbruch Listener entfernen bzw. Promises zusätzlich über den error-Callback oder ein AbortSignal auflösen.
Speicher: AudioData im output-Callback stets mit close() freigeben, sonst staut sich der Decoder trotz Backpressure.
Kompatibilität: Die WebCodecs-API ist nur in sicheren Kontexten (HTTPS) und in Window sowie Dedicated Workern verfügbar. AudioDecoder wird von Chromium-Browsern seit Version 94 unterstützt, von Firefox seit 130; Safari hat Audio-Unterstützung erst spät ergänzt. Vorher mit 'AudioDecoder' in globalThis und AudioDecoder.isConfigSupported() prüfen.

Siehe auch

AudioDecoder AudioDecoder.decodeQueueSize AudioDecoder.prototype.decode() AudioDecoder.prototype.flush() AudioEncoder: dequeue