Signatur
Beschreibung
Die Eigenschaft byteLength ist schreibgeschützt und gibt an, wie viele Bytes die codierten Videodaten eines EncodedVideoChunk umfassen. Ein solcher Chunk entsteht beim Codieren mit VideoEncoder (im output-Callback) oder wird von Hand aus Container-Daten erzeugt, um ihn an einen VideoDecoder zu übergeben.
Gebraucht wird der Wert vor allem, um einen Zielpuffer passender Größe anzulegen, bevor man die Daten mit chunk.copyTo(destination) herauskopiert. Denn ein EncodedVideoChunk gibt seine Daten nicht direkt als ArrayBuffer heraus, sondern nur über copyTo().
Außerdem eignet sich byteLength für Statistiken zur Bitrate, zur Kontrolle von Puffergrößen beim Streaming (z. B. über WebTransport oder WebSocket) und zur Diagnose, etwa um die Größe von Schlüsselbildern (type === "key") mit Delta-Frames zu vergleichen.
Rückgabewert
unsigned long): die Länge der codierten Daten in Bytes.Beispiele
Chunk erzeugen und Größe abfragen
const data = new Uint8Array([0x00, 0x00, 0x00, 0x01, 0x67, 0x42, 0x00, 0x1f]);
const chunk = new EncodedVideoChunk({
type: 'key',
timestamp: 0, // Mikrosekunden
duration: 33333,
data
});
console.log(chunk.byteLength);Encoder-Ausgabe in einen passenden Puffer kopieren
const chunks = [];
const encoder = new VideoEncoder({
output: (chunk, metadata) => {
// Puffer mit exakt passender Größe anlegen
const buffer = new ArrayBuffer(chunk.byteLength);
chunk.copyTo(buffer);
chunks.push({ type: chunk.type, timestamp: chunk.timestamp, buffer });
console.log(`${chunk.type}-Frame: ${chunk.byteLength} Bytes`);
},
error: (e) => console.error('Encoder-Fehler:', e)
});
encoder.configure({
codec: 'vp8',
width: 640,
height: 480,
bitrate: 1_000_000,
framerate: 30
});
// Ein Testbild aus einem Canvas codieren
const canvas = new OffscreenCanvas(640, 480);
canvas.getContext('2d').fillRect(0, 0, 640, 480);
const frame = new VideoFrame(canvas, { timestamp: 0 });
encoder.encode(frame, { keyFrame: true });
frame.close();
await encoder.flush();Bitrate laufend messen
let bytesInWindow = 0;
let windowStart = performance.now();
const trackBitrate = (chunk) => {
bytesInWindow += chunk.byteLength;
const elapsed = performance.now() - windowStart;
if (elapsed >= 1000) {
const kbps = (bytesInWindow * 8) / elapsed; // Bit pro ms = kbit/s
console.log(`Aktuelle Bitrate: ${kbps.toFixed(0)} kbit/s`);
bytesInWindow = 0;
windowStart = performance.now();
}
};
// Verwendung im VideoEncoder-Callback:
// output: (chunk) => { trackBitrate(chunk); send(chunk); }// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung an
byteLengthhat keine Wirkung (im Strict Mode wird einTypeErrorgeworfen). Die Größe steht fest, sobald der Chunk erzeugt ist, dennEncodedVideoChunkist unveränderlich. - Zielpuffer für
copyTo(): Ist der Puffer kleiner alsbyteLength, wirftcopyTo()einenTypeError. Deshalb den Puffer immer mitnew ArrayBuffer(chunk.byteLength)odernew Uint8Array(chunk.byteLength)anlegen. - Der Konstruktor kopiert die übergebenen
data. Spätere Änderungen am Quellpuffer wirken sich also weder auf den Chunk noch aufbyteLengthaus. Neuere Browser unterstützen zusätzlich die Optiontransfer, mit der der Puffer übertragen statt kopiert wird. - Kompatibilität: WebCodecs steht nur in sicheren Kontexten (HTTPS) zur Verfügung, sowohl im Hauptthread als auch in Workern. Chromium-Browser unterstützen die API seit Version 94, Safari seit 16.4 (für Video) und Firefox seit 130. Die Verfügbarkeit lässt sich mit
'EncodedVideoChunk' in globalThisprüfen. - Der Wert umfasst nur die reinen codierten Nutzdaten. Container-Overhead (MP4, WebM) ist nicht enthalten, ebenso wenig die Codec-Konfiguration (
decoderConfig.descriptionin den Encoder-Metadaten).