new OfflineAudioCompletionEvent() — Methode · JavaScript-Referenz

Signatur

new OfflineAudioCompletionEvent(type, options)

Beschreibung

Der Konstruktor OfflineAudioCompletionEvent() erzeugt ein Ereignisobjekt vom Typ OfflineAudioCompletionEvent. Solche Ereignisse löst ein OfflineAudioContext normalerweise selbst aus, und zwar als complete-Ereignis, sobald startRendering() fertig ist. Die Eigenschaft renderedBuffer enthält dann das Ergebnis als AudioBuffer.

Selbst ruft man den Konstruktor vor allem in Tests auf, zum Beispiel für Unit-Tests von Handlern, die auf complete reagieren. Auch in eigenen Audio-Pipelines ist er nützlich: Dort kann man das Ende eines Renderings über ein beliebiges EventTarget weitermelden und dabei dieselbe Ereignisform nutzen wie der Browser.

Für neuen Code ist der Promise-Weg meist besser: await ctx.startRendering() liefert den AudioBuffer direkt. Das complete-Ereignis und damit dieser Konstruktor sind trotzdem weiterhin Teil der Spezifikation.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Der Browser verwendet `"complete"`, du kannst aber jeden anderen Namen übergeben.
$options Pflicht	object		Wörterbuch mit Initialwerten. Pflichtfeld ist `renderedBuffer` (`AudioBuffer`), der fertig gerenderte Puffer. Außerdem sind die üblichen `EventInit`-Felder `bubbles`, `cancelable` und `composed` (jeweils `boolean`, Standard `false`) möglich.

Rückgabewert

Typ

OfflineAudioCompletionEvent

Beschreibung

Ein neues Ereignisobjekt. Seine schreibgeschützte Eigenschaft renderedBuffer verweist auf den übergebenen AudioBuffer.

Beispiele

Ereignis manuell erzeugen

// Puffer mit 1 Sekunde Stille in Stereo bei 44,1 kHz
const buffer = new AudioBuffer({ numberOfChannels: 2, length: 44100, sampleRate: 44100 });

const event = new OfflineAudioCompletionEvent('complete', { renderedBuffer: buffer });

console.log(event.type);
console.log(event.renderedBuffer.duration);

complete 1

Handler für complete testen, ohne echtes Rendering

const ctx = new OfflineAudioContext(1, 22050, 22050);

const onComplete = (e) => {
  console.log(`Fertig: ${e.renderedBuffer.length} Samples`);
};
ctx.addEventListener('complete', onComplete);

// Ereignis gezielt auslösen, um den Handler zu prüfen
const fake = new AudioBuffer({ numberOfChannels: 1, length: 22050, sampleRate: 22050 });
ctx.dispatchEvent(new OfflineAudioCompletionEvent('complete', { renderedBuffer: fake }));

Fertig: 22050 Samples

Echtes Rendering: Ereignis und Promise im Vergleich

const ctx = new OfflineAudioContext(1, 44100 * 2, 44100);
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(ctx.destination);
osc.start();

// Ereignis-Weg
ctx.oncomplete = (e) => console.log('Event:', e.renderedBuffer.duration, 's');

// Promise-Weg (empfohlen)
const rendered = await ctx.startRendering();
console.log('Promise:', rendered.duration, 's');

Promise: 2 s Event: 2 s

// Wichtig · Fallstricke

Pflichtoption: Fehlt renderedBuffer in options, wirft der Konstruktor einen TypeError. Das gilt auch, wenn der Wert kein AudioBuffer ist.
Manuell ausgelöst heißt nicht echt: Ein selbst erzeugtes Ereignis hat isTrusted === false und rendert kein Audio. Es löst nur die registrierten Handler aus.
Reihenfolge: Nutzt man beide Wege, wird das Promise von startRendering() je nach Browser vor oder nach dem complete-Ereignis aufgelöst. Verlass dich nicht auf eine bestimmte Reihenfolge.
Kompatibilität: Der Konstruktor funktioniert in allen aktuellen Browsern (Chrome, Firefox, Safari, Edge). Sehr alte Safari-Versionen mit webkitOfflineAudioContext kennen ihn nicht. In Node.js gibt es ihn nur über Polyfills wie node-web-audio-api.

Siehe auch

OfflineAudioCompletionEvent OfflineAudioContext OfflineAudioContext.prototype.startRendering() AudioBuffer new DynamicsCompressorNode() new GPUValidationError()