AudioParam: setTargetAtTime() 方法

Baseline 已廣泛支援

此特性已相當成熟,可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來,各瀏覽器均已提供此特性。

AudioParam 介面的 setTargetAtTime() 方法用於排程 AudioParam 值的漸變。這對於 ADSR 包絡的衰減或釋放部分非常有用。

語法

js
setTargetAtTime(target, startTime, timeConstant)

引數

目標

引數將在給定開始時間開始過渡到的值。

startTime

指數過渡將開始的時間,與 AudioContext.currentTime 處於同一時間座標系。如果它小於或等於 AudioContext.currentTime,則引數將立即開始更改。

timeConstant

目標值的指數逼近的時間常數值,單位為秒。該值越大,過渡越慢。

返回值

指向此 AudioParam 物件的引用。此介面的一些舊瀏覽器實現返回 undefined

描述

變化從 startTime 指定的時間開始,並呈指數趨勢向 target 引數給定的值移動。timeConstant 引數定義的衰減率是指數級的;因此,值永遠不會完全達到 target,但在每個長度為 timeConstant 的時間步長之後,該值將接近 target1-e-163.2%1 - e^{-1} \approx 63.2%。有關完整公式(使用一階線性連續時間不變系統)的資訊,請參閱 Web Audio 規範

如果你絕對需要在特定時間達到目標值,可以使用 AudioParam.exponentialRampToValueAtTime()。但是,出於數學原因,噹噹前值或目標值為 0 時,該方法不起作用。

選擇合適的 timeConstant

如上所述,值呈指數變化,每個 timeConstant 使你更接近目標值 63.2%。你不必擔心達到目標值;一旦足夠接近,任何進一步的變化對人耳來說都將是無法察覺的。

根據你的用例,接近目標值 95% 可能已經足夠;在這種情況下,你可以將 timeConstant 設定為所需持續時間的三分之一。

更多詳情,請參閱下表,瞭解值如何隨著時間的推移從 0% 變為 100%。

startTime 以來的時間
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-n1 - e^{-n}

示例

在此示例中,我們有一個帶有兩個控制按鈕的媒體源(有關原始碼,請參閱 webaudio-examples 倉庫,或線上檢視示例。)當按下這些按鈕時,setTargetAtTime() 分別用於將增益值漸變到 1.0 和 0,效果在 1 秒後開始,效果的持續時間由 timeConstant 控制。

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);
};

規範

規範
Web Audio API
# dom-audioparam-settargetattime

瀏覽器相容性

另見