BiquadFilterNode.gain — Eigenschaft · JavaScript-Referenz

Signatur

BiquadFilterNode.gain

Beschreibung

Die Eigenschaft gain eines BiquadFilterNode liefert einen a-rate AudioParam. Sein Wert ist eine Gleitkommazahl in Dezibel (dB), die festlegt, wie stark der betroffene Frequenzbereich angehoben (positiver Wert) oder abgesenkt (negativer Wert) wird. Der Standardwert ist 0, der Filter verändert den Pegel dann also nicht.

Ob gain überhaupt wirkt, hängt von BiquadFilterNode.type ab:

lowshelf: Verstärkung bzw. Absenkung aller Frequenzen unterhalb von frequency (z. B. Bassregler).
highshelf: Verstärkung bzw. Absenkung aller Frequenzen oberhalb von frequency (z. B. Höhenregler).
peaking: Verstärkung bzw. Absenkung eines Bandes um frequency, dessen Breite Q bestimmt (klassisches parametrisches EQ-Band).
lowpass, highpass, bandpass, notch, allpass: gain wird ignoriert.

Da es sich um einen AudioParam handelt, setzt man nicht die Eigenschaft selbst, sondern ihren value oder plant Änderungen sampelgenau mit Methoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Als a-rate-Parameter kann gain außerdem von einem anderen Audio-Knoten (z. B. einem OscillatorNode als LFO) moduliert werden.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein a-rate AudioParam; defaultValue ist 0 (dB), minValue ≈ -3.4028235e38, maxValue ≈ 1541.27 (entspricht 40 · log10(FLT_MAX)).

Beispiele

Bassanhebung mit einem Lowshelf-Filter

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = ctx.createMediaElementSource(audio);

const bass = new BiquadFilterNode(ctx, {
  type: 'lowshelf',
  frequency: 200, // alles unter 200 Hz
  gain: 6         // um 6 dB anheben
});

source.connect(bass).connect(ctx.destination);

console.log(bass.gain.value, bass.gain.defaultValue);

6 0

Dreiband-Equalizer mit Schiebereglern

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 110 });

const low  = new BiquadFilterNode(ctx, { type: 'lowshelf',  frequency: 250 });
const mid  = new BiquadFilterNode(ctx, { type: 'peaking',   frequency: 1000, Q: 1 });
const high = new BiquadFilterNode(ctx, { type: 'highshelf', frequency: 4000 });

osc.connect(low).connect(mid).connect(high).connect(ctx.destination);
osc.start();

// <input type="range" min="-12" max="12" step="0.5" data-band="low"> usw.
const bands = { low, mid, high };
document.querySelectorAll('input[data-band]').forEach((slider) => {
  slider.addEventListener('input', () => {
    const filter = bands[slider.dataset.band];
    // weich nachführen statt hart springen -> keine Knackser
    filter.gain.setTargetAtTime(Number(slider.value), ctx.currentTime, 0.02);
  });
});

Gain-Verlauf zeitgenau planen

const ctx = new AudioContext();
const noise = ctx.createBufferSource();
const buffer = ctx.createBuffer(1, ctx.sampleRate * 2, ctx.sampleRate);
const data = buffer.getChannelData(0);
for (let i = 0; i < data.length; i++) data[i] = Math.random() * 2 - 1;
noise.buffer = buffer;

const peak = new BiquadFilterNode(ctx, { type: 'peaking', frequency: 2000, Q: 5 });
noise.connect(peak).connect(ctx.destination);

const t = ctx.currentTime;
peak.gain.setValueAtTime(-20, t);             // Band stark absenken
peak.gain.linearRampToValueAtTime(15, t + 2); // in 2 s auf +15 dB anheben
noise.start(t);
noise.stop(t + 2);

// Wichtig · Fallstricke

Nur bei drei Filtertypen wirksam: Bei lowpass, highpass, bandpass, notch und allpass hat gain keinerlei Effekt. Häufiger Fehler: Man setzt gain und wundert sich, dass sich nichts ändert.
Die Eigenschaft ist schreibgeschützt: filter.gain = 6 funktioniert nicht (im Strict Mode, also auch in ES-Modulen, gibt es einen TypeError). Richtig ist filter.gain.value = 6 oder eine der Planungsmethoden.
Einheit Dezibel, kein linearer Faktor: Anders als bei GainNode.gain bedeutet 0 „unverändert“, +6 ungefähr doppelte und -6 ungefähr halbe Amplitude im betroffenen Band.
Übersteuerung: Große positive Werte können das Signal über ±1,0 treiben und so Verzerrungen (Clipping) verursachen. Eventuell mit DynamicsCompressorNode oder einem nachgeschalteten GainNode gegensteuern.
Knackser vermeiden: Wenn value während der Wiedergabe sprunghaft geändert wird, kann es hörbar knacken. Besser setTargetAtTime() oder Rampen verwenden.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Der Konstruktor new BiquadFilterNode(ctx, options) fehlt in sehr alten Browsern; dort stattdessen ctx.createBiquadFilter() nutzen.

Siehe auch

BiquadFilterNode BiquadFilterNode.type BiquadFilterNode.frequency BiquadFilterNode.Q AudioParam AudioParam.prototype.setTargetAtTime() GainNode