AudioEncoder.close() — Methode · JavaScript-Referenz

Signatur

AudioEncoder.prototype.close()

Beschreibung

Mit close() beenden Sie einen AudioEncoder endgültig. Alle noch in der Warteschlange stehenden encode()-Aufträge werden verworfen, laufende Arbeit wird abgebrochen und die belegten Ressourcen (z. B. Codec-Instanzen der Plattform, Hardware-Encoder, Speicher) werden freigegeben. Danach steht state auf "closed".

Im Unterschied zu reset() ist close() nicht umkehrbar: Ein geschlossener Encoder lässt sich weder mit configure() neu einrichten noch weiter verwenden. Jeder weitere Aufruf von configure(), encode(), flush() oder reset() wirft eine InvalidStateError-DOMException. Brauchen Sie später wieder einen Encoder, müssen Sie einen neuen erzeugen.

Wichtig: close() wartet nicht auf ausstehende Ausgaben. Wer sicherstellen will, dass alle bereits übergebenen AudioData-Blöcke als EncodedAudioChunk im output-Callback ankommen, ruft vorher await encoder.flush() auf und erst danach close(). Ein noch offenes flush()-Promise wird durch close() mit einer AbortError-DOMException abgelehnt.

Typische Einsatzorte sind das Ende einer Aufnahme, das Verlassen einer Seite oder Komponente (Aufräumen in Frameworks) und die Fehlerbehandlung, um Hardware-Ressourcen nicht unnötig zu blockieren.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode arbeitet synchron; nach dem Aufruf ist encoder.state sofort "closed".

Beispiele

Aufnahme sauber abschließen: erst flush(), dann close()

const chunks = [];

const encoder = new AudioEncoder({
  output: (chunk) => chunks.push(chunk),
  error: (e) => console.error('Encoder-Fehler:', e)
});

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

// 1 Sekunde Stille als Test-Audio (48000 Frames, Mono, f32-planar)
const audioData = new AudioData({
  format: 'f32-planar',
  sampleRate: 48000,
  numberOfFrames: 48000,
  numberOfChannels: 1,
  timestamp: 0,
  data: new Float32Array(48000)
});

encoder.encode(audioData);
audioData.close(); // AudioData ebenfalls freigeben

await encoder.flush(); // alle Ausgaben abwarten
encoder.close();       // Ressourcen freigeben

console.log(encoder.state, chunks.length > 0);

closed true

Geschlossenen Encoder nicht mehr verwenden

const encoder = new AudioEncoder({
  output: () => {},
  error: (e) => console.error(e)
});

encoder.close();

try {
  encoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 2 });
} catch (e) {
  console.log(e.name);
}

InvalidStateError

Laufendes flush() wird durch close() abgebrochen

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

const pending = encoder.flush();
encoder.close(); // abbrechen, ohne auf Ausgaben zu warten

try {
  await pending;
} catch (e) {
  console.log('flush abgelehnt:', e.name);
}

flush abgelehnt: AbortError

Aufräumen beim Verlassen der Seite

let encoder = null;

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

const stopEncoder = () => {
  // Nur schließen, wenn nicht bereits geschlossen
  if (encoder && encoder.state !== 'closed') {
    encoder.close();
  }
  encoder = null;
};

startEncoder();
window.addEventListener('pagehide', stopEncoder);

// Wichtig · Fallstricke

Datenverlust: close() verwirft alle noch nicht ausgegebenen Aufträge. Wer vollständige Ausgaben braucht, muss vorher await encoder.flush() aufrufen.
Nicht umkehrbar: Anders als reset() lässt sich ein geschlossener Encoder nicht erneut konfigurieren. Alle Methoden außer close() werfen danach InvalidStateError.
Doppelter Aufruf: Ein erneuter Aufruf von close() auf einem bereits geschlossenen Encoder wirft laut Spezifikation ebenfalls InvalidStateError. Prüfen Sie deshalb vorher encoder.state !== "closed".
Automatisches Schließen: Tritt ein Kodierungsfehler auf, schließt der Browser den Encoder selbst und ruft den error-Callback auf. Einen manuellen close()-Aufruf brauchen Sie dann nicht mehr.
AudioData separat freigeben: close() gibt nur den Encoder frei. Übergebene AudioData-Objekte müssen Sie selbst mit audioData.close() freigeben.
Kompatibilität: Die WebCodecs-API gibt es nur in sicheren Kontexten (HTTPS) und in Window- sowie Dedicated-Worker-Kontexten. AudioEncoder wird von Chromium-Browsern seit Version 94 unterstützt, in Firefox und Safari erst deutlich später. Prüfen Sie die Verfügbarkeit mit 'AudioEncoder' in globalThis.

Siehe auch

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