BiquadFilterNode.Q — Eigenschaft · JavaScript-Referenz

Signatur

BiquadFilterNode.Q

Beschreibung

Die Eigenschaft Q eines BiquadFilterNode liefert einen AudioParam, der den Qualitätsfaktor (Güte) des Filters festlegt. Die Eigenschaft selbst ist schreibgeschützt: Man weist nicht filter.Q zu, sondern setzt filter.Q.value oder nutzt die Automatisierungsmethoden wie setValueAtTime(), linearRampToValueAtTime() oder setTargetAtTime(). Als a-rate-Parameter kann der Wert für jedes einzelne Audio-Sample neu berechnet werden, was flüssige Filterfahrten ohne Knackser erlaubt.

Wie der Wert interpretiert wird, hängt vom Filtertyp (filter.type) ab:

lowpass / highpass: Q wird in Dezibel angegeben und bestimmt die Resonanzspitze an der Grenzfrequenz. Höhere Werte erzeugen einen deutlich hörbaren, „singenden" Resonanzpeak – typisch für Synthesizer-Sounds.
bandpass, notch, allpass, peaking: Q ist ein linearer Wert und steuert die Bandbreite (ungefähr Mittenfrequenz ÷ Bandbreite). Großes Q = schmales Band, kleines Q = breites Band.
lowshelf / highshelf: Q wird nicht verwendet.

Der Standardwert ist 1. Der nominale Wertebereich reicht vom kleinsten bis zum größten darstellbaren 32-Bit-Float; sinnvoll sind in der Praxis meist Werte zwischen etwa 0.0001 und 30 bzw. einige Dezibel bei Tief-/Hochpass.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein AudioParam mit defaultValue 1 und automationRate "a-rate". Der aktuelle Wert steht in Q.value.

Beispiele

Resonanten Tiefpass einstellen

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

// Q beim Tiefpass in dB: deutliche Resonanzspitze
filter.Q.value = 12;

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

console.log(filter.Q.value, filter.Q.defaultValue);

12 1

Filterfahrt mit automatisiertem Q (Synth-Sweep)

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 55 });
const filter = new BiquadFilterNode(ctx, { type: 'lowpass', frequency: 200, Q: 0 });
osc.connect(filter).connect(ctx.destination);

const t = ctx.currentTime;
// Grenzfrequenz und Resonanz gemeinsam hochfahren
filter.frequency.setValueAtTime(200, t);
filter.frequency.exponentialRampToValueAtTime(4000, t + 3);
filter.Q.setValueAtTime(0, t);
filter.Q.linearRampToValueAtTime(20, t + 3);

osc.start(t);
osc.stop(t + 3.5);

Bandpass: Q aus gewünschter Bandbreite berechnen

const ctx = new AudioContext();
const center = 1000;   // Mittenfrequenz in Hz
const bandwidth = 200; // gewünschte Bandbreite in Hz

const bandpass = new BiquadFilterNode(ctx, {
  type: 'bandpass',
  frequency: center,
  Q: center / bandwidth // lineares Q = f0 / Bandbreite
});

console.log(`Q = ${bandpass.Q.value}`);

Q = 5

Auswirkung von Q per Frequenzgang prüfen

const ctx = new AudioContext();
const filter = new BiquadFilterNode(ctx, { type: 'peaking', frequency: 1000, gain: 12 });
const freqs = new Float32Array([500, 1000, 2000]);
const mag = new Float32Array(3);
const phase = new Float32Array(3);

for (const q of [0.5, 5]) {
  filter.Q.value = q;
  filter.getFrequencyResponse(freqs, mag, phase);
  const db = [...mag].map(m => (20 * Math.log10(m)).toFixed(1));
  console.log(`Q=${q}:`, db.join(' dB, ') + ' dB');
}

Q=0.5: ≈ 8 dB, 12.0 dB, ≈ 8 dB Q=5: ≈ 0.5 dB, 12.0 dB, ≈ 0.5 dB

// Wichtig · Fallstricke

Nicht direkt zuweisen: filter.Q = 5 bewirkt nichts (bzw. wirft im Strict Mode einen Fehler), da Q schreibgeschützt ist. Immer filter.Q.value oder Automatisierungsmethoden verwenden.
Einheit hängt vom Typ ab: Bei lowpass/highpass ist Q in dB (ein Butterworth-artiger, flacher Verlauf ohne Resonanz entspricht etwa -3.01 dB), bei bandpass, notch, peaking, allpass ein linearer Faktor. Bei lowshelf/highshelf wird Q ignoriert.
Werte ≤ 0: Bei Bandfiltern führen Q-Werte von 0 oder negative Werte zu degenerierten Filtern (z. B. Stille oder unverändertes Signal). Positive Werte verwenden.
Lautstärke: Hohe Resonanz beim Tief-/Hochpass kann starke Pegelspitzen erzeugen – ggf. einen GainNode oder DynamicsCompressorNode nachschalten.
Automatisierung vs. value: Wenn Automatisierungsereignisse geplant sind, wird ein direktes Setzen von value eventuell überschrieben. Bei laufender Wiedergabe für weiche Übergänge setTargetAtTime() statt harter Sprünge nutzen, um Knackser zu vermeiden.
Kompatibilität: In allen modernen Browsern verfügbar. Ein AudioContext startet wegen Autoplay-Richtlinien oft im Zustand suspended und muss nach einer Nutzerinteraktion per ctx.resume() fortgesetzt werden. Ältere WebKit-Versionen benötigten webkitAudioContext.

Siehe auch

BiquadFilterNode BiquadFilterNode.frequency BiquadFilterNode.gain BiquadFilterNode.detune BiquadFilterNode.type BiquadFilterNode.getFrequencyResponse() AudioParam AudioParam.setTargetAtTime()