EncodedAudioChunk.byteLength — Eigenschaft · JavaScript-Referenz

Signatur

get EncodedAudioChunk.prototype.byteLength

Beschreibung

Die Eigenschaft byteLength eines EncodedAudioChunk gibt an, wie viele Bytes die komprimierten Audiodaten (z. B. ein Opus- oder AAC-Frame) belegen. Sie ist schreibgeschützt und wird beim Erzeugen des Chunks aus der Größe des übergebenen data-Puffers festgelegt.

Der Wert wird vor allem gebraucht, um einen passend großen Zielpuffer anzulegen, bevor die Daten mit EncodedAudioChunk.prototype.copyTo() herauskopiert werden. Der Chunk selbst bietet nämlich keinen direkten Zugriff auf seinen internen Speicher – Lesen geht nur über copyTo().

Typische Einsatzfälle sind außerdem Bitraten-Statistiken, Muxing in Containerformate (WebM, MP4, Ogg), die Übertragung über WebSocket oder WebTransport sowie Längenpräfixe in selbst gebauten Binärprotokollen.

Beispiele

Größe eines selbst erzeugten Chunks abfragen

const data = new Uint8Array([0xfc, 0xff, 0xfe, 0x01, 0x02, 0x03]);

const chunk = new EncodedAudioChunk({
  type: 'key',
  timestamp: 0,      // Mikrosekunden
  duration: 20_000,  // 20 ms
  data
});

console.log(chunk.byteLength);

6

Zielpuffer anlegen und Daten mit copyTo() kopieren

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    // Puffer genau in der benötigten Größe anlegen
    const buffer = new Uint8Array(chunk.byteLength);
    chunk.copyTo(buffer);
    console.log(`${chunk.type}-Chunk @ ${chunk.timestamp} µs: ${buffer.length} Bytes`);
  },
  error: (e) => console.error('Encoder-Fehler:', e)
});

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

key-Chunk @ 0 µs: 160 Bytes (Wert abhängig von Codec und Eingangssignal)

Chunks mit Längenpräfix über WebSocket senden

const socket = new WebSocket('wss://example.com/audio');
socket.binaryType = 'arraybuffer';

const sendChunk = (chunk) => {
  // 4 Byte Länge + 8 Byte Zeitstempel + Nutzdaten
  const header = 12;
  const packet = new ArrayBuffer(header + chunk.byteLength);
  const view = new DataView(packet);
  view.setUint32(0, chunk.byteLength);
  view.setBigInt64(4, BigInt(chunk.timestamp));
  chunk.copyTo(new Uint8Array(packet, header));
  socket.send(packet);
};

Durchschnittliche Bitrate ermitteln

let totalBytes = 0;
let totalDuration = 0; // Mikrosekunden

const trackChunk = (chunk) => {
  totalBytes += chunk.byteLength;
  totalDuration += chunk.duration ?? 0;
};

const averageKbps = () =>
  totalDuration ? (totalBytes * 8) / (totalDuration / 1_000_000) / 1000 : 0;

// Beispiel: 50 Chunks à 160 Bytes und 20 ms
for (let i = 0; i < 50; i++) {
  trackChunk(new EncodedAudioChunk({
    type: 'key', timestamp: i * 20_000, duration: 20_000, data: new Uint8Array(160)
  }));
}
console.log(`${averageKbps().toFixed(1)} kbit/s`);

64.0 kbit/s

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie chunk.byteLength = 10 wird ignoriert (im Strict Mode TypeError). Die Größe steht fest, sobald der Chunk erzeugt ist.
Zu kleiner Zielpuffer: copyTo() wirft einen TypeError, wenn der Zielpuffer kleiner als byteLength ist. Deshalb Puffer immer anhand dieses Werts dimensionieren.
byteLength zählt nur die kodierten Nutzdaten – Codec-Konfiguration (z. B. metadata.decoderConfig.description) oder Container-Header gehören nicht dazu.
Seit neueren Spezifikationsständen lässt sich der Quellpuffer per transfer-Option übergeben; der ursprüngliche ArrayBuffer ist danach abgekoppelt (byteLength 0), der Chunk behält seine Größe.
Kompatibilität: WebCodecs steht nur in sicheren Kontexten (HTTPS) zur Verfügung, in Window und Dedicated Workern. Firefox unterstützt die API erst seit Version 130 (Desktop), Safari hat Audio-Codecs erst spät nachgezogen – vorher mit 'EncodedAudioChunk' in globalThis prüfen.

Siehe auch

EncodedAudioChunk.type EncodedAudioChunk.timestamp EncodedAudioChunk.duration EncodedVideoChunk.byteLength EncodedVideoChunk.type