AudioParam.setTargetAtTime() — Methode · JavaScript-Referenz

Signatur

AudioParam.prototype.setTargetAtTime(target, startTime, timeConstant)

Beschreibung

setTargetAtTime() startet zu einem bestimmten Zeitpunkt eine exponentielle Annäherung des aktuellen Parameterwerts an einen Zielwert. Der Verlauf folgt der Formel v(t) = V1 + (V0 − V1) · e^(−(t − T0) / τ). Dabei ist V0 der Wert zum Startzeitpunkt, V1 das Ziel und τ die Zeitkonstante. Anders als bei exponentialRampToValueAtTime() gibt es keinen Endzeitpunkt: Der Zielwert wird rechnerisch nie ganz erreicht, der Parameter nähert sich ihm nur immer weiter an.

Die Methode eignet sich gut für die Release- und Decay-Phase von Hüllkurven (ADSR), für weiche Lautstärkeänderungen ohne Knacken und für Parameter, die „natürlich“ nachlaufen sollen, etwa Filterfrequenzen. Weil der Startwert der Wert ist, den der Parameter gerade hat, lässt sie sich auch mitten in eine laufende Automation einsetzen, ohne dass der Wert springt.

Als Faustregel gilt: Nach 1·τ sind etwa 63,2 % der Strecke zum Ziel geschafft, nach 3·τ etwa 95 % und nach 5·τ etwa 99,3 %. Soll die Änderung also nach ungefähr d Sekunden „fertig“ wirken, wählt man timeConstant ≈ d / 3 bis d / 5.

Parameter

Name	Typ	Beschreibung
$target Pflicht	number	Zielwert, dem sich der Parameter annähern soll. Muss im Wertebereich des Parameters liegen (`minValue` bis `maxValue`).
$startTime Pflicht	number	Startzeitpunkt der Annäherung in Sekunden, bezogen auf die Zeitachse von `AudioContext.currentTime`. Liegt der Wert in der Vergangenheit, beginnt die Änderung sofort. Negative Werte lösen einen `RangeError` aus.
$timeConstant Pflicht	number	Zeitkonstante τ in Sekunden, also die Zeit, nach der etwa 63,2 % der Strecke zum Ziel zurückgelegt sind. Muss ≥ 0 sein. Bei `0` springt der Wert sofort auf das Ziel.

Rückgabewert

Typ

AudioParam

Beschreibung

Eine Referenz auf dasselbe AudioParam-Objekt, sodass sich mehrere Aufrufe verketten lassen.

Beispiele

Weiches Ausblenden ohne Knacken

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const gain = new GainNode(ctx, { gain: 0.8 });
osc.connect(gain).connect(ctx.destination);
osc.start();

// Nach 1 Sekunde ausblenden, nach ca. 0,5 s praktisch still (5 · 0,1 s)
const t = ctx.currentTime + 1;
gain.gain.setTargetAtTime(0, t, 0.1);
osc.stop(t + 0.6);

ADSR-Hüllkurve für einen Synth-Ton

const ctx = new AudioContext();

const playNote = (freq, duration = 0.5) => {
  const now = ctx.currentTime;
  const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: freq });
  const amp = new GainNode(ctx, { gain: 0 });
  osc.connect(amp).connect(ctx.destination);

  amp.gain
    .setValueAtTime(0, now)
    .linearRampToValueAtTime(1, now + 0.01)      // Attack
    .setTargetAtTime(0.6, now + 0.01, 0.05)      // Decay auf Sustain
    .setTargetAtTime(0, now + duration, 0.15);   // Release

  osc.start(now);
  osc.stop(now + duration + 1); // 1 s ≈ 6,7 τ Nachlauf
};

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  playNote(220);
});

Filter per Schieberegler ohne Zipper-Rauschen steuern

const ctx = new AudioContext();
const filter = new BiquadFilterNode(ctx, { type: 'lowpass', frequency: 1000 });
// ... Quelle -> filter -> ctx.destination

const slider = document.querySelector('#cutoff');
slider.addEventListener('input', (e) => {
  const value = Number(e.target.value);
  // Laufende Automation abbrechen und weich zum neuen Wert gleiten
  filter.frequency.cancelScheduledValues(ctx.currentTime);
  filter.frequency.setTargetAtTime(value, ctx.currentTime, 0.02);
});

// Wichtig · Fallstricke

Der Zielwert wird nie genau erreicht. Wenn danach ein exakter Wert gebraucht wird, plant man ihn nach etwa 5·τ zusätzlich mit setValueAtTime() ein.
Bei Ziel 0 ist setTargetAtTime() die richtige Wahl. exponentialRampToValueAtTime() akzeptiert 0 nicht als Zielwert.
Das direkte Setzen von param.value wirkt wie ein setValueAtTime() zum aktuellen Zeitpunkt. Mischt man es mit geplanten Ereignissen, gibt es leicht unerwartete Sprünge. Für interaktive Steuerung besser cancelScheduledValues() (oder cancelAndHoldAtTime()) mit setTargetAtTime() kombinieren.
Folgt auf ein setTargetAtTime-Ereignis eine Rampe (linearRamp…/exponentialRamp…), startet diese beim Wert, den die Annäherung zu diesem Zeitpunkt erreicht hat.
Ein negativer startTime oder timeConstant löst einen RangeError aus. Nicht endliche Werte (NaN, Infinity) lösen einen TypeError aus.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Ein AudioContext startet meist erst nach einer Nutzerinteraktion (Autoplay-Richtlinie). Deshalb vorher ctx.resume() aufrufen.

Siehe auch

AudioParam AudioParam.setValueAtTime() AudioParam.linearRampToValueAtTime() AudioParam.exponentialRampToValueAtTime() AudioParam.cancelScheduledValues() AudioParam.cancelAndHoldAtTime() GainNode