ConvolverNode.buffer — Eigenschaft · JavaScript-Referenz

Signatur

ConvolverNode.buffer

Beschreibung

Die Eigenschaft buffer eines ConvolverNode enthält die Impulsantwort (Impulse Response, IR), die für die Faltung verwendet wird. Mit einer aufgenommenen Raum-IR kannst du jedes Signal so klingen lassen, als würde es in diesem Raum abgespielt – typisch für Hall, Kathedralen- oder Telefoneffekte und Lautsprechersimulationen.

Der zugewiesene AudioBuffer muss 1, 2 oder 4 Kanäle haben und dieselbe Abtastrate wie der AudioContext. Andernfalls wird ein NotSupportedError ausgelöst. Solange kein Buffer gesetzt ist (null), gibt der Knoten Stille aus.

Beim Zuweisen wird der Buffer abhängig von der Eigenschaft normalize skaliert. Diese wird zum Zeitpunkt der Zuweisung ausgewertet. Wenn du normalize also ändern willst, musst du das vor dem Setzen von buffer tun. Übliche Wege sind, die IR per fetch() zu laden und mit decodeAudioData() zu dekodieren, oder sie mit createBuffer() selbst zu erzeugen.

Parameter

Name	Typ	Default	Beschreibung
$value	AudioBuffer \| null	null	Beim Setzen: ein `AudioBuffer` mit 1, 2 oder 4 Kanälen und der Abtastrate des Kontexts. `null` schaltet den Knoten stumm.

Rückgabewert

Typ

AudioBuffer | null

Beschreibung

Der aktuell gesetzte Impulsantwort-Buffer oder null, wenn noch keiner zugewiesen wurde.

Beispiele

Impulsantwort laden und als Hall verwenden

const ctx = new AudioContext();

const loadReverb = async (url) => {
  const res = await fetch(url);
  const data = await res.arrayBuffer();
  const convolver = ctx.createConvolver();
  // Dekodierter Buffer hat automatisch die Abtastrate des Kontexts
  convolver.buffer = await ctx.decodeAudioData(data);
  return convolver;
};

const reverb = await loadReverb('/audio/impulse-hall.wav');
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(reverb).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 0.5);
console.log(reverb.buffer.numberOfChannels, reverb.buffer.duration.toFixed(2));

2 3.20

Synthetische Impulsantwort (abklingendes Rauschen) erzeugen

const ctx = new AudioContext();

const createImpulse = (seconds = 2, decay = 3) => {
  const length = ctx.sampleRate * seconds;
  const ir = ctx.createBuffer(2, length, ctx.sampleRate);
  for (let ch = 0; ch < ir.numberOfChannels; ch++) {
    const data = ir.getChannelData(ch);
    for (let i = 0; i < length; i++) {
      data[i] = (Math.random() * 2 - 1) * (1 - i / length) ** decay;
    }
  }
  return ir;
};

const convolver = new ConvolverNode(ctx);
convolver.normalize = true; // VOR der Zuweisung setzen!
convolver.buffer = createImpulse(2.5, 4);
console.log(convolver.buffer.length === ctx.sampleRate * 2.5);

true

Hall zur Laufzeit wechseln oder abschalten

const ctx = new AudioContext();
const convolver = ctx.createConvolver();
console.log(convolver.buffer); // noch keine IR

const small = ctx.createBuffer(1, ctx.sampleRate * 0.3, ctx.sampleRate);
small.getChannelData(0)[0] = 1; // Dirac-Impuls = trockenes Signal
convolver.buffer = small;
console.log(convolver.buffer.numberOfChannels);

// Ungültige Kanalzahl
try {
  convolver.buffer = ctx.createBuffer(3, 1000, ctx.sampleRate);
} catch (err) {
  console.log(err.name);
}

null 1 NotSupportedError

// Wichtig · Fallstricke

Abtastrate: Weicht buffer.sampleRate von ctx.sampleRate ab, wird ein NotSupportedError ausgelöst. decodeAudioData() rechnet die Datei automatisch passend um, bei createBuffer() musst du selbst darauf achten.
Kanalzahl: Erlaubt sind nur 1, 2 oder 4 Kanäle. 4 Kanäle stehen für „True Stereo“ (L→L, L→R, R→L, R→R).
Reihenfolge: normalize wirkt nur bei der Zuweisung von buffer. Wenn du es später änderst, hat das keinen Effekt, bis du den Buffer erneut setzt.
Leistung: Lange Impulsantworten (mehrere Sekunden, 4 Kanäle) kosten viel Rechenzeit. Auf Mobilgeräten sind kurze IRs sinnvoll. Ein Wechsel des Buffers während der Wiedergabe kann hörbare Knackser erzeugen – am besten zwischen zwei Convolvern überblenden.
CORS: Impulsantwort-Dateien von fremden Domains lassen sich per fetch() nur laden, wenn der Server die passenden CORS-Header sendet.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Ältere Safari-Versionen brauchen webkitAudioContext und die Callback-Variante von decodeAudioData().

Siehe auch

ConstantSourceNode.offset ConvolverNode.normalize Node.nodeName Node.nodeType Node.nodeValue