new BiquadFilterNode() — Methode · JavaScript-Referenz

Signatur

new BiquadFilterNode(context, options)

Beschreibung

Der Konstruktor BiquadFilterNode() erzeugt einen Filterknoten für die Web Audio API. Ein Biquad-Filter ist ein Filter zweiter Ordnung. Mit ihm lassen sich typische Klangformungen umsetzen: Tiefpass (lowpass), Hochpass (highpass), Bandpass, Kerbfilter (notch), Kuhschwanzfilter (lowshelf/highshelf), parametrischer EQ (peaking) und Allpass.

Im Unterschied zur älteren Fabrikmethode AudioContext.createBiquadFilter() kannst du alle Startwerte direkt über ein options-Objekt übergeben. Das ist kompakter und passt zum heutigen Konstruktor-Stil der Web Audio API. Der Knoten hat genau einen Eingang und einen Ausgang. Du baust ihn mit connect() zwischen Quelle und Ziel ein.

Die Eigenschaften frequency, detune, Q und gain sind AudioParam-Objekte. Du kannst sie also zur Laufzeit zeitgenau automatisieren, etwa mit setValueAtTime() oder linearRampToValueAtTime(). Klassische Anwendungen sind Filter-Sweeps bei Synthesizern, Equalizer in Audio-Playern und das Entfernen von Brummen oder Rauschen.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehören soll.
$options	object	{}	Optionale Startwerte: `type` – Filtertyp als String (`"lowpass"`, `"highpass"`, `"bandpass"`, `"lowshelf"`, `"highshelf"`, `"peaking"`, `"notch"`, `"allpass"`), Standard `"lowpass"` `frequency` – Grenz- bzw. Mittenfrequenz in Hz, Standard `350` `Q` – Güte bzw. Resonanz, Standard `1` `gain` – Verstärkung in dB (nur bei Shelf- und Peaking-Filtern wirksam), Standard `0` `detune` – Verstimmung der Frequenz in Cent, Standard `0` `channelCount`, `channelCountMode`, `channelInterpretation` – allgemeine `AudioNode`-Optionen

Rückgabewert

Typ

BiquadFilterNode

Beschreibung

Ein neuer BiquadFilterNode, der fest an den übergebenen Kontext gebunden ist.

Beispiele

Tiefpassfilter für einen Oszillator

const ctx = new AudioContext();

const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 220 });
const filter = new BiquadFilterNode(ctx, {
  type: 'lowpass',
  frequency: 800,
  Q: 5
});

osc.connect(filter).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);

console.log(filter.type, filter.frequency.value, filter.Q.value);

lowpass 800 5

Filter-Sweep per AudioParam-Automatisierung

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'square', frequency: 110 });
const filter = new BiquadFilterNode(ctx, { type: 'lowpass', Q: 12 });

const now = ctx.currentTime;
// Grenzfrequenz in 3 Sekunden von 200 Hz auf 5000 Hz anheben
filter.frequency.setValueAtTime(200, now);
filter.frequency.exponentialRampToValueAtTime(5000, now + 3);

osc.connect(filter).connect(ctx.destination);
osc.start(now);
osc.stop(now + 3);

Einfacher 3-Band-Equalizer für ein Audio-Element

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });

const bass = new BiquadFilterNode(ctx, { type: 'lowshelf', frequency: 200, gain: 6 });
const mid = new BiquadFilterNode(ctx, { type: 'peaking', frequency: 1000, Q: 1, gain: -3 });
const treble = new BiquadFilterNode(ctx, { type: 'highshelf', frequency: 4000, gain: 4 });

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

// Autoplay-Richtlinien: Kontext erst nach Nutzeraktion fortsetzen
audio.addEventListener('play', () => ctx.resume());

Frequenzgang berechnen mit getFrequencyResponse()

const ctx = new AudioContext();
const filter = new BiquadFilterNode(ctx, { type: 'highpass', frequency: 1000 });

const freqs = new Float32Array([100, 1000, 10000]);
const mag = new Float32Array(3);
const phase = new Float32Array(3);
filter.getFrequencyResponse(freqs, mag, phase);

freqs.forEach((f, i) => console.log(`${f} Hz: ${mag[i].toFixed(3)}`));

100 Hz: 0.010 1000 Hz: 0.707 10000 Hz: 1.000 (Werte gerundet und abhängig von der Abtastrate)

// Wichtig · Fallstricke

Autoplay-Sperre: Ein AudioContext startet in vielen Browsern im Zustand suspended. Erst ein ctx.resume() nach einer Nutzeraktion (z. B. einem Klick) macht den Ton hörbar.
Der Parameter gain wirkt nur bei lowshelf, highshelf und peaking. Bei lowshelf und highshelf wird Q ignoriert.
Ein ungültiger type-String im options-Objekt löst einen TypeError aus.
exponentialRampToValueAtTime() akzeptiert weder 0 noch einen Wechsel des Vorzeichens. Beginne einen Frequenz-Sweep deshalb bei einem positiven Wert.
Sehr hohe Q-Werte führen zu starker Resonanz und können übersteuern. Setze bei Bedarf einen GainNode dahinter.
Kompatibilität: Der Konstruktor ist in allen aktuellen Browsern verfügbar. Sehr alte Browser (z. B. Safari vor 14.1) kennen nur ctx.createBiquadFilter(), das du als Rückfallebene nutzen kannst.
Für Filter höherer Ordnung schaltest du mehrere Knoten hintereinander. Für eigene Filterkoeffizienten gibt es IIRFilterNode.

Siehe auch

new ChannelSplitterNode() new IIRFilterNode() new AnalyserNode() new ConvolverNode() new PannerNode()