BiquadFilterNode.detune — Eigenschaft · JavaScript-Referenz

Signatur

BiquadFilterNode.detune

Beschreibung

Die Eigenschaft detune eines BiquadFilterNode liefert einen AudioParam, mit dem sich die Grenz- bzw. Mittenfrequenz des Filters relativ verschieben lässt, und zwar in Cent. Die tatsächlich wirksame Frequenz ergibt sich aus frequency * 2^(detune / 1200). Ein Wert von 1200 verdoppelt die Frequenz also (eine Oktave höher), -1200 halbiert sie.

Weil es sich um einen a-rate-Parameter handelt, wird der Wert für jedes einzelne Sample berechnet. Deshalb eignet er sich gut für feine Modulationen, zum Beispiel für einen Filter-Sweep in musikalischen Intervallen, eine LFO-Modulation über einen OscillatorNode oder eine Hüllkurve, die über setValueAtTime(), linearRampToValueAtTime() oder exponentialRampToValueAtTime() geplant wird.

Die Eigenschaft selbst ist schreibgeschützt. Du weist also nicht filter.detune zu, sondern setzt filter.detune.value oder nutzt die Automationsmethoden des AudioParam. Der Standardwert ist 0. Das ist praktisch, wenn du Frequenzen musikalisch in Halbtönen statt in Hertz steuern willst.

Rückgabewert

Typ

AudioParam

Beschreibung

Ein a-rate-AudioParam mit dem Standardwert 0. Der nominelle Bereich liegt bei etwa ±1200 * log2(Number.MAX_VALUE) (ca. ±153600 Cent).

Beispiele

Filter um eine Oktave nach oben verstimmen

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

// +1200 Cent = eine Oktave höher → effektiv 1600 Hz
filter.detune.value = 1200;

osc.connect(filter).connect(ctx.destination);
osc.start();
console.log(filter.detune.value, filter.detune.defaultValue);

1200 0

Filter-Sweep über zwei Oktaven automatisieren

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

const now = ctx.currentTime;
filter.detune.setValueAtTime(0, now);
// In 2 Sekunden linear auf +2400 Cent (zwei Oktaven → 1600 Hz)
filter.detune.linearRampToValueAtTime(2400, now + 2);

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

LFO moduliert detune (Wah-Effekt)

const ctx = new AudioContext();
const source = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 130.81 });
const filter = new BiquadFilterNode(ctx, { type: 'bandpass', frequency: 1000, Q: 8 });

// LFO mit 3 Hz, Hub von ±1200 Cent
const lfo = new OscillatorNode(ctx, { frequency: 3 });
const depth = new GainNode(ctx, { gain: 1200 });
lfo.connect(depth).connect(filter.detune);

source.connect(filter).connect(ctx.destination);
source.start();
lfo.start();

// Wichtig · Fallstricke

Nicht direkt zuweisen: filter.detune = 100 hat keine Wirkung, weil die Eigenschaft schreibgeschützt ist. Verwende stattdessen filter.detune.value = 100.
Zusammenspiel mit frequency: Beide Parameter werden kombiniert. Die Nyquist-Frequenz (sampleRate / 2) begrenzt das Ergebnis. Ein großer detune-Wert kann daher unerwartet an die Obergrenze stoßen.
Automationskonflikte: Solange Automationsereignisse geplant sind, werden direkte Zuweisungen an .value ignoriert oder überschrieben. Setze vorher cancelScheduledValues() ein.
exponentialRampToValueAtTime() akzeptiert keinen Zielwert 0. Das ist bei detune ungünstig, weil der Standardwert 0 ist. Nutze dafür lineare Rampen oder setTargetAtTime().
Autoplay: Browser starten einen AudioContext oft im Zustand suspended. Rufe ctx.resume() nach einer Nutzeraktion auf.
Kompatibilität: Wird in allen aktuellen Browsern unterstützt. Ältere Safari-Versionen brauchten webkitAudioContext und kannten keine Konstruktor-Syntax (ctx.createBiquadFilter() verwenden).

Siehe auch

BiquadFilterNode BiquadFilterNode.frequency BiquadFilterNode.Q BiquadFilterNode.gain AudioParam OscillatorNode.detune VideoDecoder.state