AudioParam
==========

The Web Audio API's `AudioParam` interface represents an audio-related parameter, usually a parameter of an `AudioNode` (such as `GainNode.gain`).

An `AudioParam` can be set to a specific value or a change in value, and can be scheduled to happen at a specific time and following a specific pattern.

Each `AudioParam` has a list of events, initially empty, that define when and how values change. When this list is not empty, changes using the `AudioParam.value` attributes are ignored. This list of events allows us to schedule changes that have to happen at very precise times, using arbitrary timeline-based automation curves. The time used is the one defined in `AudioContext.currentTime`.

AudioParam types
----------------

There are two `AudioParam` kinds: *a-rate* and *k-rate* parameters. Each `AudioNode` defines which of its parameters are *a-rate* or *k-rate* in the spec.

### a-rate

An *a-rate* `AudioParam` takes the current audio parameter value for each sample frame of the audio signal.

### k-rate

A *k-rate* `AudioParam` uses the same initial audio parameter value for the whole block processed; that is, 128 sample frames. In other words, the same value applies to every frame in the audio as it's processed by the node.

Instance properties
-------------------

`AudioParam.defaultValue` Read only 

Represents the initial value of the attribute as defined by the specific `AudioNode` creating the `AudioParam`.

`AudioParam.maxValue` Read only 

Represents the maximum possible value for the parameter's nominal (effective) range.

`AudioParam.minValue` Read only 

Represents the minimum possible value for the parameter's nominal (effective) range.

`AudioParam.value`

Represents the parameter's current value as of the current time; initially set to the value of `defaultValue`.

Instance methods
----------------

`AudioParam.setValueAtTime()`

Schedules an instant change to the value of the `AudioParam` at a precise time, as measured against `AudioContext.currentTime`. The new value is given by the `value` parameter.

`AudioParam.linearRampToValueAtTime()`

Schedules a gradual linear change in the value of the `AudioParam`. The change starts at the time specified for the *previous* event, follows a linear ramp to the new value given in the `value` parameter, and reaches the new value at the time given in the `endTime` parameter.

`AudioParam.exponentialRampToValueAtTime()`

Schedules a gradual exponential change in the value of the `AudioParam`. The change starts at the time specified for the *previous* event, follows an exponential ramp to the new value given in the `value` parameter, and reaches the new value at the time given in the `endTime` parameter.

`AudioParam.setTargetAtTime()`

Schedules the start of a change to the value of the `AudioParam`. The change starts at the time specified in `startTime` and exponentially moves towards the value given by the `target` parameter. The exponential decay rate is defined by the `timeConstant` parameter, which is a time measured in seconds.

`AudioParam.setValueCurveAtTime()`

Schedules the values of the `AudioParam` to follow a set of values, defined by an array of floating-point numbers scaled to fit into the given interval, starting at a given start time and spanning a given duration of time.

`AudioParam.cancelScheduledValues()`

Cancels all scheduled future changes to the `AudioParam`.

`AudioParam.cancelAndHoldAtTime()`

Cancels all scheduled future changes to the `AudioParam` but holds its value at a given time until further changes are made using other methods.

Examples
--------

First, a basic example showing a `GainNode` having its `gain` value set. `gain` is an example of an *a-rate* `AudioParam`, as the value can potentially be set differently for each sample frame of the audio.


```js
const audioCtx = new AudioContext();

const gainNode = audioCtx.createGain();
gainNode.gain.value = 0;
```


Next, an example showing a `DynamicsCompressorNode` having some param values manipulated. These are examples of *k-rate* `AudioParam` types, as the values are set for the entire audio block at once.


```js
const compressor = audioCtx.createDynamicsCompressor();
compressor.threshold.setValueAtTime(-50, audioCtx.currentTime);
compressor.knee.setValueAtTime(40, audioCtx.currentTime);
compressor.ratio.setValueAtTime(12, audioCtx.currentTime);
compressor.attack.setValueAtTime(0, audioCtx.currentTime);
compressor.release.setValueAtTime(0.25, audioCtx.currentTime);
```

Specifications
--------------

| Specification |
| --- |
| Web Audio API # AudioParam |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using the Web Audio API