AudioDecoder.configure() — Methode · JavaScript-Referenz

Signatur

AudioDecoder.prototype.configure(config)

Beschreibung

configure() legt fest, wie ein AudioDecoder die nachfolgenden EncodedAudioChunk-Objekte dekodieren soll: welcher Codec verwendet wird (z. B. "opus", "mp4a.40.2" für AAC-LC, "flac"), mit welcher Abtastrate und Kanalzahl, und ggf. welche codec-spezifischen Zusatzdaten (description) benötigt werden – etwa die AudioSpecificConfig bei AAC aus einem MP4-Container.

Die Methode arbeitet asynchron über eine Steuerungswarteschlange: Der Aufruf kehrt sofort zurück, der Zustand (state) wechselt direkt auf "configured", die eigentliche Einrichtung erfolgt aber im Hintergrund. Schlägt sie fehl (z. B. weil der Codec nicht unterstützt wird), wird der beim Konstruktor übergebene error-Callback mit einer NotSupportedError-DOMException aufgerufen und der Decoder geschlossen.

Vor dem Konfigurieren sollte man mit der statischen Methode AudioDecoder.isConfigSupported() prüfen, ob die Konfiguration unterstützt wird. configure() kann auch erneut aufgerufen werden, um z. B. bei einem Streamwechsel auf einen anderen Codec umzustellen; noch ausstehende Arbeit wird dabei in der Warteschlange abgearbeitet. Nach einer Neukonfiguration muss der nächste Chunk ein Schlüssel-Chunk (type: "key") sein.

Parameter

Name	Typ	Beschreibung
$config Pflicht	AudioDecoderConfig	Konfigurationsobjekt mit den unten genannten Feldern.
$config.codec Pflicht	string	Codec-String gemäß WebCodecs-Codec-Registry, z. B. `"opus"`, `"mp4a.40.2"`, `"flac"`, `"mp3"`, `"vorbis"`, `"pcm-s16"`.
$config.sampleRate Pflicht	number	Abtastrate in Hz (Frames pro Sekunde), z. B. `48000`.
$config.numberOfChannels Pflicht	number	Anzahl der Audiokanäle, z. B. `2` für Stereo.
$config.description	ArrayBuffer \| TypedArray \| DataView	Codec-spezifische Initialisierungsdaten, z. B. AAC-AudioSpecificConfig, Opus-Header (`OpusHead`) oder FLAC-STREAMINFO. Fehlt sie, erwartet z. B. AAC den ADTS-Bitstrom.

Beispiele

Opus-Decoder konfigurieren und Chunks dekodieren

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

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

console.log(decoder.state);

// Anschließend z. B. aus einem Demuxer:
// decoder.decode(new EncodedAudioChunk({ type: 'key', timestamp: 0, data }));

configured

Unterstützung vorab mit isConfigSupported() prüfen

const config = {
  codec: 'mp4a.40.2', // AAC-LC
  sampleRate: 44100,
  numberOfChannels: 2,
};

const createDecoder = async () => {
  if (!('AudioDecoder' in window)) {
    throw new Error('WebCodecs wird nicht unterstützt');
  }
  const { supported } = await AudioDecoder.isConfigSupported(config);
  if (!supported) {
    throw new Error(`Codec ${config.codec} nicht verfügbar`);
  }
  const decoder = new AudioDecoder({
    output: (data) => data.close(),
    error: (e) => console.error(e),
  });
  decoder.configure(config);
  return decoder;
};

createDecoder()
  .then((d) => console.log('Bereit:', d.state))
  .catch((e) => console.warn(e.message));

Bereit: configured

AAC aus MP4 mit description (AudioSpecificConfig)

// 2 Bytes AudioSpecificConfig: AAC-LC, 44,1 kHz, Stereo (aus dem esds-Box des MP4)
const asc = new Uint8Array([0x12, 0x10]);

const decoder = new AudioDecoder({
  output: (data) => {
    const pcm = new Float32Array(data.numberOfFrames);
    data.copyTo(pcm, { planeIndex: 0, format: 'f32-planar' });
    data.close();
  },
  error: (e) => console.error(e.name, e.message),
});

decoder.configure({
  codec: 'mp4a.40.2',
  sampleRate: 44100,
  numberOfChannels: 2,
  description: asc,
});

console.log(decoder.decodeQueueSize);

// Wichtig · Fallstricke

Synchrone Ausnahmen: Ist config ungültig (z. B. leerer codec, fehlende sampleRate/numberOfChannels, abgelöster description-Puffer), wird sofort ein TypeError geworfen. Ist der Decoder bereits "closed", folgt ein InvalidStateError.
Asynchrone Fehler: Ein nicht unterstützter Codec wirft nicht, sondern ruft den error-Callback mit NotSupportedError auf und schließt den Decoder – danach ist eine neue Instanz nötig. Daher vorher AudioDecoder.isConfigSupported() nutzen.
Nach configure() (und nach flush()) muss der erste dekodierte Chunk vom Typ "key" sein, sonst gibt es einen DataError.
Die description muss zum Container passen: AAC aus MP4 braucht die AudioSpecificConfig, ADTS-Streams dagegen keine.
AudioData-Objekte im output-Callback immer mit close() freigeben, sonst drohen Speicherlecks.
Kompatibilität: WebCodecs ist nur in sicheren Kontexten (HTTPS) sowie in Window und Dedicated Workern verfügbar. Unterstützte Codecs variieren je nach Browser und Plattform; Feature-Erkennung per 'AudioDecoder' in self ist empfehlenswert.

Siehe auch

AudioDecoder AudioDecoder.decode() AudioDecoder.flush() AudioDecoder.reset() AudioDecoder.isConfigSupported() EncodedAudioChunk AudioData VideoDecoder.configure()