BiquadFilterNode — Schnittstelle · JavaScript-Referenz

Signatur

interface BiquadFilterNode extends AudioNode

Beschreibung

BiquadFilterNode ist ein einfacher Filter niedriger Ordnung (zweiter Ordnung, „biquadratisch“) aus der Web Audio API. Er hat genau einen Eingang und einen Ausgang und wird entweder über BaseAudioContext.createBiquadFilter() oder über den Konstruktor new BiquadFilterNode(context, options) erzeugt. Typische Einsatzgebiete sind Klangregelung (Equalizer), das Entfernen von Brummen oder Rauschen, Synthesizer-Filter und Effekte wie „Wah-Wah“ oder Telefon-Sound.

Wie der Filter arbeitet, bestimmt die Eigenschaft type: "lowpass" (Standard), "highpass", "bandpass", "lowshelf", "highshelf", "peaking", "notch" und "allpass". Gesteuert wird er über vier AudioParam-Eigenschaften:

frequency – Grenz- bzw. Mittenfrequenz in Hz (Standard 350).
detune – Verstimmung der Frequenz in Cent (Standard 0).
Q – Güte/Resonanz; bestimmt die Bandbreite bzw. Überhöhung (Standard 1).
gain – Verstärkung in dB (Standard 0); wirkt nur bei lowshelf, highshelf und peaking.

Da es sich um AudioParams handelt, lassen sich die Werte sampelgenau automatisieren (setValueAtTime(), linearRampToValueAtTime(), setTargetAtTime()) oder per connect() von einem LFO modulieren. Die Methode getFrequencyResponse(frequencyHz, magResponse, phaseResponse) berechnet den Amplituden- und Phasengang für beliebige Frequenzen – praktisch zum Zeichnen einer EQ-Kurve.

Für steilere Flanken schaltet man mehrere Filter hintereinander. Wer beliebige Filterkoeffizienten benötigt, greift zu IIRFilterNode.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehört (nur beim Konstruktor).
$options.type	"lowpass"\|"highpass"\|"bandpass"\|"lowshelf"\|"highshelf"\|"peaking"\|"notch"\|"allpass"	"lowpass"	Filtertyp.
$options.frequency	number	350	Anfangswert für `frequency` in Hz (0 bis Nyquist-Frequenz).
$options.Q	number	1	Anfangswert für die Güte `Q`.
$options.gain	number	0	Anfangswert für `gain` in dB (nur Shelf- und Peaking-Filter).
$options.detune	number	0	Anfangswert für `detune` in Cent.
$options.channelCount / channelCountMode / channelInterpretation	number\|string		Übliche `AudioNode`-Kanaloptionen.

Rückgabewert

Typ

BiquadFilterNode

Beschreibung

Ein neuer Filterknoten, der mit connect() in den Audiograph eingebunden werden kann.

Beispiele

Tiefpass-Filter für ein Audio-Element (Factory und Konstruktor)

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

// Variante 1: Factory-Methode
const lowpass = ctx.createBiquadFilter();
lowpass.type = 'lowpass';
lowpass.frequency.value = 800; // alles über ~800 Hz dämpfen
lowpass.Q.value = 0.7;

// Variante 2: Konstruktor mit Optionen
const highpass = new BiquadFilterNode(ctx, { type: 'highpass', frequency: 80 });

source.connect(highpass).connect(lowpass).connect(ctx.destination);

// Autoplay-Richtlinie: Kontext erst nach Nutzeraktion starten
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  audio.play();
});
console.log(lowpass.type, lowpass.frequency.value, highpass.frequency.value);

lowpass 800 80

Filter-Sweep mit Automatisierung (Synthesizer)

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

osc.connect(filter).connect(ctx.destination);

const now = ctx.currentTime;
filter.frequency.setValueAtTime(200, now);
filter.frequency.exponentialRampToValueAtTime(5000, now + 2); // hoch sweepen
filter.frequency.exponentialRampToValueAtTime(200, now + 4);  // zurück

osc.start(now);
osc.stop(now + 4);

3-Band-Equalizer mit Shelf- und Peaking-Filtern

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

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

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

// Regler-Wert sanft übernehmen (vermeidet Knackser)
const setBass = (db) => bass.gain.setTargetAtTime(db, ctx.currentTime, 0.02);
setBass(10);
console.log(bass.type, mid.type, treble.type);

lowshelf peaking highshelf

Frequenzgang mit getFrequencyResponse() berechnen

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

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

filter.getFrequencyResponse(freqs, mag, phase);

freqs.forEach((f, i) => {
  const db = 20 * Math.log10(mag[i]);
  console.log(`${f} Hz: ${db.toFixed(1)} dB`);
});

100 Hz: 0.0 dB 1000 Hz: 0.0 dB 10000 Hz: -39.9 dB (Werte ungefähr, abhängig von der Abtastrate)

// Wichtig · Fallstricke

gain wird nicht immer verwendet: Bei lowpass, highpass, bandpass, notch und allpass hat gain keine Wirkung. Bei lowshelf/highshelf wird dafür Q ignoriert.
Bedeutung von Q je nach Typ: Bei Tief- und Hochpass wird Q in dB interpretiert (Resonanzüberhöhung). Hohe Werte können das Signal stark übersteuern – dahinter einen GainNode oder DynamicsCompressorNode einsetzen.
Knackser vermeiden: Direktes Setzen von .value während der Wiedergabe kann hörbare Sprünge verursachen. Besser setTargetAtTime() oder Rampen verwenden. exponentialRampToValueAtTime() erlaubt keinen Zielwert 0.
Frequenzbereich: frequency wird auf 0 bis zur Nyquist-Frequenz (sampleRate / 2) begrenzt.
Flankensteilheit: Ein einzelner Biquad liefert nur 12 dB/Oktave. Für steilere Filter mehrere Knoten hintereinanderschalten.
Autoplay: Ein AudioContext startet in vielen Browsern im Zustand "suspended" und muss nach einer Nutzeraktion mit resume() gestartet werden.
Kompatibilität: In allen modernen Browsern verfügbar. Der Konstruktor new BiquadFilterNode() fehlt in sehr alten Safari-Versionen (vor 14.1); dort funktioniert nur createBiquadFilter(), teils mit dem Präfix webkitAudioContext.

Siehe auch

IIRFilterNode AnalyserNode AudioNode ConvolverNode PannerNode