BaseAudioContext.createIIRFilter() — Methode · JavaScript-Referenz

Signatur

BaseAudioContext.prototype.createIIRFilter(feedforward, feedback)

Beschreibung

Die Methode createIIRFilter() eines AudioContext oder OfflineAudioContext erzeugt einen IIRFilterNode. Dieser setzt einen allgemeinen rekursiven Digitalfilter um, dessen Übertragungsfunktion vollständig durch zwei Koeffizienten-Arrays festgelegt wird: die Feedforward-Koeffizienten (Zähler, b) und die Feedback-Koeffizienten (Nenner, a). Die Differenzengleichung lautet: a0·y[n] = Σ b[k]·x[n−k] − Σ a[k]·y[n−k] (für k ≥ 1 im Feedback-Teil).

Anders als der BiquadFilterNode ist ein IIR-Filter nicht auf Filter zweiter Ordnung mit vordefinierten Typen beschränkt. Er eignet sich, wenn man Koeffizienten aus einem Filterentwurfswerkzeug (z. B. MATLAB, SciPy scipy.signal.butter) übernehmen oder spezielle Filter wie DC-Blocker, Pre-Emphasis- oder Klangfärbungsfilter nachbauen möchte.

Wichtig: Die Koeffizienten sind nach der Erstellung unveränderlich – es gibt keine AudioParams zur Automatisierung. Für zeitlich veränderliche Filter (z. B. Filter-Sweeps) ist der BiquadFilterNode die bessere Wahl. Mit getFrequencyResponse() lässt sich der Frequenzgang des Filters auslesen, etwa für eine Visualisierung.

Parameter

Name	Typ	Default	Beschreibung
$feedforward Pflicht	number[] \| Float32Array \| Float64Array		Feedforward-Koeffizienten (Zähler b) der Übertragungsfunktion. 1 bis 20 Elemente, mindestens ein Wert darf nicht 0 sein.
$feedback Pflicht	number[] \| Float32Array \| Float64Array		Feedback-Koeffizienten (Nenner a). 1 bis 20 Elemente; das erste Element `a0` darf nicht 0 sein. Die Koeffizienten werden intern durch `a0` normiert.

Rückgabewert

Typ

IIRFilterNode

Beschreibung

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

Beispiele

Einfacher Tiefpass erster Ordnung auf einen Oszillator

const ctx = new AudioContext();

// y[n] = 0.1·x[n] + 0.9·y[n-1]  → glättender Tiefpass
const lowpass = ctx.createIIRFilter([0.1], [1, -0.9]);

const osc = ctx.createOscillator();
osc.type = 'sawtooth';
osc.frequency.value = 220;

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

// Nach Nutzerinteraktion starten (Autoplay-Richtlinie)
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  osc.start();
  osc.stop(ctx.currentTime + 2);
});

DC-Blocker für Mikrofon-Eingang

const ctx = new AudioContext();

// Klassischer DC-Blocker: y[n] = x[n] - x[n-1] + 0.995·y[n-1]
const dcBlocker = ctx.createIIRFilter([1, -1], [1, -0.995]);

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const source = ctx.createMediaStreamSource(stream);

source.connect(dcBlocker).connect(ctx.destination);
console.log('DC-Blocker aktiv:', dcBlocker instanceof IIRFilterNode);

DC-Blocker aktiv: true

Frequenzgang auslesen

const ctx = new AudioContext();
const filter = ctx.createIIRFilter([0.1], [1, -0.9]);

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.1 dB 1000 Hz: -6.5 dB 10000 Hz: -15.6 dB (Werte abhängig von der Abtastrate, hier ca. 48 kHz)

Fehlerbehandlung bei ungültigen Koeffizienten

const ctx = new AudioContext();

try {
  ctx.createIIRFilter([1, 0.5], [0, 1]); // a0 = 0 ist unzulässig
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Ausnahmen: NotSupportedError, wenn ein Array leer ist oder mehr als 20 Elemente hat; InvalidStateError, wenn alle Feedforward-Koeffizienten 0 sind oder feedback[0] 0 ist.
Stabilität: Der Browser prüft nicht, ob der Filter stabil ist. Liegen Pole außerhalb des Einheitskreises, wächst das Signal unkontrolliert – im schlimmsten Fall laute Verzerrungen oder NaN/Stille. Koeffizienten vorher prüfen, Lautstärke beim Testen niedrig halten.
Abtastrate: Koeffizienten gelten für eine bestimmte Abtastrate. Da ctx.sampleRate je nach Gerät 44,1 oder 48 kHz sein kann, Koeffizienten zur Laufzeit berechnen oder den Kontext mit fester sampleRate erzeugen.
Keine Automatisierung: Koeffizienten lassen sich nachträglich nicht ändern; für neue Werte einen neuen Knoten erzeugen.
Numerik: Hohe Filterordnungen in einem einzigen Knoten sind numerisch empfindlich. Besser mehrere Filter zweiter Ordnung hintereinanderschalten.
Kompatibilität: In allen aktuellen Browsern verfügbar (Chrome 49+, Firefox 50+, Safari 14.1+). Alternativ kann der Konstruktor new IIRFilterNode(ctx, { feedforward, feedback }) verwendet werden.

Siehe auch

BaseAudioContext.createBiquadFilter() BaseAudioContext.createBuffer() BaseAudioContext.createConvolver() BaseAudioContext.createAnalyser() BaseAudioContext.createOscillator()