AudioParam: Methode setTargetAtTime()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.

Die Methode setTargetAtTime() des AudioParam-Interfaces plant den Beginn einer allmählichen Änderung des AudioParam-Werts. Dies ist nützlich für Decay- oder Release-Teile von ADSR-Hüllkurven.

Syntax

js
setTargetAtTime(target, startTime, timeConstant)

Parameter

target

Der Wert, auf den der Parameter zum angegebenen Startzeitpunkt zugehen wird.

startTime

Die Zeit, zu der der exponentielle Übergang beginnt, im selben Zeitkoordinatensystem wie AudioContext.currentTime. Wenn es kleiner oder gleich AudioContext.currentTime ist, beginnt die Änderung sofort.

timeConstant

Der Zeitkonstantenwert in Sekunden für den exponentiellen Ansatz zum Zielwert. Je größer dieser Wert ist, desto langsamer erfolgt der Übergang.

Rückgabewert

Ein Verweis auf dieses AudioParam-Objekt. Einige ältere Browser-Implementierungen dieses Interfaces geben undefined zurück.

Beschreibung

Die Änderung beginnt zu der in startTime angegebenen Zeit und bewegt sich exponentiell in Richtung des Wertes, der durch den target-Parameter angegeben ist. Die Abklingrate, wie durch den timeConstant-Parameter definiert, ist exponentiell; daher wird der Wert target nie vollständig erreichen, aber nach jedem Zeitschritt der Länge timeConstant wird sich der Wert target um weitere 1 - e - 1 63.2 % 1 - e^{-1} \approx 63.2% angenähert haben. Für die vollständige Formel (die ein lineares kontinuierliches zeitsinvariantes System erster Ordnung verwendet), lesen Sie die Web Audio Spezifikation.

Wenn Sie unbedingt einen bestimmten Zielwert zu einem bestimmten Zeitpunkt erreichen müssen, können Sie AudioParam.exponentialRampToValueAtTime() verwenden. Aus mathematischen Gründen funktioniert diese Methode jedoch nicht, wenn der aktuelle Wert oder der Zielwert 0 ist.

Wahl einer guten timeConstant

Wie oben erwähnt, ändert sich der Wert exponentiell, wobei jede timeConstant Sie um weitere 63,2 % dem Zielwert näher bringt. Sie müssen sich keine Sorgen machen, den Zielwert zu erreichen; sobald Sie nahe genug dran sind, sind weitere Änderungen für das menschliche Gehör nicht mehr wahrnehmbar.

Je nach Anwendungsfall kann es bereits ausreichen, 95 % des Zielwerts zu erreichen; in diesem Fall könnten Sie timeConstant auf ein Drittel der gewünschten Dauer setzen.

Für weitere Details sehen Sie die folgende Tabelle an, wie sich der Wert von 0 % auf 100 % ändert, während die Zeit fortschreitet.

Zeit seit startTime Wert
0 * timeConstant 0%
0.5 * timeConstant 39,3%
1 * timeConstant 63,2%
2 * timeConstant 86,5%
3 * timeConstant 95,0%
4 * timeConstant 98,2%
5 * timeConstant 99,3%
n * timeConstant 1
1 - e - n 1 - e^{-n}

Beispiele

In diesem Beispiel haben wir eine Medienquelle mit zwei Steuerknöpfen (sehen Sie den webaudio-examples Repo für den Quellcode an oder sehen Sie sich das Beispiel live an.) Wenn diese Knöpfe gedrückt werden, wird setTargetAtTime() verwendet, um den Gain-Wert auf 1,0 hoch- und auf 0 runterzufahren, wobei der Effekt nach 1 Sekunde beginnt und die Länge des Effekts durch die Zeitkonstante gesteuert wird.

js
// create audio context
const audioCtx = new AudioContext();

// set basic variables for example
const myAudio = document.querySelector("audio");

const atTimePlus = document.querySelector(".at-time-plus");
const atTimeMinus = document.querySelector(".at-time-minus");

// Create a MediaElementAudioSourceNode
// Feed the HTMLMediaElement into it
const source = audioCtx.createMediaElementSource(myAudio);

// Create a gain node and set its gain value to 0.5
const gainNode = audioCtx.createGain();
gainNode.gain.value = 0.5;
let currGain = gainNode.gain.value;

// connect the AudioBufferSourceNode to the gainNode
// and the gainNode to the destination
source.connect(gainNode);
gainNode.connect(audioCtx.destination);

// set buttons to do something onclick
atTimePlus.onclick = () => {
  currGain = 1.0;
  gainNode.gain.setTargetAtTime(1.0, audioCtx.currentTime + 1, 0.5);
};

atTimeMinus.onclick = () => {
  currGain = 0;
  gainNode.gain.setTargetAtTime(0, audioCtx.currentTime + 1, 0.5);
};

Spezifikationen

Specification
Web Audio API
# dom-audioparam-settargetattime

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch