BaseAudioContext.createBiquadFilter() — Methode · JavaScript-Referenz

Signatur

BaseAudioContext.prototype.createBiquadFilter()

Beschreibung

Die Methode createBiquadFilter() eines AudioContext oder OfflineAudioContext erzeugt einen BiquadFilterNode. Das ist ein Filter zweiter Ordnung (Biquad) und der wichtigste Baustein für klassische Klangformung in der Web Audio API: Damit baut man Equalizer, schneidet Brummen oder Rauschen weg, erzeugt Wah-Wah- und Synthesizer-Filtereffekte oder simuliert Telefon- und Radioklang.

Welcher Filter entsteht, legt die Eigenschaft type fest. Möglich sind "lowpass" (Standard), "highpass", "bandpass", "lowshelf", "highshelf", "peaking", "notch" und "allpass". Das Verhalten steuern die AudioParam-Werte frequency (Standard 350 Hz), Q (Güte/Resonanz, Standard 1), gain (in dB, Standard 0, wirkt nur bei Shelf- und Peaking-Filtern) und detune (in Cent). Da es AudioParams sind, lassen sie sich zeitgenau automatisieren, etwa mit setValueAtTime() oder linearRampToValueAtTime().

Der Knoten hat genau einen Eingang und einen Ausgang und wird wie jeder andere AudioNode per connect() zwischen Quelle und Ziel gehängt. Mehrere Filter hintereinander ergeben steilere Flanken oder einen mehrbandigen Equalizer.

Als Alternative gibt es den Konstruktor new BiquadFilterNode(context, options). Mit ihm lassen sich alle Werte direkt beim Erzeugen übergeben, deshalb ist er meist die bessere Wahl.

Rückgabewert

Typ

BiquadFilterNode

Beschreibung

Ein neuer BiquadFilterNode mit den Standardwerten type = "lowpass", frequency = 350, Q = 1, gain = 0 und detune = 0.

Beispiele

Tiefpass für ein Audio-Element (dumpfer Klang)

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

const lowpass = ctx.createBiquadFilter();
lowpass.type = 'lowpass';
lowpass.frequency.value = 800; // alles über ca. 800 Hz wird gedämpft
lowpass.Q.value = 0.7;

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

// Autoplay-Regeln: Kontext erst nach einer Nutzeraktion starten
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  audioEl.play();
});

console.log(lowpass.type, lowpass.frequency.value);

lowpass 800

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

const ctx = new AudioContext();
const osc = ctx.createOscillator();
osc.type = 'sawtooth';

const bass = ctx.createBiquadFilter();
bass.type = 'lowshelf';
bass.frequency.value = 200;
bass.gain.value = 6; // +6 dB Bass

const mid = ctx.createBiquadFilter();
mid.type = 'peaking';
mid.frequency.value = 1000;
mid.Q.value = 1;
mid.gain.value = -4; // Mitten absenken

const treble = ctx.createBiquadFilter();
treble.type = 'highshelf';
treble.frequency.value = 4000;
treble.gain.value = 3;

osc.connect(bass).connect(mid).connect(treble).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 2);

Filter-Sweep (Wah-Effekt) per Automation

const ctx = new AudioContext();
const osc = ctx.createOscillator();
osc.type = 'square';
osc.frequency.value = 110;

const filter = ctx.createBiquadFilter();
filter.type = 'lowpass';
filter.Q.value = 12; // starke Resonanz

const now = ctx.currentTime;
filter.frequency.setValueAtTime(200, now);
filter.frequency.exponentialRampToValueAtTime(5000, now + 1.5);
filter.frequency.exponentialRampToValueAtTime(200, now + 3);

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

Frequenzgang abfragen mit getFrequencyResponse()

const ctx = new AudioContext();
const notch = ctx.createBiquadFilter();
notch.type = 'notch';
notch.frequency.value = 50; // Netzbrummen bei 50 Hz
notch.Q.value = 10;

const freqs = new Float32Array([25, 50, 100]);
const mag = new Float32Array(freqs.length);
const phase = new Float32Array(freqs.length);
notch.getFrequencyResponse(freqs, mag, phase);

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

25 Hz: 0.989 50 Hz: 0.000 100 Hz: 0.994 (Werte gerundet und je nach Browser leicht unterschiedlich)

// Wichtig · Fallstricke

Autoplay: Ein AudioContext startet in vielen Browsern im Zustand "suspended". Rufe ctx.resume() erst nach einer Nutzeraktion auf, sonst ist nichts zu hören.
gain wirkt nur bei manchen Typen: Nur bei lowshelf, highshelf und peaking hat gain eine Wirkung. Bei lowshelf und highshelf wird dafür Q ignoriert.
Resonanz und Übersteuerung: Hohe Q-Werte bei Tief- und Hochpass heben die Grenzfrequenz stark an. Das kann den Ausgang übersteuern (Clipping). Setze bei Bedarf einen GainNode dahinter, der den Pegel absenkt.
Automation: Das direkte Setzen von .value während der Wiedergabe kann Knackser erzeugen. Weiche Übergänge gelingen mit setTargetAtTime() oder Rampen. exponentialRampToValueAtTime() akzeptiert keine 0 als Zielwert.
Flankensteilheit: Ein Biquad-Filter senkt nur um 12 dB pro Oktave ab. Für steilere Flanken schaltet man mehrere Filter hintereinander. Für beliebige Filterkoeffizienten gibt es createIIRFilter().
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Sehr alte Safari-Versionen kannten nur webkitAudioContext, und frühe Implementierungen nutzten numerische Konstanten statt Zeichenketten für type. Heute ist der Konstruktor new BiquadFilterNode(ctx, { type, frequency, Q, gain }) die empfohlene Schreibweise.

Siehe auch

BiquadFilterNode BaseAudioContext AudioContext BaseAudioContext.createIIRFilter() BaseAudioContext.createGain() AudioParam AudioNode.connect() BiquadFilterNode.getFrequencyResponse()