VideoDecoder.decodeQueueSize — Eigenschaft · JavaScript-Referenz

Signatur

get VideoDecoder.prototype.decodeQueueSize

Beschreibung

Die schreibgeschützte Eigenschaft decodeQueueSize liefert eine ganze Zahl: So viele Aufrufe von VideoDecoder.decode() stehen noch in der internen Warteschlange des Decoders. Jeder decode()-Aufruf erhöht den Wert um eins. Sobald der zugrunde liegende Codec einen Chunk angenommen hat, sinkt der Wert wieder.

Gebraucht wird die Eigenschaft vor allem für den Gegendruck (engl. backpressure). Wenn eine Anwendung Chunks schneller liefert (z. B. aus einem Demuxer oder über WebSocket), als der Decoder sie verarbeiten kann, wächst die Warteschlange ohne Grenze. Dann steigen Speicherverbrauch und Latenz. Mit decodeQueueSize kann man die Zufuhr drosseln, bis der Wert unter eine Schwelle fällt.

Jedes Mal, wenn der Wert sinkt, löst der Decoder das Ereignis dequeue aus. Deshalb muss man den Wert nicht ständig abfragen (Polling). Stattdessen wartet man ereignisgesteuert auf dequeue und prüft dann decodeQueueSize erneut.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative ganze Zahl: die Anzahl der ausstehenden Dekodierungsanfragen. Bei einem neuen oder zurückgesetzten Decoder ist der Wert 0.

Beispiele

Warteschlangengröße nach decode() prüfen

const decoder = new VideoDecoder({
  output: (frame) => {
    // Frame verarbeiten und danach sofort freigeben
    frame.close();
  },
  error: (e) => console.error('Decoder-Fehler:', e),
});

decoder.configure({ codec: 'vp8', codedWidth: 640, codedHeight: 480 });

// encodedChunks: Array von EncodedVideoChunk-Objekten (z. B. aus einem Demuxer)
for (const chunk of encodedChunks.slice(0, 3)) {
  decoder.decode(chunk);
}
console.log('Ausstehend:', decoder.decodeQueueSize);

Ausstehend: 3 (oder weniger, falls der Codec schon Chunks übernommen hat)

Gegendruck mit dem dequeue-Ereignis

const MAX_QUEUE = 10;

const waitForQueue = (decoder) =>
  new Promise((resolve) => {
    if (decoder.decodeQueueSize < MAX_QUEUE) return resolve();
    const onDequeue = () => {
      if (decoder.decodeQueueSize < MAX_QUEUE) {
        decoder.removeEventListener('dequeue', onDequeue);
        resolve();
      }
    };
    decoder.addEventListener('dequeue', onDequeue);
  });

const feed = async (decoder, chunks) => {
  for (const chunk of chunks) {
    await waitForQueue(decoder); // drosseln, bis wieder Platz ist
    decoder.decode(chunk);
  }
  await decoder.flush();
  console.log('Fertig, Warteschlange:', decoder.decodeQueueSize);
};

Fertig, Warteschlange: 0

Echtzeit-Stream: veraltete Frames verwerfen

// Bei Live-Video ist geringe Latenz wichtiger als Vollständigkeit
const onNetworkChunk = (decoder, chunk) => {
  if (decoder.decodeQueueSize > 30 && chunk.type !== 'key') {
    // Decoder ist überlastet: Delta-Frames bis zum nächsten Keyframe überspringen
    console.warn('Überlast, Frame verworfen. Queue =', decoder.decodeQueueSize);
    return;
  }
  decoder.decode(chunk);
};

Überlast, Frame verworfen. Queue = 31

// Wichtig · Fallstricke

Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus.
decodeQueueSize zählt nur die Anfragen, die der Codec noch nicht angenommen hat. Frames, die im Codec gerade verarbeitet werden oder schon ausgegeben, aber noch nicht mit close() freigegeben wurden, zählen nicht mit. Werden VideoFrame-Objekte nicht geschlossen, kann der Decoder trotz kleiner Warteschlange hängen bleiben.
Nach reset() oder close() fällt der Wert auf 0. Ausstehende Anfragen werden dabei verworfen.
Den Wert per setInterval abzufragen ist unnötig und verschwendet Rechenzeit. Besser ist das Ereignis dequeue (bzw. ondequeue).
Kompatibilität: Die WebCodecs API ist nur in sicheren Kontexten (HTTPS) verfügbar, auch in Dedicated Workers. Vor der Nutzung sollte man mit 'VideoDecoder' in globalThis prüfen, ob die API vorhanden ist.

Siehe auch

VideoDecoder.state AudioDecoder.decodeQueueSize VideoEncoder.encodeQueueSize AudioEncoder.encodeQueueSize ImageDecoder.complete