OfflineAudioCompletionEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface OfflineAudioCompletionEvent extends Event

Beschreibung

Die Schnittstelle OfflineAudioCompletionEvent der Web Audio API ist das Ereignis-Objekt, das beim complete-Event eines OfflineAudioContext übergeben wird. Das Event wird ausgelöst, sobald das Offline-Rendern eines Audio-Graphen abgeschlossen ist, also nachdem startRendering() alle Samples berechnet hat.

Die wichtigste Eigenschaft ist renderedBuffer: ein AudioBuffer mit dem vollständigen Ergebnis. Diesen Puffer kannst du anschließend abspielen, analysieren (z. B. Pegel oder Wellenform berechnen) oder als WAV-Datei exportieren. Typische Einsatzgebiete sind das schnelle Vorberechnen von Effekten, das Mischen mehrerer Spuren, Audio-Export oder die Analyse von Dateien, ohne sie in Echtzeit abzuspielen.

Seit startRendering() ein Promise<AudioBuffer> zurückgibt, ist der Promise-Weg meist die bequemere Variante. Das Event bleibt aber nützlich, wenn mehrere Stellen im Code auf den Abschluss reagieren sollen oder bestehender Callback-Code weitergepflegt wird. Mit new OfflineAudioCompletionEvent(type, init) lassen sich Instanzen auch selbst erzeugen, etwa für Tests.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Name des Events (Konstruktor-Parameter), in der Praxis immer `"complete"`.
$init Pflicht	{ renderedBuffer: AudioBuffer, bubbles?: boolean, cancelable?: boolean, composed?: boolean }	Initialisierungsobjekt; `renderedBuffer` ist Pflicht und enthält den gerenderten `AudioBuffer`.
$renderedBuffer	AudioBuffer	Schreibgeschützte Instanz-Eigenschaft: der fertig gerenderte Audio-Puffer.

Rückgabewert

Typ

OfflineAudioCompletionEvent

Beschreibung

Der Konstruktor liefert ein neues Event-Objekt; im Normalfall erzeugt der Browser es selbst und übergibt es an den complete-Handler.

Beispiele

Offline rendern und complete-Event per addEventListener auswerten

// 2 Sekunden Stereo bei 44,1 kHz offline berechnen
const offlineCtx = new OfflineAudioContext(2, 44100 * 2, 44100);

const osc = offlineCtx.createOscillator();
osc.frequency.value = 440;
osc.connect(offlineCtx.destination);
osc.start();

offlineCtx.addEventListener('complete', (event) => {
  const buffer = event.renderedBuffer;
  console.log(event instanceof OfflineAudioCompletionEvent);
  console.log(`Kanäle: ${buffer.numberOfChannels}, Dauer: ${buffer.duration}s`);
});

offlineCtx.startRendering();

true Kanäle: 2, Dauer: 2s

Gerenderten Puffer über oncomplete in Echtzeit abspielen

const audioCtx = new AudioContext();
const offlineCtx = new OfflineAudioContext(1, 48000, 48000);

const osc = offlineCtx.createOscillator();
const gain = offlineCtx.createGain();
gain.gain.setValueAtTime(1, 0);
gain.gain.linearRampToValueAtTime(0, 1); // Ausblenden über 1 s
osc.connect(gain).connect(offlineCtx.destination);
osc.start();

offlineCtx.oncomplete = ({ renderedBuffer }) => {
  const source = audioCtx.createBufferSource();
  source.buffer = renderedBuffer;
  source.connect(audioCtx.destination);
  source.start();
};

offlineCtx.startRendering();

Spitzenpegel analysieren (Promise und Event kombiniert)

const analyzePeak = async (audioBuffer) => {
  const offlineCtx = new OfflineAudioContext(
    audioBuffer.numberOfChannels,
    audioBuffer.length,
    audioBuffer.sampleRate
  );
  const src = offlineCtx.createBufferSource();
  src.buffer = audioBuffer;
  src.connect(offlineCtx.destination);
  src.start();

  offlineCtx.addEventListener('complete', () => console.log('Rendern fertig'), { once: true });

  const rendered = await offlineCtx.startRendering();
  const data = rendered.getChannelData(0);
  let peak = 0;
  for (const s of data) peak = Math.max(peak, Math.abs(s));
  return peak;
};

Rendern fertig

Event manuell erzeugen (z. B. für Tests)

const ctx = new OfflineAudioContext(1, 100, 8000);
const fakeBuffer = new AudioBuffer({ length: 100, sampleRate: 8000 });

const evt = new OfflineAudioCompletionEvent('complete', { renderedBuffer: fakeBuffer });
console.log(evt.type, evt.renderedBuffer.length);

complete 100

// Wichtig · Fallstricke

Promise bevorzugen: startRendering() liefert ein Promise<AudioBuffer>. Das complete-Event feuert zusätzlich; es ist kein Entweder-oder.
Nur einmal rendern: Ein OfflineAudioContext kann nur einmal gerendert werden. Ein zweiter Aufruf von startRendering() wirft einen InvalidStateError. Für neues Rendern brauchst du einen neuen Kontext.
Handler vor dem Start registrieren: Sonst kann das Event bei sehr kurzen Puffern verpasst werden.
Speicherbedarf: renderedBuffer liegt komplett im Arbeitsspeicher (32-Bit-Float pro Sample und Kanal). Lange Mehrkanal-Renderings können mehrere hundert MB belegen.
Kompatibilität: In allen modernen Browsern verfügbar. Ältere WebKit-Versionen kannten nur webkitOfflineAudioContext ohne Promise-Rückgabe. Der Konstruktor new OfflineAudioCompletionEvent() wird in sehr alten Browsern nicht unterstützt.

Siehe auch

OfflineAudioContext OfflineAudioContext.prototype.startRendering() AudioBuffer AudioContext Event