AudioParam.cancelScheduledValues() — Methode · JavaScript-Referenz

Signatur

AudioParam.prototype.cancelScheduledValues(cancelTime)

Beschreibung

cancelScheduledValues() löscht aus der Zeitleiste eines AudioParam alle Ereignisse, die zum Zeitpunkt cancelTime oder danach beginnen. Dazu gehören Aufrufe von setValueAtTime(), linearRampToValueAtTime(), exponentialRampToValueAtTime(), setTargetAtTime() und setValueCurveAtTime(). Die Zeitangabe bezieht sich auf die Uhr des Audiokontexts (AudioContext.currentTime), in Sekunden.

Gebraucht wird die Methode vor allem dann, wenn eine geplante Automation durch Benutzereingaben überholt wird, etwa wenn eine Taste eines Synthesizers losgelassen wird, bevor die Attack-Hüllkurve fertig ist, oder wenn ein Fade-out abgebrochen und durch einen neuen ersetzt werden soll. Typisch ist die Kombination aus cancelScheduledValues(now), danach setValueAtTime(param.value, now) und anschließend einer neuen Rampe.

Wichtig: Die Methode hält den Wert nicht an der aktuellen Position fest. Wird eine laufende Rampe gelöscht, kann der Parameter auf den Wert des letzten verbliebenen Ereignisses zurückspringen, was hörbar knackt. Wenn der aktuelle Wert erhalten bleiben soll, ist cancelAndHoldAtTime() meist die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$cancelTime Pflicht	number		Zeitpunkt in Sekunden (bezogen auf `AudioContext.currentTime`), ab dem alle geplanten Ereignisse entfernt werden. Er muss endlich und nicht negativ sein.

Rückgabewert

Typ

AudioParam

Beschreibung

Gibt eine Referenz auf denselben AudioParam zurück. Dadurch lassen sich Aufrufe verketten (in älteren Firefox-Versionen: undefined).

Beispiele

Geplante Lautstärke-Automation komplett verwerfen

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

const now = ctx.currentTime;
// Einblenden über 2 Sekunden, danach ausblenden
gain.gain.setValueAtTime(0, now);
gain.gain.linearRampToValueAtTime(0.8, now + 2);
gain.gain.linearRampToValueAtTime(0, now + 4);

// Nach 1 Sekunde alles verwerfen, was noch nicht begonnen hat
setTimeout(() => {
  gain.gain.cancelScheduledValues(ctx.currentTime);
  console.log('Automation verworfen, Wert:', gain.gain.value.toFixed(2));
}, 1000);

Automation verworfen, Wert: 0.00

Synth-Hüllkurve beim Loslassen ohne Knacksen abbrechen

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sawtooth', frequency: 220 });
const amp = new GainNode(ctx, { gain: 0 });
osc.connect(amp).connect(ctx.destination);
osc.start();

const noteOn = () => {
  const t = ctx.currentTime;
  amp.gain.cancelScheduledValues(t);
  amp.gain.setValueAtTime(amp.gain.value, t);
  amp.gain.linearRampToValueAtTime(1, t + 0.5); // langsamer Attack
};

const noteOff = () => {
  const t = ctx.currentTime;
  const current = amp.gain.value;         // aktuellen Wert merken
  amp.gain.cancelScheduledValues(t);       // laufenden Attack verwerfen
  amp.gain.setValueAtTime(current, t);     // Wert festhalten -> kein Sprung
  amp.gain.setTargetAtTime(0, t, 0.1);     // weiches Release
};

document.querySelector('#taste').addEventListener('pointerdown', noteOn);
document.querySelector('#taste').addEventListener('pointerup', noteOff);

Nur Ereignisse ab einem späteren Zeitpunkt löschen (verkettet)

const ctx = new AudioContext();
const filter = new BiquadFilterNode(ctx, { type: 'lowpass', frequency: 500 });
const t = ctx.currentTime;

filter.frequency
  .setValueAtTime(500, t)
  .exponentialRampToValueAtTime(5000, t + 1)
  .exponentialRampToValueAtTime(200, t + 3)
  // Alles ab t + 2 entfernen: die Rampe nach 5000 Hz bleibt erhalten,
  // die Rampe nach 200 Hz (Endzeit t + 3) wird gelöscht
  .cancelScheduledValues(t + 2);

console.log('Rampe ab t+2 entfernt');

Rampe ab t+2 entfernt

// Wichtig · Fallstricke

Wertsprünge: Wird eine laufende Rampe gelöscht, fällt der Parameter auf den Wert des letzten verbliebenen Ereignisses zurück. Das kann hörbar knacken. Um das zu vermeiden, danach setValueAtTime(param.value, now) aufrufen oder gleich cancelAndHoldAtTime() verwenden.
Rampen zählen ab ihrer Endzeit: Bei linearRampToValueAtTime() und exponentialRampToValueAtTime() gilt der angegebene Endzeitpunkt als Ereigniszeit. Eine Rampe, die vor cancelTime beginnt, aber danach endet, wird daher vollständig entfernt.
Fehler: Ist cancelTime negativ oder nicht endlich (NaN, Infinity), wird ein RangeError ausgelöst.
param.value gibt den zuletzt berechneten Wert zurück. Er kann dem tatsächlichen Audiothread um bis zu einen Renderblock (128 Samples) hinterherhinken.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Vor dem ersten Ton muss der AudioContext durch eine Benutzeraktion gestartet werden (Autoplay-Richtlinie, ctx.resume()).

Siehe auch

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