new EncodedAudioChunk() — Methode · JavaScript-Referenz

Signatur

new EncodedAudioChunk(options)

Beschreibung

Der Konstruktor EncodedAudioChunk() gehört zur WebCodecs API. Er verpackt rohe, bereits komprimierte Audiodaten, etwa einen einzelnen Opus-Frame aus einem WebM-Container, einen AAC-Frame aus MP4 oder ein über WebSocket bzw. WebTransport empfangenes Paket, zusammen mit Metadaten wie Zeitstempel, Dauer und Chunk-Typ in ein Objekt, das ein AudioDecoder verarbeiten kann.

Solche Objekte erzeugt man vor allem dann selbst, wenn man Audio dekodieren will: Ein Demuxer (z. B. mp4box.js oder ein eigener Parser) zerlegt eine Datei in einzelne Frames, und aus jedem Frame wird ein EncodedAudioChunk, der an AudioDecoder.decode() übergeben wird. Beim Kodieren dagegen erzeugt der AudioEncoder die Chunks selbst und reicht sie an seinen output-Callback weiter.

Die übergebenen Daten werden beim Erzeugen kopiert, außer man überträgt den Puffer mit der Option transfer. Danach ist das Objekt unveränderlich. Seine Bytes liest man mit copyTo() aus, die Größe steht in byteLength.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.type Pflicht	"key" \| "delta"		`"key"` für einen Chunk, der unabhängig dekodiert werden kann. `"delta"` für einen Chunk, der von vorherigen Chunks abhängt. Bei den meisten Audio-Codecs (Opus, AAC) ist jeder Frame ein `"key"`.
$options.timestamp Pflicht	number		Präsentationszeitpunkt in Mikrosekunden, als ganze Zahl (auch negativ möglich).
$options.duration	number	null	Dauer des Chunks in Mikrosekunden, als nicht-negative ganze Zahl.
$options.data Pflicht	ArrayBuffer \| TypedArray \| DataView		Die kodierten Audiodaten. Sie werden kopiert, sofern der Puffer nicht über `transfer` übertragen wird.
$options.transfer	ArrayBuffer[]	[]	Liste von `ArrayBuffer`n, die übertragen statt kopiert werden. Danach sind sie im aufrufenden Code abgetrennt (`byteLength === 0`).

Rückgabewert

Typ

EncodedAudioChunk

Beschreibung

Ein neues, unveränderliches EncodedAudioChunk-Objekt mit den Eigenschaften type, timestamp, duration und byteLength.

Beispiele

Einfachen Chunk erzeugen und Eigenschaften lesen

// Beispielbytes – in der Praxis ein echter Opus-Frame aus einem Demuxer
const bytes = new Uint8Array([0xfc, 0xff, 0xfe, 0x01, 0x02, 0x03]);

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

console.log(chunk.type, chunk.timestamp, chunk.duration, chunk.byteLength);

key 0 20000 6

Demuxte Frames mit AudioDecoder dekodieren

// frames: Array aus { data: Uint8Array, timestampUs: number, durationUs: number }
const decodeOpus = async (frames) => {
  const decoder = new AudioDecoder({
    output: (audioData) => {
      console.log(`Dekodiert: ${audioData.numberOfFrames} Samples @ ${audioData.timestamp} µs`);
      audioData.close(); // Speicher sofort freigeben
    },
    error: (e) => console.error('Decoder-Fehler:', e)
  });

  const config = { codec: 'opus', sampleRate: 48000, numberOfChannels: 2 };
  const { supported } = await AudioDecoder.isConfigSupported(config);
  if (!supported) throw new Error('Opus wird nicht unterstützt');
  decoder.configure(config);

  for (const f of frames) {
    decoder.decode(new EncodedAudioChunk({
      type: 'key',
      timestamp: f.timestampUs,
      duration: f.durationUs,
      data: f.data
    }));
  }
  await decoder.flush();
  decoder.close();
};

Dekodiert: 960 Samples @ 0 µs Dekodiert: 960 Samples @ 20000 µs …

Netzwerkpaket ohne Kopie übernehmen (transfer)

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

socket.addEventListener('message', (event) => {
  const buffer = event.data; // ArrayBuffer
  const chunk = new EncodedAudioChunk({
    type: 'key',
    timestamp: ts,
    duration: 20_000,
    data: buffer,
    transfer: [buffer] // keine Kopie, buffer ist danach abgetrennt
  });
  ts += 20_000;
  console.log(buffer.byteLength, chunk.byteLength);
  // decoder.decode(chunk);
});

0 123

// Wichtig · Fallstricke

Einheiten: timestamp und duration werden in Mikrosekunden angegeben, nicht in Millisekunden oder Samples. Ein häufiger Fehler: Aus 960 Samples bei 48 kHz werden 20000 µs.
Fehlt type, timestamp oder data, oder hat type einen ungültigen Wert, wirft der Konstruktor einen TypeError. Dasselbe gilt, wenn ein Puffer in transfer bereits abgetrennt ist oder doppelt vorkommt.
Ohne transfer werden die Daten kopiert. Bei großen Datenmengen oder vielen Chunks lohnt sich transfer, aber dann ist der ursprüngliche Puffer nicht mehr nutzbar.
Manche Codecs brauchen zusätzlich eine description in der Decoder-Konfiguration (bei AAC etwa die AudioSpecificConfig aus dem esds-Block). Die Chunks allein reichen dann nicht.
Kompatibilität: Nur in sicheren Kontexten (HTTPS) und in Window- sowie Worker-Kontexten verfügbar. Chromium unterstützt die API seit Version 94, Firefox seit 130. Safari unterstützte zunächst nur Video-Codecs, Audio-Unterstützung kam erst später. Vor der Nutzung prüfen, ob 'EncodedAudioChunk' in globalThis gilt.

Siehe auch

new EncodedVideoChunk() new RTCEncodedAudioFrame() new RTCEncodedVideoFrame() new Animation() new Audio()