EncodedAudioChunk — Schnittstelle · JavaScript-Referenz

Signatur

interface EncodedAudioChunk

Beschreibung

EncodedAudioChunk ist der Datencontainer der WebCodecs-API für komprimiertes Audio. Ein AudioEncoder liefert solche Chunks in seinem output-Callback, und ein AudioDecoder erwartet sie als Eingabe für decode(). Jeder Chunk enthält typischerweise genau einen kodierten Frame, etwa ein Opus-Paket oder einen AAC-Frame.

Der Konstruktor new EncodedAudioChunk(init) nimmt ein Objekt mit type ("key" oder "delta"), timestamp (Mikrosekunden), optional duration (Mikrosekunden) und data (ein ArrayBuffer, TypedArray oder DataView) entgegen. Die Daten werden beim Erzeugen kopiert, sofern sie nicht über transfer übertragen werden. Das Objekt ist danach unveränderlich.

Schreibgeschützte Eigenschaften sind type, timestamp, duration (oder null) und byteLength. Mit der Methode copyTo(destination) kopiert man die kodierten Bytes in einen eigenen Puffer, etwa um sie in einen Container (WebM, MP4) zu schreiben oder über WebSocket bzw. WebTransport zu verschicken.

Man verwendet EncodedAudioChunk, wenn man die Kodierung bzw. Dekodierung selbst steuern will: bei Echtzeit-Streaming mit niedriger Latenz, in browserbasierten Audio-Editoren oder beim Demuxen von Mediendateien in JavaScript bzw. WebAssembly.

Rückgabewert

Typ

EncodedAudioChunk

Beschreibung

Eine neue, unveränderliche EncodedAudioChunk-Instanz mit den Eigenschaften type, timestamp, duration und byteLength sowie der Methode copyTo().

Beispiele

Chunk aus empfangenen Opus-Bytes erzeugen und dekodieren

const decoder = new AudioDecoder({
  output: (audioData) => {
    console.log(`Dekodiert: ${audioData.numberOfFrames} Frames @ ${audioData.sampleRate} Hz`);
    audioData.close(); // Speicher freigeben
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

decoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 2 });

// packetBytes: Uint8Array mit einem Opus-Paket, z. B. per WebSocket empfangen
const handlePacket = (packetBytes, timestampUs) => {
  const chunk = new EncodedAudioChunk({
    type: 'key',
    timestamp: timestampUs,
    duration: 20_000, // 20 ms
    data: packetBytes
  });
  decoder.decode(chunk);
};

Dekodiert: 960 Frames @ 48000 Hz

Chunks aus dem AudioEncoder auslesen und mit copyTo() versenden

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

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    const buffer = new Uint8Array(chunk.byteLength);
    chunk.copyTo(buffer);
    console.log(chunk.type, chunk.timestamp, chunk.duration, chunk.byteLength);
    if (socket.readyState === WebSocket.OPEN) socket.send(buffer);
  },
  error: (e) => console.error(e)
});

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

key 0 20000 97 key 20000 20000 103

Eigenschaften prüfen und Zero-Copy-Transfer

const bytes = new Uint8Array([0xfc, 0xff, 0xfe]).buffer;

const chunk = new EncodedAudioChunk({
  type: 'key',
  timestamp: 1_000_000, // 1 Sekunde
  data: bytes,
  transfer: [bytes] // ohne Kopie übergeben
});

console.log(chunk.type, chunk.timestamp, chunk.duration, chunk.byteLength);
console.log('Originalpuffer:', bytes.byteLength); // detached

key 1000000 null 3 Originalpuffer: 0

// Wichtig · Fallstricke

Einheiten: timestamp und duration werden in Mikrosekunden angegeben, nicht in Millisekunden oder Samples. Ein Opus-Frame mit 20 ms hat also duration: 20000.
Unveränderlich: Die Daten lassen sich nicht direkt lesen, es gibt keine data-Eigenschaft. Man kommt nur über copyTo() an die Bytes. Ist der Zielpuffer kleiner als byteLength, wirft die Methode einen TypeError.
Kopie vs. Transfer: Ohne transfer werden die Daten kopiert. Mit transfer sind die übergebenen ArrayBuffer danach detached. Die Unterstützung von transfer ist neuer und fehlt in älteren Browsern.
Codec-Konfiguration: Bei AAC muss der Decoder meist mit description (AudioSpecificConfig) konfiguriert werden. Diese erhält man beim Kodieren über metadata.decoderConfig im output-Callback.
Kompatibilität: WebCodecs ist nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster und in Workern. Chromium unterstützt die API ab Version 94, Firefox ab 130, Safari hat Audio-WebCodecs erst spät erhalten. Vorher per Feature-Test prüfen: 'EncodedAudioChunk' in globalThis und AudioDecoder.isConfigSupported().
EncodedAudioChunk ist serialisierbar und lässt sich per postMessage() an Worker senden.

Siehe auch

EncodedVideoChunk RTCEncodedAudioFrame AudioTrack RTCEncodedVideoFrame Scheduling