AudioEncoder.encodeQueueSize — Eigenschaft · JavaScript-Referenz

Signatur

AudioEncoder.encodeQueueSize

Beschreibung

Die Eigenschaft encodeQueueSize einer AudioEncoder-Instanz liefert die Anzahl der Aufrufe von encode(), die zwar angenommen, aber vom zugrunde liegenden Codec noch nicht abgearbeitet wurden. Jeder Aufruf von encode() erhöht den Wert. Sobald der Codec eine Anfrage übernimmt, sinkt er wieder.

Die Eigenschaft dient vor allem der Gegendruck-Steuerung (engl. backpressure). Liefert eine Quelle, etwa ein Mikrofon über MediaStreamTrackProcessor, schneller AudioData-Objekte, als der Encoder sie verarbeiten kann, wächst die Warteschlange und mit ihr der Speicherverbrauch. Wenn Sie encodeQueueSize prüfen, können Sie Frames verwerfen oder das Einlesen pausieren, bis der Encoder aufgeholt hat.

Jede Verringerung des Werts löst das Ereignis dequeue aus. Deshalb brauchen Sie die Eigenschaft nicht per Polling abzufragen. Lauschen Sie stattdessen auf dequeue (bzw. setzen Sie ondequeue) und lesen Sie encodeQueueSize dort aus.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl: die Anzahl der ausstehenden Kodieranfragen. Nach reset() oder close() ist der Wert 0.

Beispiele

Warteschlangenlänge nach encode() prüfen

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

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

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

console.log('Vorher:', encoder.encodeQueueSize);
encoder.encode(data);
data.close();
console.log('Nachher:', encoder.encodeQueueSize);

Vorher: 0 Nachher: 1

Gegendruck: Frames bei voller Warteschlange verwerfen

const MAX_QUEUE = 10;

const encoder = new AudioEncoder({
  output: (chunk) => sendToServer(chunk),
  error: (e) => console.error('Encoder-Fehler:', e)
});
encoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 1 });

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const reader = new MediaStreamTrackProcessor({ track }).readable.getReader();

while (true) {
  const { value: audioData, done } = await reader.read();
  if (done) break;

  if (encoder.encodeQueueSize > MAX_QUEUE) {
    console.warn('Encoder überlastet, Frame verworfen');
  } else {
    encoder.encode(audioData);
  }
  audioData.close(); // Speicher immer freigeben
}

function sendToServer(chunk) {
  const buf = new Uint8Array(chunk.byteLength);
  chunk.copyTo(buf);
  // z. B. per WebSocket versenden
}

Auf das dequeue-Ereignis reagieren statt zu pollen

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

encoder.addEventListener('dequeue', () => {
  console.log('Ausstehend:', encoder.encodeQueueSize);
  if (encoder.encodeQueueSize === 0) {
    console.log('Warteschlange leer – weitere Daten einspeisen');
  }
});

// Alternativ über die on-Property:
// encoder.ondequeue = () => console.log(encoder.encodeQueueSize);

Ausstehend: 0 Warteschlange leer – weitere Daten einspeisen

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wird still ignoriert (im Strict Mode gibt es einen TypeError).
Nicht mit fertiger Ausgabe verwechseln: Wenn der Wert sinkt, hat der Codec die Anfrage nur übernommen. Die zugehörigen EncodedAudioChunk-Objekte können später im output-Callback ankommen. Um sicher alle Ergebnisse zu erhalten, warten Sie mit await encoder.flush().
Nach reset() oder close() fällt der Wert auf 0 und ausstehende Anfragen werden verworfen.
Rufen Sie nach encode() immer audioData.close() auf. Sonst bleiben Audiopuffer im Speicher, und zwar unabhängig vom Stand der Warteschlange.
Kompatibilität: Die WebCodecs API ist nur in sicheren Kontexten (HTTPS) verfügbar. Sie läuft in Fenstern und in dedizierten Workern. Chromium-Browser unterstützen sie ab Version 94, Firefox ab 130, Safari erst ab Version 26. Prüfen Sie die Verfügbarkeit mit 'AudioEncoder' in globalThis.

Siehe auch

MediaTrackConstraints.sampleSize AudioEncoder.state VideoEncoder.encodeQueueSize AudioDecoder.decodeQueueSize VideoDecoder.decodeQueueSize