1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
---
title: AudioParam
slug: Web/API/AudioParam
tags:
- API
- Audio
- AudioParam
- Interface
- Reference
- Web Audio API
translation_of: Web/API/AudioParam
---
<div>{{APIRef("Web Audio API")}}</div>
<p><span class="seoSummary">The Web Audio API's <code>AudioParam</code> interface represents an audio-related parameter, usually a parameter of an {{domxref("AudioNode")}} (such as {{ domxref("GainNode.gain") }}).</span> An <code>AudioParam</code> 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.</p>
<p>There are two kinds of <code>AudioParam</code>, <em>a-rate</em> and <em>k-rate</em> parameters:</p>
<ul>
<li id="a-rate">An <em>a-rate</em> <code>AudioParam</code> takes the current audio parameter value for each <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API#Audio_buffers.3A_frames.2C_samples_and_channels">sample frame</a> of the audio signal.</li>
<li id="k-rate">A <em>k-rate</em> <code>AudioParam</code> uses the same initial audio parameter value for the whole block processed, that is 128 sample frames.</li>
</ul>
<p>Each {{domxref("AudioNode")}} defines which of its parameters are <em>a-rate</em> or <em>k-rate</em> in the spec.</p>
<p>Each <code>AudioParam</code> has a list of events, initially empty, that define when and how values change. When this list is not empty, changes using the <code>AudioParam.value</code> attributes are ignored. This list of events allows us to schedule changes that have to happen at very precise times, using arbitrary timelime-based automation curves. The time used is the one defined in {{domxref("AudioContext.currentTime")}}.</p>
<h2 id="Properties">Properties</h2>
<p><code>AudioParam</code><em> Inherits properties from its parent, </em><code>AudioNode</code>.</p>
<dl>
<dt>{{domxref("AudioParam.defaultValue")}} {{readonlyInline}}</dt>
<dd>Represents the initial volume of the attribute as defined by the specific {{domxref("AudioNode")}} creating the <code>AudioParam</code>.</dd>
<dt>{{domxref("AudioParam.maxValue")}} {{readonlyInline}}</dt>
<dd>Represents the maximum possible value for the parameter's nominal (effective) range. </dd>
<dt>{{domxref("AudioParam.minValue")}} {{readonlyinline}}</dt>
<dd>Represents the minimum possible value for the parameter's nominal (effective) range. </dd>
<dt>{{domxref("AudioParam.value")}}</dt>
<dd>Represents the parameter's current volume as a floating point value; initially set to the value of <code>AudioParam.defaultValue</code>. Though it can be set, any modifications happening while there are automation events scheduled — that is events scheduled using the methods of the <code>AudioParam</code> — are ignored, without raising any exception.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<p>AudioParam<em> Inherits methods from its parent, </em><code>AudioNode</code>.</p>
<dl>
<dt>{{domxref("AudioParam.setValueAtTime()")}}</dt>
<dd>Schedules an instant change to the value of the <code>AudioParam</code> at a precise time, as measured against {{domxref("AudioContext.currentTime")}}. The new value is given by the <code>value</code> parameter.</dd>
<dt>{{domxref("AudioParam.linearRampToValueAtTime()")}}</dt>
<dd>Schedules a gradual linear change in the value of the <code>AudioParam</code>. The change starts at the time specified for the <em>previous</em> event, follows a linear ramp to the new value given in the <code>value</code> parameter, and reaches the new value at the time given in the <code>endTime</code> parameter.</dd>
<dt>{{domxref("AudioParam.exponentialRampToValueAtTime()")}}</dt>
<dd>Schedules a gradual exponential change in the value of the <code>AudioParam</code>. The change starts at the time specified for the <em>previous</em> event, follows an exponential ramp to the new value given in the <code>value</code> parameter, and reaches the new value at the time given in the <code>endTime</code> parameter.</dd>
<dt>{{domxref("AudioParam.setTargetAtTime()")}}</dt>
<dd>Schedules the start of a change to the value of the <code>AudioParam</code>. The change starts at the time specified in <code>startTime</code> and exponentially moves towards the value given by the <code>target</code> parameter. The exponential decay rate is defined by the <code>timeConstant</code> parameter, which is a time measured in seconds.</dd>
<dt>{{domxref("AudioParam.setValueCurveAtTime()")}}</dt>
<dd>Schedules the values of the <code>AudioParam</code> 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.</dd>
<dt>{{domxref("AudioParam.cancelScheduledValues()")}}</dt>
<dd>Cancels all scheduled future changes to the <code>AudioParam</code>.</dd>
<dt>{{domxref("AudioParam.cancelAndHoldAtTime()")}}</dt>
<dd>Cancels all scheduled future changes to the <code>AudioParam</code> but holds its value at a given time until further changes are made using other methods.</dd>
</dl>
<h2 id="Examples">Examples</h2>
<p>First, a basic example showing a {{domxref("GainNode")}} having its <code>gain</code> value set. <code>gain</code> is an example of an a-rate AudioParam, as the value can potentially be set differently for each sample frame of the audio.</p>
<pre class="brush: js;highlight[5]">var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var gainNode = audioCtx.createGain();
gainNode.gain.value = 0;</pre>
<p>Next, an example showing a {{ domxref("BiquadFilterNode") }} having some values set. These are examples of k-rate AudioParam's, as the values are set for the entire audio block at once.</p>
<pre class="brush: js;highlight[6,7,8]">var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var biquadFilter = audioCtx.createBiquadFilter();
biquadFilter.type = "lowshelf";
biquadFilter.frequency.value = 1000;
biquadFilter.gain.value = 25;</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('Web Audio API', '#AudioParam', 'AudioParam')}}</td>
<td>{{Spec2('Web Audio API')}}</td>
<td> </td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
<p>{{Compat("api.AudioParam")}}</p>
</div>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web_Audio_API/Using_Web_Audio_API">Using the Web Audio API</a></li>
</ul>
|
