# AudioParam.setTargetAtTime()

The `setTargetAtTime()` method of the `AudioParam` interface schedules the start of a gradual change to the `AudioParam` value. This is useful for decay or release portions of ADSR envelopes.

## Syntax

``````setTargetAtTime(target, startTime, timeConstant)
``````

### Parameters

`target`

The value the parameter will start to transition towards at the given start time.

`startTime`

The time that the exponential transition will begin, in the same time coordinate system as `AudioContext.currentTime`. If it is less than or equal to `AudioContext.currentTime`, the parameter will start changing immediately.

`timeConstant`

The time-constant value, given in seconds, of an exponential approach to the target value. The larger this value is, the slower the transition will be.

### Return value

A reference to this `AudioParam` object. Some older browser implementations of this interface return `undefined`.

## Description

The change starts at the time specified in `startTime` and exponentially moves towards the value given by the `target` parameter. The decay rate as defined by the `timeConstant` parameter is exponential; therefore the value will never reach `target` completely, but after each timestep of length `timeConstant`, the value will have approached `target` by another $1 - e^\left\{-1\right\} \approx 63.2%$. For the complete formula (which uses a first-order linear continuous time-invariant system), check the Web Audio specification.

If you absolutely need to reach the target value by a specific time, you can use `AudioParam.exponentialRampToValueAtTime()`. However, for mathematical reasons, that method does not work if the current value or the target value is `0`.

### Choosing a good `timeConstant`

As mentioned above, the value changes exponentially, with each `timeConstant` bringing you another 63.2% toward the target value. You don't have to worry about reaching the target value; once you are close enough, any further changes will be imperceptible to a human listener.

Depending on your use case, getting 95% toward the target value may already be enough; in that case, you could set `timeConstant` to one third of the desired duration.

For more details, check the following table on how the value changes from 0% to 100% as the time progresses.

$1 - e^\left\{-n\right\}$

## Examples

In this example, we have a media source with two control buttons (see the webaudio-examples repo for the source code, or view the example live.) When these buttons are pressed, `setTargetAtTime()` is used to fade the gain value up to 1.0, and down to 0, respectively, with the effect starting after 1 second, and the length of time the effect lasts being controlled by the timeConstant.

``````// 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 it's 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);
};
``````

## Specifications

Specification
Web Audio API
# dom-audioparam-settargetattime

## Browser compatibility

BCD tables only load in the browser