new AudioDecoder() — Methode · JavaScript-Referenz

Signatur

new AudioDecoder(init)

Beschreibung

Der Konstruktor AudioDecoder() gehört zur WebCodecs API und legt einen Decoder an, der kodierte Audiodaten (z. B. AAC, Opus, MP3, FLAC) in rohe PCM-Samples umwandelt. Dabei werden zwei Rückruffunktionen übergeben: output erhält jedes dekodierte AudioData-Objekt, error wird bei einem fatalen Fehler aufgerufen.

Nach der Erzeugung befindet sich der Decoder im Zustand "unconfigured". Bevor Daten mit decode() eingespeist werden können, muss er mit configure() auf Codec, Abtastrate und Kanalanzahl eingestellt werden. Ob eine Konfiguration unterstützt wird, lässt sich vorab mit der statischen Methode AudioDecoder.isConfigSupported() prüfen.

Typische Einsatzgebiete sind eigene Mediaplayer, Audio-Bearbeitung im Browser, Echtzeit-Streaming (z. B. über WebTransport oder WebSockets) sowie die Analyse von Audiodateien, bei denen man mehr Kontrolle braucht als mit <audio> oder AudioContext.decodeAudioData(). Die Verarbeitung läuft asynchron und kann auch in einem Web Worker stattfinden.

Parameter

Name	Typ	Beschreibung
$init Pflicht	Object	Initialisierungsobjekt mit den beiden Pflicht-Rückrufen `output` und `error`.
$init.output Pflicht	(data: AudioData) => void	Wird für jedes dekodierte Audio-Frame mit einem `AudioData`-Objekt aufgerufen. Das Objekt sollte nach der Verwendung mit `close()` freigegeben werden.
$init.error Pflicht	(error: DOMException) => void	Wird bei einem fatalen Fehler aufgerufen. Danach ist der Decoder im Zustand `"closed"` und nicht mehr verwendbar.

Rückgabewert

Typ

AudioDecoder

Beschreibung

Ein neues AudioDecoder-Objekt im Zustand "unconfigured".

Beispiele

Decoder erzeugen und konfigurieren

const decoder = new AudioDecoder({
  output: (audioData) => {
    console.log(`Frame: ${audioData.numberOfFrames} Samples, ${audioData.sampleRate} Hz`);
    audioData.close(); // Speicher freigeben
  },
  error: (err) => console.error('Dekodierfehler:', err.message),
});

console.log(decoder.state);

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

console.log(decoder.state);

unconfigured configured

Unterstützung vorab prüfen

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

const initDecoder = async () => {
  if (!('AudioDecoder' in window)) {
    throw new Error('WebCodecs wird nicht unterstützt');
  }
  const { supported } = await AudioDecoder.isConfigSupported(config);
  if (!supported) throw new Error('AAC wird nicht unterstützt');

  const decoder = new AudioDecoder({
    output: (data) => data.close(),
    error: (e) => console.error(e),
  });
  decoder.configure(config);
  return decoder;
};

initDecoder().then((d) => console.log('Bereit:', d.state));

Bereit: configured

Chunks dekodieren und in Float32Array kopieren

const samples = [];

const decoder = new AudioDecoder({
  output: (audioData) => {
    const buffer = new Float32Array(audioData.numberOfFrames);
    // Kanal 0 als planares Float32 kopieren
    audioData.copyTo(buffer, { planeIndex: 0, format: 'f32-planar' });
    samples.push(buffer);
    audioData.close();
  },
  error: (e) => console.error(e),
});

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

// packets: Array aus { data: Uint8Array, timestamp: number } (z. B. aus einem Demuxer)
const decodeAll = async (packets) => {
  for (const p of packets) {
    decoder.decode(new EncodedAudioChunk({
      type: 'key',
      timestamp: p.timestamp, // in Mikrosekunden
      data: p.data,
    }));
  }
  await decoder.flush(); // wartet, bis alle Ausgaben geliefert wurden
  console.log(`Dekodierte Blöcke: ${samples.length}`);
  decoder.close();
};

// Wichtig · Fallstricke

Sicherer Kontext: AudioDecoder ist nur über HTTPS (bzw. localhost) verfügbar, in Fenstern und dedizierten Workern.
Browser-Kompatibilität: Chromium-Browser unterstützen die API seit Version 94, Firefox seit 130 (Desktop). Safari hat AudioDecoder erst deutlich später als VideoDecoder bekommen – immer per 'AudioDecoder' in self prüfen.
Beide Rückrufe sind Pflicht; fehlt einer, wirft der Konstruktor einen TypeError.
Speicherlecks: Jedes AudioData im output-Rückruf mit close() freigeben, sonst bleibt der Puffer belegt.
Der Konstruktor enthält keine Codec-Angaben – ein decode() vor configure() wirft einen InvalidStateError.
Nach einem Aufruf von error ist der Decoder dauerhaft geschlossen; für einen Neustart muss eine neue Instanz erzeugt werden.
WebCodecs übernimmt kein Demuxing: Container wie MP4 oder WebM müssen vorher selbst (oder mit Bibliotheken wie mp4box.js) in einzelne Chunks zerlegt werden. Für AAC wird meist die description (AudioSpecificConfig) in configure() benötigt.

Siehe auch

AudioDecoder AudioDecoder.prototype.configure() AudioDecoder.prototype.decode() EncodedAudioChunk AudioData AudioEncoder VideoDecoder