AudioData.close() — Methode · JavaScript-Referenz

Signatur

AudioData.prototype.close()

Beschreibung

Die Methode close() der Schnittstelle AudioData aus der WebCodecs-API gibt den Verweis auf den zugrunde liegenden Audio-Puffer frei. Danach ist das Objekt geschlossen (detached): format wird null, sampleRate, numberOfFrames, numberOfChannels und duration werden 0, und Aufrufe wie copyTo() oder clone() lösen einen InvalidStateError aus.

Audio-Rohdaten können viel Speicher belegen, der teilweise außerhalb des JavaScript-Heaps liegt. Der Garbage Collector weiß davon nichts und gibt ihn möglicherweise erst spät frei. Deshalb sollte man jedes AudioData-Objekt explizit schließen, sobald man es nicht mehr braucht – typischerweise im output-Rückruf eines AudioDecoder, nachdem die Samples kopiert oder weitergegeben wurden.

Wurde ein Objekt mit clone() vervielfältigt, teilen sich die Kopien dieselbe Ressource über eine Referenzzählung. close() gibt nur die Referenz des jeweiligen Objekts frei; der Speicher wird erst freigegeben, wenn alle Klone geschlossen sind.

Beispiele

AudioData erzeugen, auslesen und schließen

const frames = 480;
const samples = new Float32Array(frames); // 10 ms Stille bei 48 kHz, mono

const audioData = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: frames,
  numberOfChannels: 1,
  timestamp: 0,
  data: samples
});

console.log(audioData.numberOfFrames, audioData.format);

// Ressource freigeben
audioData.close();

console.log(audioData.numberOfFrames, audioData.format);

480 f32 0 null

Im output-Rückruf eines AudioDecoders schließen

const decoder = new AudioDecoder({
  output: (audioData) => {
    try {
      // Kanal 0 als planare Float32-Daten kopieren
      const size = audioData.allocationSize({ planeIndex: 0, format: 'f32-planar' });
      const buffer = new Float32Array(size / 4);
      audioData.copyTo(buffer, { planeIndex: 0, format: 'f32-planar' });
      console.log('Frames dekodiert:', buffer.length);
    } finally {
      // Immer freigeben – auch wenn beim Kopieren ein Fehler auftritt
      audioData.close();
    }
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

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

Zugriff nach close() schlägt fehl

const audioData = new AudioData({
  format: 's16',
  sampleRate: 44100,
  numberOfFrames: 100,
  numberOfChannels: 2,
  timestamp: 0,
  data: new Int16Array(200)
});

const copy = audioData.clone(); // eigene Referenz auf dieselbe Ressource
audioData.close();

try {
  audioData.copyTo(new Int16Array(200), { planeIndex: 0 });
} catch (err) {
  console.log(err.name);
}

console.log(copy.numberOfFrames); // Klon ist weiterhin gültig
copy.close();

InvalidStateError 100

// Wichtig · Fallstricke

Speicherlecks: Wer close() vergisst, riskiert schnell steigenden Speicherverbrauch, weil Audio-Puffer außerhalb des JS-Heaps liegen können. Einige Browser warnen in der Konsole, wenn ein AudioData-Objekt vom Garbage Collector ohne vorheriges Schließen eingesammelt wird.
Übergabe an Encoder: AudioEncoder.encode() schließt das übergebene Objekt nicht. Nach dem Aufruf kann (und sollte) man close() selbst aufrufen.
Transfer an Worker: Wird ein AudioData per postMessage(data, [data]) übertragen, ist das Original danach geschlossen; das Objekt im Worker muss dort geschlossen werden.
Ein wiederholter Aufruf von close() ist unschädlich und wirft keinen Fehler.
Kompatibilität: Die WebCodecs-API ist nur in sicheren Kontexten (HTTPS) verfügbar und wird nicht von allen Browsern unterstützt. Vorab per 'AudioData' in globalThis prüfen.

Siehe auch

AudioData AudioData.clone() AudioData.copyTo() AudioDecoder AudioEncoder VideoFrame.close() MediaStreamTrack.clone()