AudioEncoder.reset() — Methode · JavaScript-Referenz

Signatur

AudioEncoder.prototype.reset()

Beschreibung

Die Methode reset() der Schnittstelle AudioEncoder setzt den gesamten internen Zustand des Encoders zurück. Dazu gehören die aktuelle Konfiguration, alle Steuerungsnachrichten in der Warteschlange (etwa noch nicht verarbeitete encode()-Aufrufe) und alle ausstehenden Rückrufe. Danach ist state gleich "unconfigured" und encodeQueueSize gleich 0.

Anders als close() ist reset() nicht endgültig: Dieselbe Instanz lässt sich danach mit configure() neu einrichten und weiterverwenden. Das braucht man vor allem, wenn:

man mitten in einer Aufnahme auf einen anderen Codec, eine andere Bitrate oder Abtastrate wechseln will,
der Nutzer eine Aufnahme abbricht und die schon eingereihten Frames nicht mehr kodiert werden sollen,
bei einem Seek oder Neustart ein Stream ohne Altlasten neu beginnen soll.

Alle noch offenen Promises von flush() werden mit einer DOMException vom Typ AbortError abgelehnt. Kodierte Chunks, die bereits an den output-Callback gegangen sind, bleiben gültig. Für noch nicht verarbeitete Frames wird dagegen keine Ausgabe mehr erzeugt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode arbeitet synchron: Direkt nach dem Aufruf ist state gleich "unconfigured".

Beispiele

Encoder zurücksetzen und Zustand prüfen

const encoder = new AudioEncoder({
  output: (chunk) => console.log('Chunk:', chunk.byteLength, 'Bytes'),
  error: (e) => console.error('Encoder-Fehler:', e)
});

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

encoder.reset();
console.log(encoder.state);
console.log(encoder.encodeQueueSize);

configured unconfigured 0

Bitrate während der Aufnahme wechseln

const encoder = new AudioEncoder({
  output: (chunk, meta) => {
    // meta.decoderConfig ist nach einer Neukonfiguration wieder gesetzt
    if (meta?.decoderConfig) console.log('Neue Decoder-Konfiguration erhalten');
  },
  error: console.error
});

const baseConfig = { codec: 'opus', sampleRate: 48000, numberOfChannels: 2 };
encoder.configure({ ...baseConfig, bitrate: 128000 });

// Netzwerk wird langsamer: Qualität reduzieren
const switchBitrate = async (bitrate) => {
  await encoder.flush();   // bisherige Frames sauber fertig kodieren
  encoder.reset();          // Konfiguration verwerfen
  encoder.configure({ ...baseConfig, bitrate });
  console.log('Bitrate jetzt', bitrate);
};

await switchBitrate(48000);

Bitrate jetzt 48000

Aufnahme abbrechen – ausstehendes flush() wird abgelehnt

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

// Einige Frames Stille einreihen
for (let i = 0; i < 50; i++) {
  const data = new AudioData({
    format: 'f32-planar',
    sampleRate: 48000,
    numberOfFrames: 960,
    numberOfChannels: 1,
    timestamp: i * 20000, // Mikrosekunden
    data: new Float32Array(960)
  });
  encoder.encode(data);
  data.close();
}

const pending = encoder.flush();
encoder.reset(); // Nutzer klickt auf „Abbrechen“

try {
  await pending;
} catch (err) {
  console.log(err.name);
}

AbortError

// Wichtig · Fallstricke

InvalidStateError: Wurde der Encoder schon mit close() geschlossen (state === "closed"), wirft reset() eine DOMException vom Typ InvalidStateError. Nach einem Encoder-Fehler ist der Encoder ebenfalls geschlossen. Dann hilft nur eine neue Instanz.
Neu konfigurieren: Nach reset() wirft jeder Aufruf von encode() einen InvalidStateError, bis configure() erneut aufgerufen wurde.
Datenverlust: reset() verwirft Frames, die noch in der Warteschlange stehen. Sollen alle Daten erhalten bleiben, zuerst await encoder.flush() und erst danach reset() aufrufen.
Offene Promises: Ausstehende flush()-Promises werden mit AbortError abgelehnt. Fängt man das nicht ab, entsteht eine unbehandelte Promise-Ablehnung (unhandled rejection).
Kompatibilität: Die WebCodecs-API gibt es nur in sicheren Kontexten (HTTPS), dafür auch in Web Workern. Chromium-Browser unterstützen AudioEncoder seit Version 94, Firefox seit Version 130 (Desktop). In Safari ist die Unterstützung eingeschränkt. Vor der Nutzung mit 'AudioEncoder' in globalThis prüfen.

Siehe auch

AudioEncoder AudioEncoder.configure() AudioEncoder.encode() AudioEncoder.flush() AudioEncoder.close() AudioEncoder.state AudioDecoder.reset() VideoEncoder.reset()