AudioParam.linearRampToValueAtTime() — Methode · JavaScript-Referenz

Signatur

AudioParam.prototype.linearRampToValueAtTime(value, endTime)

Beschreibung

linearRampToValueAtTime() fügt der Automatisierungs-Zeitleiste eines AudioParam eine lineare Rampe hinzu. Die Rampe beginnt nicht beim Aufruf, sondern zum Zeitpunkt des vorherigen geplanten Ereignisses (z. B. eines setValueAtTime()). Von dort ändert sich der Wert gleichmäßig, bis er genau zum Zeitpunkt endTime den Wert value erreicht.

Typische Anwendungen sind Ein- und Ausblenden (Fade-in/Fade-out) über GainNode.gain, Frequenz-Sweeps bei einem OscillatorNode oder Filter-Fahrten über BiquadFilterNode.frequency. Damit lassen sich auch Knackgeräusche vermeiden, die bei abrupten Wertänderungen entstehen.

Alle Zeitangaben beziehen sich auf die Uhr des Audio-Kontexts (AudioContext.currentTime, in Sekunden). Damit die Rampe am gewünschten Punkt startet, setzt man vorher fast immer einen Ankerpunkt mit setValueAtTime(param.value, ctx.currentTime).

Für wahrnehmungsgerechtere Lautstärke- oder Frequenzverläufe eignet sich oft exponentialRampToValueAtTime() besser, da das Gehör logarithmisch empfindet.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number		Zielwert, den der Parameter zum Zeitpunkt `endTime` erreichen soll. Wird auf `minValue`/`maxValue` des Parameters begrenzt.
$endTime Pflicht	number		Zeitpunkt in Sekunden (bezogen auf `AudioContext.currentTime`), an dem die Rampe endet. Muss endlich und ≥ 0 sein.

Rückgabewert

Typ

AudioParam

Beschreibung

Eine Referenz auf denselben AudioParam, sodass Aufrufe verkettet werden können.

Beispiele

Fade-in und Fade-out eines Tons

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

const now = ctx.currentTime;
gain.gain
  .setValueAtTime(0, now)                 // Ankerpunkt: Start bei 0
  .linearRampToValueAtTime(0.8, now + 1)  // in 1 s einblenden
  .linearRampToValueAtTime(0, now + 3);   // bis 3 s ausblenden

osc.start(now);
osc.stop(now + 3);

Frequenz-Sweep (Sirene)

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

const t = ctx.currentTime;
osc.frequency.setValueAtTime(300, t);
for (let i = 0; i < 4; i++) {
  osc.frequency.linearRampToValueAtTime(900, t + i + 0.5);
  osc.frequency.linearRampToValueAtTime(300, t + i + 1);
}
osc.start(t);
osc.stop(t + 4);

Klickfreies Stummschalten per Button

const ctx = new AudioContext();
const gain = new GainNode(ctx);
gain.connect(ctx.destination);

const fadeTo = (target, duration = 0.05) => {
  const now = ctx.currentTime;
  gain.gain.cancelScheduledValues(now);
  gain.gain.setValueAtTime(gain.gain.value, now); // aktuellen Wert fixieren
  gain.gain.linearRampToValueAtTime(target, now + duration);
};

document.querySelector('#mute').addEventListener('click', async () => {
  await ctx.resume();
  fadeTo(gain.gain.value > 0 ? 0 : 1);
  console.log('Neuer Zielwert geplant');
});

Neuer Zielwert geplant

// Wichtig · Fallstricke

Startpunkt der Rampe: Die Rampe beginnt beim vorherigen Automatisierungsereignis. Gibt es keines, startet sie – je nach Implementierung – beim Zeitpunkt 0 oder springt abrupt. Deshalb immer zuerst setValueAtTime() als Anker setzen.
Direkte Zuweisung an .value während laufender Automatisierung wird ignoriert bzw. verhält sich wie setValueAtTime(value, currentTime); Mischen führt oft zu unerwartetem Verhalten.
Liegt endTime in der Vergangenheit, springt der Wert sofort auf value.
Ein nicht endlicher Wert für value oder endTime (z. B. NaN) wirft einen TypeError; ein negatives endTime einen RangeError.
Vor dem Umplanen laufende Ereignisse mit cancelScheduledValues() oder cancelAndHoldAtTime() entfernen.
Browser starten einen AudioContext wegen Autoplay-Richtlinien oft im Zustand suspended – erst nach Nutzerinteraktion ctx.resume() aufrufen. Die Methode wird von allen modernen Browsern unterstützt.

Siehe auch

AudioParam AudioParam.setValueAtTime() AudioParam.exponentialRampToValueAtTime() AudioParam.setTargetAtTime() AudioParam.cancelScheduledValues() GainNode