AudioParam.setValueAtTime() — Methode · JavaScript-Referenz

Signatur

AudioParam.prototype.setValueAtTime(value, startTime)

Beschreibung

setValueAtTime() trägt ein Ereignis in die Automatisierungs-Zeitleiste eines AudioParam ein. Zum Zeitpunkt startTime springt der Parameter ohne Übergang auf value. Die Zeit gilt auf der Uhr des Audio-Kontexts (AudioContext.currentTime, in Sekunden). Deshalb wird die Änderung sample-genau im Audio-Thread ausgeführt, unabhängig von Timern im Haupt-Thread wie setTimeout.

Typische Einsatzfälle sind Sequencer, Metronome, ein Gate an einem GainNode oder Frequenzsprünge an einem OscillatorNode. Sehr wichtig ist die Methode auch als Ankerpunkt für Rampen: linearRampToValueAtTime() und exponentialRampToValueAtTime() beginnen beim vorherigen Ereignis der Zeitleiste. Ohne ein vorangehendes setValueAtTime() ist oft nicht klar, wann und bei welchem Wert eine Rampe startet.

Liegt startTime in der Vergangenheit, also vor currentTime, wird die Änderung sofort ausgeführt. Die Methode gibt den AudioParam selbst zurück. Aufrufe lassen sich daher verketten.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number		Neuer Wert des Parameters. Er wird auf den Bereich `minValue` bis `maxValue` begrenzt, zum Beispiel beim Frequenzbereich eines Oszillators.
$startTime Pflicht	number		Zeitpunkt in Sekunden auf der Zeitachse von `AudioContext.currentTime`, zu dem der Wert gesetzt wird. Muss endlich und ≥ 0 sein.

Rückgabewert

Typ

AudioParam

Beschreibung

Eine Referenz auf denselben AudioParam. Damit sind verkettete Aufrufe möglich.

Beispiele

Lautstärke nach 2 Sekunden auf null schalten

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

// Sofort volle Lautstärke, nach 2 s stumm
gain.gain.setValueAtTime(1, ctx.currentTime);
gain.gain.setValueAtTime(0, ctx.currentTime + 2);

osc.start();
osc.stop(ctx.currentTime + 2.5);

Einfache Tonfolge (Melodie) planen

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

const noten = [261.63, 293.66, 329.63, 349.23, 392.0]; // C D E F G
const dauer = 0.3;
const t0 = ctx.currentTime + 0.05;

noten.forEach((freq, i) => {
  osc.frequency.setValueAtTime(freq, t0 + i * dauer);
});

osc.start(t0);
osc.stop(t0 + noten.length * dauer);

Ankerpunkt für eine Fade-out-Rampe

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

const fadeOut = (param, dauer = 1) => {
  const jetzt = ctx.currentTime;
  param.cancelScheduledValues(jetzt);
  // aktuellen Wert festhalten, damit die Rampe dort beginnt
  param.setValueAtTime(param.value, jetzt)
       .linearRampToValueAtTime(0, jetzt + dauer);
};

document.querySelector('#stop')?.addEventListener('click', () => fadeOut(gain.gain, 0.5));

// Wichtig · Fallstricke

Knackgeräusche: Ein harter Sprung, etwa bei der Lautstärke von 1 auf 0, erzeugt hörbare Klicks. Für weiche Übergänge nutzt du besser setTargetAtTime() oder eine Rampe.
Rampen brauchen einen Anker: linearRampToValueAtTime() startet beim vorherigen Ereignis. Fehlt dieses, springt der Wert in manchen Browsern oder die Rampe beginnt bei Zeit 0.
Wird param.value direkt gesetzt, während Automatisierungs-Ereignisse aktiv sind, wird die Zuweisung ignoriert. Dieses Verhalten ist in der Spezifikation festgelegt. Nutze stattdessen setValueAtTime(v, ctx.currentTime).
Ist startTime negativ oder nicht endlich, wird ein RangeError bzw. TypeError ausgelöst.
Ein Ereignis mit gleichem Zeitpunkt und gleichem Typ ersetzt ein bereits geplantes Ereignis.
Ein AudioContext startet wegen der Autoplay-Richtlinien oft im Zustand suspended. Rufe ctx.resume() nach einer Nutzerinteraktion auf.
Die Methode wird von allen modernen Browsern unterstützt. Das alte Präfix webkitAudioContext ist nicht mehr nötig.

Siehe auch

AudioParam AudioParam.linearRampToValueAtTime() AudioParam.exponentialRampToValueAtTime() AudioParam.setTargetAtTime() AudioParam.cancelScheduledValues() BaseAudioContext.currentTime CSSUnparsedValue.entries()