IIRFilterNode — Schnittstelle · JavaScript-Referenz

Signatur

interface IIRFilterNode extends AudioNode

Beschreibung

IIRFilterNode ist ein Verarbeitungsknoten der Web Audio API, der einen allgemeinen IIR-Filter umsetzt. Anders als bei BiquadFilterNode gibst du die Übertragungsfunktion direkt über zwei Koeffizienten-Arrays vor: feedforward (Zähler, b-Koeffizienten) und feedback (Nenner, a-Koeffizienten). Damit lassen sich Filter höherer Ordnung, eigene Equalizer, Klangregler oder nachgebildete analoge Schaltungen bauen.

Der Knoten hat genau einen Eingang und einen Ausgang. Die Anzahl der Ausgabekanäle entspricht der der Eingabe. Erzeugt wird er mit AudioContext.createIIRFilter(feedforward, feedback) oder dem Konstruktor new IIRFilterNode(context, { feedforward, feedback }). Nach dem Erzeugen sind die Koeffizienten unveränderlich – es gibt keine AudioParams zur Automatisierung.

Die einzige eigene Methode ist getFrequencyResponse(frequencyHz, magResponse, phaseResponse). Sie berechnet für ein Array von Frequenzen den Betrags- und Phasengang des Filters, etwa um eine Filterkurve in einem <canvas> zu zeichnen.

Einsatzfälle: Wenn die Standardtypen von BiquadFilterNode nicht reichen, du Koeffizienten aus einem Filterentwurf (z. B. aus MATLAB, SciPy) übernehmen willst oder einen Filter erster Ordnung brauchst. Für Filter, deren Parameter sich zur Laufzeit ändern sollen, ist BiquadFilterNode meist die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der Audio-Kontext, zu dem der Knoten gehört (nur beim Konstruktor).
$options.feedforward Pflicht	number[] \| Float32Array		Zähler-Koeffizienten (b₀…b_M) der Übertragungsfunktion. 1 bis 20 Werte, nicht alle dürfen 0 sein.
$options.feedback Pflicht	number[] \| Float32Array		Nenner-Koeffizienten (a₀…a_N). 1 bis 20 Werte; `a0` darf nicht 0 sein. Werte werden intern durch `a0` normiert.
$options.channelCount / channelCountMode / channelInterpretation	number \| string	2 / "max" / "speakers"	Übliche `AudioNodeOptions` zur Kanalbehandlung.

Rückgabewert

Typ

IIRFilterNode

Beschreibung

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

Beispiele

Einfacher Tiefpass erster Ordnung per Konstruktor

const ctx = new AudioContext();

// Einpoliger Tiefpass: y[n] = 0.1*x[n] + 0.9*y[n-1]
const lowpass = new IIRFilterNode(ctx, {
  feedforward: [0.1],
  feedback: [1, -0.9]
});

const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 220 });
osc.connect(lowpass).connect(ctx.destination);

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  osc.start();
  osc.stop(ctx.currentTime + 2);
});

Mikrofon-Signal mit createIIRFilter filtern

const ctx = new AudioContext();

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

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

  source.connect(dcBlocker).connect(ctx.destination);
  console.log('Filter aktiv:', dcBlocker instanceof IIRFilterNode);
};

document.querySelector('#mic').addEventListener('click', start);

Filter aktiv: true

Frequenzgang mit getFrequencyResponse auslesen

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

const freqs = new Float32Array([100, 1000, 5000, 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: -2.4 dB 5000 Hz: -12.5 dB 10000 Hz: -16.4 dB (Werte abhängig von der Abtastrate, hier ca. 48 kHz)

// Wichtig · Fallstricke

Koeffizienten sind fest: Nach dem Erzeugen lassen sie sich nicht mehr ändern. Für neue Werte einen neuen Knoten erzeugen und umverbinden (ggf. per GainNode überblenden, um Knackser zu vermeiden).
Grenzen: Beide Arrays müssen 1–20 Einträge haben, sonst gibt es einen NotSupportedError. Sind alle feedforward-Werte 0 oder ist feedback[0] gleich 0, wird ein InvalidStateError geworfen.
Stabilität: Liegen Pole außerhalb des Einheitskreises, wird der Filter instabil und die Ausgabe schaukelt sich auf (Browser können einen Warnhinweis ausgeben). Filter hoher Ordnung sind numerisch empfindlich – besser mehrere Biquads in Reihe schalten.
Abtastrate: Die Koeffizienten beziehen sich auf die sampleRate des Kontexts; bei 44,1 kHz und 48 kHz ergeben dieselben Werte unterschiedliche Grenzfrequenzen.
getFrequencyResponse() wirft einen InvalidAccessError, wenn die drei Arrays unterschiedlich lang sind.
Kompatibilität: unterstützt in Chrome 49+, Firefox 50+, Safari 14.1+ und Edge 79+. Der Konstruktor new IIRFilterNode() ist in älteren Safari-Versionen nicht verfügbar – dort createIIRFilter() verwenden. Ein AudioContext startet wegen der Autoplay-Regeln erst nach einer Nutzeraktion.

Siehe auch

BiquadFilterNode ConvolverNode AnalyserNode FileReader OscillatorNode