ConvolverNode.normalize — Eigenschaft · JavaScript-Referenz

Signatur

ConvolverNode.normalize

Beschreibung

Die Eigenschaft normalize eines ConvolverNode legt fest, ob die Impulsantwort (Impulse Response, IR) aus dem zugewiesenen AudioBuffer beim Setzen von buffer skaliert wird. Ist der Wert true (Standard), berechnet der Browser einen Skalierungsfaktor. Dadurch klingen unterschiedlich laute Impulsantworten ähnlich laut, und das Ausgangssignal wird nicht zu laut und übersteuert nicht.

Wichtig: Der Wert wird nur beim Zuweisen von buffer ausgewertet. Wenn du normalize später änderst, wirkt sich das nicht auf den bereits gesetzten Puffer aus. Du musst normalize also vor der Zuweisung von buffer setzen oder den Puffer danach neu zuweisen.

Setze normalize = false, wenn deine Impulsantwort schon richtig eingepegelt ist, etwa eine gemessene Raumantwort mit bekannter Lautstärke. Das gilt auch, wenn du den ConvolverNode für präzise Filter (FIR-Filter) nutzt und die IR nicht verändert werden darf. Im Konstruktor kannst du die Normalisierung über die Option disableNormalization abschalten.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Impulsantwort beim nächsten Setzen von buffer normalisiert wird (Standard). Sonst false.

Beispiele

Normalisierung abschalten, bevor der Puffer gesetzt wird

const ctx = new AudioContext();
const convolver = ctx.createConvolver();

console.log(convolver.normalize); // Standardwert

// Reihenfolge ist wichtig: zuerst normalize, dann buffer
convolver.normalize = false;

const response = await fetch('/audio/hall-ir.wav');
const arrayBuffer = await response.arrayBuffer();
convolver.buffer = await ctx.decodeAudioData(arrayBuffer);

console.log(convolver.normalize);

true false

Über den Konstruktor mit disableNormalization

const ctx = new AudioContext();

// Kurze synthetische Impulsantwort: exponentiell abklingendes Rauschen
const length = ctx.sampleRate * 1.5;
const ir = ctx.createBuffer(2, length, ctx.sampleRate);
for (let ch = 0; ch < 2; ch++) {
  const data = ir.getChannelData(ch);
  for (let i = 0; i < length; i++) {
    data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / length, 3);
  }
}

const convolver = new ConvolverNode(ctx, {
  buffer: ir,
  disableNormalization: true
});

console.log(convolver.normalize);

false

Nachträglich umschalten: Puffer neu zuweisen

const toggleNormalize = (convolver, enabled) => {
  const ir = convolver.buffer;
  convolver.normalize = enabled;
  // Ohne erneute Zuweisung bleibt die alte Skalierung aktiv
  convolver.buffer = null;
  convolver.buffer = ir;
};

const ctx = new AudioContext();
const convolver = ctx.createConvolver();
convolver.buffer = ctx.createBuffer(2, ctx.sampleRate, ctx.sampleRate);

toggleNormalize(convolver, false);
console.log(convolver.normalize);

false

// Wichtig · Fallstricke

Reihenfolge beachten: normalize wirkt erst beim nächsten Zuweisen von buffer. Wenn du den Wert erst nach dem Laden des Puffers änderst, passiert hörbar nichts.
Ohne Normalisierung kann die Faltung mit einer lauten oder langen Impulsantwort den Pegel stark erhöhen und übersteuern (Clipping). Senke den Pegel dann gegebenenfalls mit einem GainNode.
Im Konstruktor heißt die Option umgekehrt disableNormalization: true entspricht normalize = false.
Wie genau der Skalierungsfaktor berechnet wird, ist in der Web-Audio-Spezifikation festgelegt. Zwischen verschiedenen Browsern kann es trotzdem minimale Pegelunterschiede geben.
Kompatibilität: Die Eigenschaft wird in allen aktuellen Browsern unterstützt. Der Konstruktor new ConvolverNode() wird in sehr alten Safari-Versionen nicht unterstützt; dort nutzt du createConvolver().

Siehe auch

ConvolverNode ConvolverNode.buffer BaseAudioContext.createConvolver() AudioBuffer BaseAudioContext.decodeAudioData() GainNode ResizeObserverSize.blockSize