new AudioProcessingEvent() — Methode · JavaScript-Referenz

Signatur

new AudioProcessingEvent(type, options)

Beschreibung

Der Konstruktor AudioProcessingEvent() erzeugt ein Ereignisobjekt vom Typ AudioProcessingEvent. Solche Ereignisse löst normalerweise der Browser selbst aus: Ein ScriptProcessorNode feuert für jeden Audioblock ein audioprocess-Ereignis. Darin stehen der Eingabepuffer (inputBuffer), der zu befüllende Ausgabepuffer (outputBuffer) und der Zeitpunkt, zu dem der Block abgespielt wird (playbackTime).

Selbst aufrufen muss man den Konstruktor selten. Nützlich ist er vor allem in Unit-Tests und Simulationen: Man kann damit einen onaudioprocess-Handler mit festgelegten Puffern prüfen, ohne dass ein echter Audiograph läuft. Das Ereignis lässt sich dann per dispatchEvent() an einen beliebigen EventTarget senden.

Alle drei audiospezifischen Felder im options-Objekt sind Pflicht. Fehlt eines davon, wirft der Konstruktor einen TypeError. Zusätzlich gelten die üblichen Ereignis-Optionen bubbles, cancelable und composed.

Wichtig: AudioProcessingEvent und ScriptProcessorNode sind veraltet. Für eigene Audioverarbeitung in neuem Code solltest du AudioWorkletNode mit einem AudioWorkletProcessor verwenden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Die Web Audio API verwendet `"audioprocess"`.
$options Pflicht	object		Einstellungsobjekt. Es erbt die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils Standard `false`) und enthält außerdem die folgenden Pflichtfelder: `playbackTime` (`number`): Zeitpunkt in Sekunden im Zeitsystem von `AudioContext.currentTime`, zu dem der Block abgespielt wird. `inputBuffer` (`AudioBuffer`): Puffer mit den Eingabedaten, die verarbeitet werden sollen. `outputBuffer` (`AudioBuffer`): Puffer, in den der Handler die Ausgabedaten schreibt.

Rückgabewert

Typ

AudioProcessingEvent

Beschreibung

Ein neues AudioProcessingEvent-Objekt mit den schreibgeschützten Eigenschaften playbackTime, inputBuffer und outputBuffer.

Beispiele

Ereignis manuell erzeugen und Eigenschaften lesen

const ctx = new AudioContext();

// Zwei Mono-Puffer mit 1024 Samples anlegen
const inputBuffer = ctx.createBuffer(1, 1024, ctx.sampleRate);
const outputBuffer = ctx.createBuffer(1, 1024, ctx.sampleRate);

const event = new AudioProcessingEvent('audioprocess', {
  playbackTime: 0.5,
  inputBuffer,
  outputBuffer
});

console.log(event.type);
console.log(event.playbackTime);
console.log(event.inputBuffer.length);

audioprocess 0.5 1024

Verstärker-Handler im Unit-Test prüfen

const ctx = new AudioContext();

// Zu testende Verarbeitungslogik: halbiert die Lautstärke
const halveGain = (e) => {
  const input = e.inputBuffer.getChannelData(0);
  const output = e.outputBuffer.getChannelData(0);
  for (let i = 0; i < input.length; i++) {
    output[i] = input[i] * 0.5;
  }
};

const inputBuffer = ctx.createBuffer(1, 4, ctx.sampleRate);
inputBuffer.copyToChannel(new Float32Array([1, -1, 0.5, 0]), 0);
const outputBuffer = ctx.createBuffer(1, 4, ctx.sampleRate);

// Beliebiges EventTarget als Test-Ziel
const target = new EventTarget();
target.addEventListener('audioprocess', halveGain);
target.dispatchEvent(new AudioProcessingEvent('audioprocess', {
  playbackTime: ctx.currentTime,
  inputBuffer,
  outputBuffer
}));

console.log(Array.from(outputBuffer.getChannelData(0)));

[0.5, -0.5, 0.25, 0]

Typischer Fall: der Browser liefert das Ereignis (ScriptProcessorNode)

const ctx = new AudioContext();
const osc = ctx.createOscillator();
const processor = ctx.createScriptProcessor(4096, 1, 1);

processor.onaudioprocess = (e) => {
  // e ist ein vom Browser erzeugtes AudioProcessingEvent
  const input = e.inputBuffer.getChannelData(0);
  const output = e.outputBuffer.getChannelData(0);
  output.set(input.map((s) => s * 0.2)); // leiser durchreichen
};

osc.connect(processor).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 1);

Moderne Alternative mit AudioWorklet

// gain-processor.js
// class GainProcessor extends AudioWorkletProcessor {
//   process([input], [output]) {
//     input.forEach((ch, i) => output[i].set(ch.map((s) => s * 0.2)));
//     return true;
//   }
// }
// registerProcessor('gain-processor', GainProcessor);

const ctx = new AudioContext();
await ctx.audioWorklet.addModule('gain-processor.js');
const node = new AudioWorkletNode(ctx, 'gain-processor');
const osc = new OscillatorNode(ctx);
osc.connect(node).connect(ctx.destination);
osc.start();

// Wichtig · Fallstricke

Veraltet: AudioProcessingEvent und ScriptProcessorNode sind als deprecated markiert. Sie laufen im Haupt-Thread, was zu Aussetzern und hoher Latenz führt. Verwende für neuen Code AudioWorkletNode.
Pflichtfelder: Fehlt playbackTime, inputBuffer oder outputBuffer in options, wirft der Konstruktor einen TypeError.
Ein selbst erzeugtes Ereignis hat isTrusted === false. Es löst keine echte Audioverarbeitung aus, sondern ruft nur die registrierten Handler auf.
Browser-Kompatibilität: Der Konstruktor ist in Chrome, Edge, Firefox und Safari vorhanden. Ältere Safari-Versionen mit webkitAudioContext kennen ihn teilweise nicht. Außerhalb des Browsers (z. B. in Node.js oder jsdom) gibt es ihn nur mit Polyfills wie standardized-audio-context.
Die Puffer werden per Referenz übergeben und nicht kopiert. Änderungen am outputBuffer im Handler sind danach also direkt im ursprünglichen Objekt sichtbar.

Siehe auch

new NDEFReadingEvent() new MIDIMessageEvent() new MediaKeyMessageEvent() new PeriodicSyncEvent() new ProgressEvent()