AudioParam.setValueCurveAtTime() — Methode · JavaScript-Referenz

Signatur

AudioParam.prototype.setValueCurveAtTime(values, startTime, duration)

Beschreibung

setValueCurveAtTime() lässt einen Audio-Parameter (z. B. gain, frequency oder detune) einer frei festgelegten Kurve folgen. Die übergebenen Werte werden gleichmäßig über den Zeitraum startTime bis startTime + duration verteilt. Zwischen zwei benachbarten Punkten wird linear interpoliert. Am Ende der Kurve behält der Parameter den letzten Wert.

Die Methode eignet sich für Hüllkurven und Verläufe, die sich mit linearRampToValueAtTime() oder exponentialRampToValueAtTime() nur umständlich nachbauen lassen: weiche Ein- und Ausblendungen (z. B. Sinus- oder Equal-Power-Fades), Vibrato-Muster, Tremolo, Filter-Sweeps mit eigener Form oder Kurven, die aus Messdaten berechnet wurden.

Für die Zeitangaben gilt die Uhr des Kontexts, also AudioContext.currentTime. Während der Kurve dürfen sich keine anderen Automationsereignisse mit ihr überschneiden, sonst wirft der Browser einen Fehler. Wenn du eine laufende Kurve abbrechen willst, verwende cancelScheduledValues() oder cancelAndHoldAtTime().

Parameter

Name	Typ	Default	Beschreibung
$values Pflicht	Float32Array \| number[]	—	Liste der Kurvenpunkte, mindestens 2 Werte. Die Werte werden gleichmäßig über `duration` verteilt. Nicht endliche Werte (`NaN`, `Infinity`) lösen einen `TypeError` aus.
$startTime Pflicht	number	—	Startzeit der Kurve in Sekunden, gemessen an `AudioContext.currentTime`. Negative Werte lösen einen `RangeError` aus. Liegt die Zeit in der Vergangenheit, beginnt die Kurve sofort.
$duration Pflicht	number	—	Dauer der Kurve in Sekunden. Der Wert muss größer als 0 sein, sonst wird ein `RangeError` ausgelöst.

Rückgabewert

Typ

AudioParam

Beschreibung

Eine Referenz auf denselben AudioParam. Dadurch lassen sich mehrere Aufrufe verketten (in älteren Implementierungen war der Rückgabewert undefined).

Beispiele

Weiches Einblenden mit Sinuskurve

const ctx = new AudioContext();
const osc = ctx.createOscillator();
const gain = ctx.createGain();
osc.connect(gain).connect(ctx.destination);

// Sinusförmige Einblend-Kurve von 0 bis 1 mit 64 Stützpunkten
const steps = 64;
const fadeIn = new Float32Array(steps);
for (let i = 0; i < steps; i++) {
  fadeIn[i] = Math.sin((i / (steps - 1)) * Math.PI / 2);
}

const now = ctx.currentTime;
gain.gain.setValueAtTime(0, now);
gain.gain.setValueCurveAtTime(fadeIn, now, 2); // 2 Sekunden einblenden

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

Eigene Hüllkurve für einen Ton per Knopfdruck

const ctx = new AudioContext();

const playPluck = () => {
  const osc = ctx.createOscillator();
  const gain = ctx.createGain();
  osc.type = 'triangle';
  osc.frequency.value = 440;
  osc.connect(gain).connect(ctx.destination);

  // Schneller Anschlag, danach langsames Abklingen
  const envelope = [0, 1, 0.6, 0.35, 0.2, 0.1, 0.04, 0];
  const t = ctx.currentTime;
  gain.gain.setValueCurveAtTime(envelope, t, 0.8);

  osc.start(t);
  osc.stop(t + 0.8);
};

document.querySelector('#play').addEventListener('click', async () => {
  if (ctx.state === 'suspended') await ctx.resume();
  playPluck();
});

Vibrato durch Frequenzkurve

const ctx = new AudioContext();
const osc = ctx.createOscillator();
osc.connect(ctx.destination);

// Frequenz schwankt 6-mal um 440 Hz (±10 Hz)
const points = 200;
const curve = Float32Array.from({ length: points }, (_, i) =>
  440 + 10 * Math.sin((i / (points - 1)) * 6 * 2 * Math.PI)
);

const t = ctx.currentTime;
osc.frequency.setValueCurveAtTime(curve, t, 1.5);
osc.start(t);
osc.stop(t + 1.5);
console.log(curve.length, curve[0]);

200 440

// Wichtig · Fallstricke

Überschneidungen sind verboten: Plant ein anderes Automationsereignis (z. B. setValueAtTime() oder linearRampToValueAtTime()) in den Zeitraum [startTime, startTime + duration) hinein, wird ein NotSupportedError ausgelöst. Das gilt auch umgekehrt, wenn die Kurve ein schon geplantes Ereignis überlappt.
Werte ändern sich nicht nachträglich: Der Browser kopiert das Array beim Aufruf intern. Wenn du das Array danach veränderst, wirkt sich das nicht auf die Kurve aus.
Werte unter 2 und ungültige Zeiten: Weniger als 2 Werte führen zu einem InvalidStateError. Ein negativer startTime oder ein duration ≤ 0 führt zu einem RangeError.
Interpolation: Laut aktueller Spezifikation wird zwischen den Punkten linear interpoliert. Ältere Browser-Versionen nutzten teils Stufen ohne Interpolation. Wenige Stützpunkte können deshalb hörbar eckig klingen, nimm lieber 32–256 Werte.
Klicken bei gain: Beginnt die Kurve mit einem anderen Wert als dem aktuellen, springt der Parameter sofort. Das kann ein Knacken erzeugen.
Autoplay-Regeln: Browser starten einen AudioContext oft im Zustand suspended. Erst eine Nutzeraktion mit ctx.resume() macht Ton hörbar.
Kompatibilität: Die Methode wird in allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Normale Arrays (number[]) statt Float32Array akzeptieren nur neuere Versionen. Für ältere Safari-Versionen ist Float32Array die sichere Wahl.

Siehe auch

AudioParam AudioParam.setValueAtTime() AudioParam.linearRampToValueAtTime() AudioParam.exponentialRampToValueAtTime() AudioParam.setTargetAtTime() AudioParam.cancelScheduledValues() AudioParam.cancelAndHoldAtTime() BaseAudioContext.currentTime