VideoEncoder.encodeQueueSize — Eigenschaft · JavaScript-Referenz

Signatur

get VideoEncoder.prototype.encodeQueueSize

Beschreibung

encodeQueueSize ist eine schreibgeschützte Ganzzahl-Eigenschaft von VideoEncoder. Sie zeigt, wie viele Aufrufe von encode() in der internen Warteschlange stehen und noch nicht an den zugrunde liegenden Codec übergeben wurden. Jeder Aufruf von encode() erhöht den Wert um eins. Sobald der Codec eine Anfrage übernimmt, sinkt der Wert wieder.

Wichtig ist die Eigenschaft vor allem für Gegendruck (Backpressure). Wenn Frames schneller erzeugt werden, als der Encoder sie verarbeiten kann – etwa bei Kamera-Streams oder beim Rendern aus einem <canvas> –, wächst die Warteschlange. Mit ihr wachsen der Speicherverbrauch und die Latenz. Deshalb prüft man encodeQueueSize vor jedem encode(). Ist der Wert zu hoch, verwirft man Frames oder wartet eine Weile.

Jedes Mal, wenn der Wert sinkt, löst der Encoder das Ereignis dequeue aus. Damit lässt sich ohne Polling warten, bis wieder Platz frei ist. Nach reset() oder close() steht der Wert wieder auf 0.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl: die Anzahl der Kodierungsanfragen, die noch in der Warteschlange stehen.

Beispiele

Warteschlange nach encode() auslesen

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

encoder.configure({ codec: 'vp8', width: 640, height: 480, bitrate: 1_000_000 });

const canvas = new OffscreenCanvas(640, 480);
canvas.getContext('2d').fillRect(0, 0, 640, 480);

const frame = new VideoFrame(canvas, { timestamp: 0 });
encoder.encode(frame);
frame.close();

console.log('Ausstehend:', encoder.encodeQueueSize);

Ausstehend: 1

Gegendruck: Frames verwerfen, wenn der Encoder nicht hinterherkommt

const MAX_QUEUE = 5;
let frameCount = 0;

const encodeFrame = (encoder, frame) => {
  if (encoder.encodeQueueSize > MAX_QUEUE) {
    // Encoder überlastet: diesen Frame auslassen
    frame.close();
    return false;
  }
  // Alle 60 Frames einen Keyframe erzwingen
  encoder.encode(frame, { keyFrame: frameCount++ % 60 === 0 });
  frame.close();
  return true;
};

Mit dem dequeue-Ereignis auf freien Platz warten

const waitForQueue = (encoder, limit = 2) =>
  new Promise((resolve) => {
    if (encoder.encodeQueueSize <= limit) return resolve();
    const onDequeue = () => {
      if (encoder.encodeQueueSize <= limit) {
        encoder.removeEventListener('dequeue', onDequeue);
        resolve();
      }
    };
    encoder.addEventListener('dequeue', onDequeue);
  });

const encodeAll = async (encoder, frames) => {
  for (const frame of frames) {
    await waitForQueue(encoder);
    encoder.encode(frame);
    frame.close();
  }
  await encoder.flush();
  console.log('Fertig, Warteschlange:', encoder.encodeQueueSize);
};

Fertig, Warteschlange: 0

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wird ignoriert, im Strict Mode wirft sie einen TypeError.
Der Wert zählt nur Anfragen, die noch nicht an den Codec übergeben wurden. Er sagt nicht, wie viele Chunks noch über den output-Callback zurückkommen. Um wirklich auf alle Ergebnisse zu warten, verwendet man await encoder.flush().
Den Wert nicht in einer engen Schleife abfragen (Busy-Waiting). Besser ist das Ereignis dequeue bzw. die Eigenschaft ondequeue.
Rufen Sie frame.close() nach encode() immer auf. Der Encoder arbeitet mit einer eigenen Kopie des Frames. Offene VideoFrame-Objekte belegen dagegen weiter GPU- bzw. Arbeitsspeicher.
Kompatibilität: WebCodecs gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in Workern. Firefox unterstützt die API erst ab Version 130. Das Ereignis dequeue ist neuer als encodeQueueSize. Prüfen Sie es vorher per Feature-Test, z. B. 'ondequeue' in VideoEncoder.prototype.

Siehe auch

ResizeObserverEntry.contentBoxSize VideoEncoder.state AudioEncoder.encodeQueueSize VideoDecoder.decodeQueueSize AudioDecoder.decodeQueueSize