Revision 649251 of AudioParam

<p>{{APIRef()}}</p>
<div class="summary">
 <p>The <code>AudioParam</code> interface represents an audio-related parameter, usually a parameter of an {{domxref("AudioNode")}} (such as {{ domxref("GainNode.gain") }}). 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>
</div>
<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.value")}}</dt>
 <dd>
  Represents the parameter's current 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>
 <dt>
  {{domxref("AudioParam.defaultValue")}} {{readonlyInline}}</dt>
 <dd>
  Represents the initial value of the attributes as defined by the specific {{domxref("AudioNode")}} creating the <code>AudioParam</code>.</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 in 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.</dd>
 <dt>
  {{domxref("AudioParam.setValueCurveAtTime()")}}</dt>
 <dd>
  Schedules the values of the <code>AudioParam</code> to follow a set of values, defined by the <code>values</code> {{domxref("Float32Array")}} scaled to fit into the given interval, starting at <code>startTime</code>, and having a specific <code>duration</code>.</dd>
 <dt>
  {{domxref("AudioParam.cancelScheduledValues()")}}</dt>
 <dd>
  Cancels all scheduled future changes to the <code>AudioParam</code>.</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', '#the-audioparam-interface', 'AudioParam')}}</td>
   <td>{{Spec2('Web Audio API')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
 {{CompatibilityTable}}</div>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Chrome</th>
    <th>Firefox (Gecko)</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari (WebKit)</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>14 {{property_prefix("webkit")}}</td>
    <td>23</td>
    <td>{{CompatNo}}</td>
    <td>15&nbsp;{{property_prefix("webkit")}}<br />
     22 (unprefixed)</td>
    <td>6 {{property_prefix("webkit")}}</td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Android</th>
    <th>Chrome</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>Firefox OS</th>
    <th>IE Phone</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{CompatNo}}</td>
    <td>28&nbsp;{{property_prefix("webkit")}}</td>
    <td>25</td>
    <td>1.2</td>
    <td>{{CompatNo}}</td>
    <td>{{CompatNo}}</td>
    <td>6&nbsp;{{property_prefix("webkit")}}</td>
   </tr>
  </tbody>
 </table>
</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>