AudioEncoder: dequeue — Ereignis · JavaScript-Referenz

Signatur

audioEncoder.addEventListener("dequeue", handler)

Beschreibung

Das dequeue-Ereignis gehört zum Interface AudioEncoder der WebCodecs API. Der Browser löst es aus, wenn ein Kodierauftrag aus der internen Warteschlange an den Codec übergeben wurde und encodeQueueSize dadurch kleiner geworden ist. Das Ereignis ist ein einfaches Event ohne zusätzliche Daten; den aktuellen Stand liest man direkt über encoder.encodeQueueSize aus.

Das Ereignis ist vor allem für Gegendruck (engl. Backpressure) gedacht. Statt encodeQueueSize in einer Schleife abzufragen oder beliebig viele AudioData-Objekte mit encode() einzureihen, kann man warten, bis der Encoder wieder Kapazität hat. So wächst der Speicherverbrauch nicht unkontrolliert, etwa beim Kodieren eines Mikrofon-Streams oder einer großen Audiodatei.

Registrieren kann man den Handler über addEventListener("dequeue", handler) oder über die Eigenschaft ondequeue. Da AudioEncoder von EventTarget erbt, funktionieren auch removeEventListener und die Option { once: true }.

Das Ereignis wird gebündelt ausgelöst: Mehrere Übernahmen innerhalb kurzer Zeit können zu einem einzigen dequeue-Ereignis zusammengefasst werden. Man sollte daher nie Ereignisse zählen, sondern immer encodeQueueSize auslesen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"dequeue"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Verringerung der Warteschlange aufgerufen wird. Erhält ein einfaches `Event`; `event.target` ist der `AudioEncoder`.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignisobjekt ist ein einfaches Event ohne eigene Eigenschaften.

Beispiele

Warteschlange per addEventListener beobachten

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

encoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 1,
  bitrate: 64000
});

encoder.addEventListener('dequeue', () => {
  console.log('Verbleibende Aufträge:', encoder.encodeQueueSize);
});

// 20 ms Stille als Test-Audio
const frames = 960;
const data = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: frames,
  numberOfChannels: 1,
  timestamp: 0,
  data: new Float32Array(frames)
});
encoder.encode(data);
data.close();

Verbleibende Aufträge: 0 Chunk: 3 Bytes

Gegendruck: nur kodieren, wenn Platz in der Warteschlange ist

const MAX_QUEUE = 8;

const waitForCapacity = (encoder) =>
  new Promise((resolve) => {
    if (encoder.encodeQueueSize < MAX_QUEUE) return resolve();
    const check = () => {
      if (encoder.encodeQueueSize < MAX_QUEUE) {
        encoder.removeEventListener('dequeue', check);
        resolve();
      }
    };
    encoder.addEventListener('dequeue', check);
  });

const encodeStream = async (encoder, audioDataIterable) => {
  for await (const audioData of audioDataIterable) {
    await waitForCapacity(encoder);
    encoder.encode(audioData);
    audioData.close();
  }
  await encoder.flush();
  console.log('Alle Daten kodiert');
};

Alle Daten kodiert

ondequeue-Eigenschaft setzen und wieder entfernen

const encoder = new AudioEncoder({
  output: () => {},
  error: console.error
});

encoder.ondequeue = () => {
  if (encoder.encodeQueueSize === 0) {
    console.log('Warteschlange leer – weitere Daten können folgen');
  }
};

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

// Wichtig · Fallstricke

Ereignisse werden zusammengefasst: Pro Übernahme gibt es nicht zwangsläufig ein eigenes Ereignis. Werte immer encodeQueueSize aus, statt Ereignisse zu zählen.
Das Ereignis sagt nur, dass die Eingabe-Warteschlange kleiner geworden ist. Ob kodierte Daten fertig sind, erfährst du über den output-Callback bzw. über flush().
Rufe nach encode() audioData.close() auf, sonst bleibt der Speicher belegt, egal wie gut der Gegendruck funktioniert.
Nach close() oder einem Fehler (Zustand "closed") kommen keine Ereignisse mehr. Promise-basierte Warte-Helfer sollten deshalb auch den Fehlerfall abfangen, sonst hängen sie für immer.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS) sowie in Fenstern und dedizierten Workern. AudioEncoder wird von Chromium-Browsern seit Version 94 unterstützt. In Firefox und Safari kam er später bzw. fehlt je nach Version noch. Vorher mit 'AudioEncoder' in globalThis prüfen. Ob ein Codec unterstützt wird, zeigt AudioEncoder.isConfigSupported().

Siehe auch

AudioEncoder AudioEncoder.encodeQueueSize AudioEncoder.prototype.encode() AudioEncoder.prototype.flush() AudioDecoder: dequeue VideoEncoder: dequeue AudioData EventTarget.addEventListener()