new AudioEncoder() — Methode · JavaScript-Referenz

Signatur

new AudioEncoder(init)

Beschreibung

Der Konstruktor AudioEncoder() gehört zur WebCodecs API und legt einen neuen Audio-Encoder an. Dabei werden zwei Rückruffunktionen registriert: init.output wird für jedes erzeugte EncodedAudioChunk aufgerufen, init.error bei einem schweren Fehler, nach dem der Encoder geschlossen wird.

Nach der Erzeugung befindet sich der Encoder im Zustand "unconfigured" (siehe state). Bevor Daten kodiert werden können, muss er mit configure() konfiguriert werden – etwa mit Codec, Abtastrate, Kanalanzahl und Bitrate. Anschließend übergibt man AudioData-Objekte an encode() und leert die Warteschlange zum Schluss mit flush().

Typische Einsatzfälle sind Echtzeit-Übertragung (eigene WebRTC-/WebTransport-Pipelines), browserseitige Aufnahme und Kodierung von Mikrofon-Audio oder das Erzeugen von Mediendateien zusammen mit einem Muxer-Bibliothek. Im Gegensatz zu MediaRecorder erhält man direkten Zugriff auf die einzelnen kodierten Pakete samt Zeitstempeln und Decoder-Metadaten.

Parameter

Name	Typ	Beschreibung
$init Pflicht	Object	Initialisierungsobjekt mit den beiden Pflicht-Callbacks `output` und `error`.
$init.output Pflicht	(chunk: EncodedAudioChunk, metadata?: EncodedAudioChunkMetadata) => void	Wird für jedes kodierte Paket aufgerufen. `metadata.decoderConfig` enthält (beim ersten Chunk bzw. bei Änderungen) die passende `AudioDecoderConfig` inkl. `description`.
$init.error Pflicht	(error: DOMException) => void	Wird bei einem schwerwiegenden Kodierfehler aufgerufen. Danach ist der Encoder im Zustand `"closed"`.

Rückgabewert

Typ

AudioEncoder

Beschreibung

Ein neues AudioEncoder-Objekt im Zustand "unconfigured".

Beispiele

Encoder erzeugen und für Opus konfigurieren

const chunks = [];

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    chunks.push(chunk);
    if (metadata?.decoderConfig) {
      console.log('Decoder-Konfiguration:', metadata.decoderConfig.codec);
    }
  },
  error: (e) => console.error('Kodierfehler:', e.message)
});

console.log(encoder.state);

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

console.log(encoder.state);

unconfigured configured

Unterstützung vor dem Erzeugen prüfen

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

if (!('AudioEncoder' in window)) {
  console.warn('WebCodecs wird nicht unterstützt');
} else {
  const { supported } = await AudioEncoder.isConfigSupported(config);
  if (supported) {
    const encoder = new AudioEncoder({
      output: (chunk) => console.log('Chunk:', chunk.byteLength, 'Bytes'),
      error: (e) => console.error(e)
    });
    encoder.configure(config);
  } else {
    console.warn('AAC wird hier nicht unterstützt');
  }
}

Synthetischen Sinuston kodieren

const encoder = new AudioEncoder({
  output: (chunk) => console.log(chunk.type, chunk.timestamp, chunk.byteLength),
  error: (e) => console.error(e)
});
encoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 1 });

const sampleRate = 48000;
const frameSize = 960; // 20 ms
for (let f = 0; f < 50; f++) {
  const samples = new Float32Array(frameSize);
  for (let i = 0; i < frameSize; i++) {
    const t = (f * frameSize + i) / sampleRate;
    samples[i] = Math.sin(2 * Math.PI * 440 * t) * 0.3;
  }
  const data = new AudioData({
    format: 'f32',
    sampleRate,
    numberOfFrames: frameSize,
    numberOfChannels: 1,
    timestamp: (f * frameSize * 1_000_000) / sampleRate, // Mikrosekunden
    data: samples
  });
  encoder.encode(data);
  data.close(); // Speicher sofort freigeben
}

await encoder.flush();
encoder.close();

key 0 … key 20000 … …

// Wichtig · Fallstricke

Beide Callbacks sind Pflicht: Fehlt output oder error, wirft der Konstruktor einen TypeError.
Nur in sicheren Kontexten (HTTPS/localhost) und in Window sowie dedizierten Workern verfügbar. Für rechenintensive Pipelines empfiehlt sich ein Worker.
Browser-Unterstützung: Chromium-Browser seit Version 94, Firefox seit 130 (Desktop), Safari erst sehr spät. Immer per Feature-Erkennung ('AudioEncoder' in self) und AudioEncoder.isConfigSupported() prüfen – unterstützte Codecs unterscheiden sich je Plattform (AAC fehlt z. B. in manchen Firefox-Builds).
Aufrufe von encode() vor configure() werfen einen InvalidStateError.
AudioData-Objekte nach encode() mit close() freigeben, sonst drohen Speicherlecks. Über encodeQueueSize und das dequeue-Event lässt sich Gegendruck (Backpressure) steuern.
Zeitstempel werden in Mikrosekunden angegeben, nicht in Millisekunden.

Siehe auch

new AudioDecoder() new VideoEncoder() new AudioBuffer() new TextEncoder() new VideoDecoder()