AudioDecoder.close() — Methode · JavaScript-Referenz

Signatur

AudioDecoder.prototype.close()

Beschreibung

close() versetzt einen AudioDecoder endgültig in den Zustand "closed". Alle noch in der Warteschlange befindlichen Aufträge aus decode() werden abgebrochen, es werden keine weiteren AudioData-Objekte mehr an den output-Callback übergeben, und ein noch offenes Promise von flush() wird mit einer AbortError-DOMException abgelehnt.

Die Methode ist vor allem dafür da, knappe Ressourcen deterministisch freizugeben. Decoder können Hardware-Beschleunigung, native Puffer oder Threads belegen – darauf zu warten, dass der Garbage Collector das Objekt einsammelt, ist unzuverlässig. Rufe close() also auf, sobald ein Stream fertig abgespielt, ein Tab-Wechsel die Wiedergabe beendet oder ein Fehler aufgetreten ist.

Anders als reset() ist close() nicht umkehrbar: Nach dem Schließen führen configure(), decode(), flush() und reset() zu einer InvalidStateError-Ausnahme. Wer denselben Decoder mit anderer Konfiguration weiterverwenden möchte, nutzt stattdessen reset() und anschließend configure().

Wichtig: close() ist synchron und wartet nicht auf bereits laufende Dekodierungen. Sollen alle Daten noch ausgegeben werden, muss vorher await decoder.flush() aufgerufen werden.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Der Zustand ist danach über decoder.state === "closed" prüfbar.

Beispiele

Sauberes Beenden nach vollständiger Dekodierung

const decoder = new AudioDecoder({
  output: (audioData) => {
    console.log(`Frames: ${audioData.numberOfFrames}`);
    audioData.close(); // auch AudioData freigeben!
  },
  error: (e) => console.error('Dekodierfehler:', e)
});

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

const decodeAll = async (chunks) => {
  for (const chunk of chunks) decoder.decode(chunk);
  await decoder.flush(); // erst alle Ausgaben abwarten
  decoder.close();       // dann Ressourcen freigeben
  console.log(decoder.state);
};

// decodeAll(encodedChunks); // encodedChunks: Array<EncodedAudioChunk>

closed

Wiedergabe abbrechen – flush() wird abgelehnt

const decoder = new AudioDecoder({
  output: (data) => data.close(),
  error: (e) => console.error(e)
});
decoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 2 });

const pending = decoder.flush().catch((err) => {
  console.log(err.name);
});

// Nutzer klickt auf „Stopp“: sofort alles verwerfen
decoder.close();
await pending;

AbortError

Zugriff nach close() absichern

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

const safeClose = (dec) => {
  if (dec.state !== 'closed') dec.close();
};
safeClose(decoder); // kein Fehler

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

InvalidStateError

Aufräumen beim Verlassen der Seite

let decoder = new AudioDecoder({
  output: (data) => data.close(),
  error: () => decoder.state !== 'closed' && decoder.close()
});

window.addEventListener('pagehide', () => {
  if (decoder.state !== 'closed') decoder.close();
});

// Wichtig · Fallstricke

Nicht umkehrbar: Nach close() werfen configure(), decode(), flush() und reset() eine InvalidStateError. Zum Neukonfigurieren reset() verwenden oder einen neuen Decoder erzeugen.
Doppelter Aufruf: close() auf einem bereits geschlossenen Decoder wirft laut Spezifikation eine InvalidStateError. Vorher decoder.state prüfen.
Datenverlust: Noch nicht ausgegebene Frames gehen verloren. Wenn alles ausgegeben werden soll, zuerst await flush().
AudioData separat freigeben: close() am Decoder gibt bereits ausgelieferte AudioData-Objekte nicht frei – diese müssen einzeln mit AudioData.close() geschlossen werden, sonst drohen Speicherlecks.
Nach einem Fehler (error-Callback) schließt der Browser den Decoder automatisch; ein erneutes close() ist dann überflüssig.
Kompatibilität: WebCodecs gibt es nur in sicheren Kontexten (HTTPS) und in Window- sowie Dedicated-Worker-Kontexten. Unterstützung mit 'AudioDecoder' in globalThis prüfen; Safari unterstützt AudioDecoder erst seit neueren Versionen.

Siehe auch

AudioDecoder.flush() AudioDecoder.decode() AudioDecoder.reset() AudioDecoder.configure() AudioDecoder.isConfigSupported()