EncodedAudioChunk.copyTo() — Methode · JavaScript-Referenz

Signatur

EncodedAudioChunk.prototype.copyTo(destination)

Beschreibung

Ein EncodedAudioChunk ist ein unveränderliches Objekt der WebCodecs API. Es enthält einen Block komprimierter Audiodaten, etwa einen Opus- oder AAC-Frame. Direkt auf die Bytes zugreifen kannst du nicht. Mit copyTo() holst du sie aus dem Chunk heraus und schreibst sie in einen Puffer, den du selbst bereitstellst.

Das brauchst du immer dann, wenn die kodierten Daten außerhalb des Encoders weiterverarbeitet werden sollen. Typische Fälle sind das Verpacken in einen Container (WebM, MP4, Ogg), das Senden über WebSocket oder WebTransport und das Speichern in IndexedDB oder im Origin Private File System. Die benötigte Puffergröße liest du vorher über die Eigenschaft byteLength des Chunks aus.

Die Methode arbeitet synchron und gibt nichts zurück. Die Daten stehen nach dem Aufruf sofort im Zielpuffer. Ist der Puffer zu klein, wird ein TypeError geworfen. Ist er größer als nötig, werden nur die ersten byteLength Bytes beschrieben.

Parameter

Name	Typ	Default	Beschreibung
$destination Pflicht	ArrayBuffer \| TypedArray \| DataView		Zielpuffer für die kodierten Bytes. Er muss mindestens `chunk.byteLength` Bytes groß sein. Auch ein `SharedArrayBuffer` oder eine View darauf ist erlaubt.

Beispiele

Einen Chunk manuell anlegen und zurückkopieren

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

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

const ziel = new Uint8Array(chunk.byteLength);
chunk.copyTo(ziel);

console.log(chunk.byteLength, ziel);

5 Uint8Array(5) [252, 255, 254, 1, 2]

Opus-Ausgabe eines AudioEncoder sammeln

const pakete = [];

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    const buffer = new ArrayBuffer(chunk.byteLength);
    chunk.copyTo(buffer);
    pakete.push({ timestamp: chunk.timestamp, type: chunk.type, data: buffer });
  },
  error: (e) => console.error('Encoder-Fehler:', e)
});

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

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

encoder.encode(audio);
audio.close();
await encoder.flush();
console.log(`${pakete.length} Paket(e) kodiert`);

1 Paket(e) kodiert

Chunk mit Header über WebSocket senden

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

const sendeChunk = (chunk) => {
  const HEADER = 9; // 1 Byte Typ + 8 Byte Zeitstempel
  const buffer = new ArrayBuffer(HEADER + chunk.byteLength);
  const view = new DataView(buffer);
  view.setUint8(0, chunk.type === 'key' ? 1 : 0);
  view.setBigInt64(1, BigInt(chunk.timestamp));
  // Nutzdaten direkt hinter den Header kopieren
  chunk.copyTo(new Uint8Array(buffer, HEADER));
  socket.send(buffer);
};

// Wichtig · Fallstricke

Puffergröße: Ist destination.byteLength kleiner als chunk.byteLength, wird ein TypeError geworfen. Lege den Puffer deshalb immer anhand von byteLength an.
Offset: copyTo() hat keinen Offset-Parameter. Willst du an einer bestimmten Stelle schreiben, übergib eine View mit Offset, z. B. new Uint8Array(buffer, offset).
Jeder Aufruf erzeugt eine echte Kopie. Bei hohem Datendurchsatz lohnt es sich, Puffer wiederzuverwenden (Pooling), statt ständig neue anzulegen.
Im Gegensatz zu AudioData und VideoFrame besitzt EncodedAudioChunk keine close()-Methode. Die Speicherfreigabe übernimmt die Garbage Collection.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS), dort aber auch in Workern. Chromium-Browser unterstützen sie seit Version 94, Firefox seit Version 130. Safari unterstützt die Audio-Teile erst ab Version 26. Prüfe die Verfügbarkeit mit 'EncodedAudioChunk' in globalThis.

Siehe auch

TrustedScriptURL.toJSON() EncodedVideoChunk.copyTo() new EncodedAudioChunk() AudioData.copyTo() VideoFrame.copyTo()