Web Audio API

https://webaudio.github.io/web-audio-api
Admin
Web Audio API is a high-level JavaScript API for processing and synthesizing audio in web...
Tokens:233,030
Snippets:927
Trust Score:8.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### start(when)

Source: https://webaudio.github.io/web-audio-api/

Schedules a sound to start playback at the specified time. The method queues a control message to start the node and may resume the AudioContext if conditions are met. Throws a RangeError if the 'when' parameter is negative.

```APIDOC
## start(when)

### Description
Schedules a sound to start playback at the specified time. The method queues a control message to start the node and may resume the AudioContext if conditions are met. Throws a RangeError if the 'when' parameter is negative.

### Method
start

### Parameters
#### Parameters
- **when** (double) - Optional - The time (in seconds) at which the sound should start playing. It is in the same time coordinate system as the AudioContext's currentTime attribute. If 0 or less than currentTime, the sound starts immediately. A RangeError is thrown if negative.

### Return Type
undefined

### Exceptions
- **RangeError** - Thrown if the 'when' parameter is negative.

### Steps
1. Check for any errors that must be thrown due to parameter constraints. If any exception is thrown, abort those steps.
2. Set the internal slot [[source started]] on this AudioScheduledSourceNode to true.
3. Queue a control message to start the AudioScheduledSourceNode, including the parameter values in the message.
4. Send a control message to the associated AudioContext to start running its rendering thread only when all the following conditions are met:
   - The context's [[control thread state]] is "suspended".
   - The context is allowed to start.
   - [[suspended by user]] flag is false.
```

--------------------------------

### AudioParam Automation Example

Source: https://webaudio.github.io/web-audio-api/

An example demonstrating how to automate an AudioParam using various methods.

```APIDOC
## AudioParam Automation Example

### Description
An example of parameter automation using the AudioParam methods.

### Code
```javascript
const curveLength = 44100;
const curve = new Float32Array(curveLength);
for (const i = 0; i < curveLength; ++i)
    curve[i] = Math.sin(Math.PI * i / curveLength);
const t0 = 0;
const t1 = 0.1;
const t2 = 0.2;
const t3 = 0.3;
const t4 = 0.325;
const t5 = 0.5;
const t6 = 0.6;
const t7 = 0.7;
const t8 = 1.0;
const timeConstant = 0.1;
param.setValueAtTime(0.2, t0);
param.setValueAtTime(0.3, t1);
param.setValueAtTime(0.4, t2);
param.linearRampToValueAtTime(1, t3);
param.linearRampToValueAtTime(0.8, t4);
param.setTargetAtTime(.5, t4, timeConstant);
// Compute where the setTargetAtTime will be at time t5 so we can make
// the following exponential start at the right point so there's no
// jump discontinuity. From the spec, we have
// v(t) = 0.5 + (0.8 - 0.5)*exp(-(t-t4)/timeConstant)
// Thus v(t5) = 0.5 + (0.8 - 0.5)*exp(-(t5-t4)/timeConstant)
param.setValueAtTime(0.5 + (0.8 - 0.5)*Math.exp(-(t5 - t4)/timeConstant), t5);
param.exponentialRampToValueAtTime(0.75, t6);
param.exponentialRampToValueAtTime(0.05, t7);
param.setValueCurveAtTime(curve, t7, t8 - t7);
```
```

--------------------------------

### OfflineAudioContext.startRendering()

Source: https://webaudio.github.io/web-audio-api/

Starts rendering the audio. Returns a promise that resolves with the rendered AudioBuffer.

```APIDOC
## OfflineAudioContext.startRendering()

### Description
Starts rendering the audio. Returns a promise that resolves with the rendered AudioBuffer.

### Method
startRendering

### Parameters
- **chunkSize** (unsigned long?) - Optional - The chunk size for rendering. Default is null.

### Returns
- **Promise<AudioBuffer>** - A promise that resolves with the rendered audio buffer.

### Example
```js
const audioBuffer = await offlineContext.startRendering();
```
```

--------------------------------

### OfflineAudioContext.startRendering(chunkSize)

Source: https://webaudio.github.io/web-audio-api/

Starts rendering audio given the current connections and scheduled changes. The primary method of getting the rendered audio data is via its promise return value, but the instance will also fire a 'complete' event for legacy reasons.

```APIDOC
## OfflineAudioContext.startRendering(chunkSize)

### Description
Starts rendering audio given the current connections and scheduled changes. The primary method of getting the rendered audio data is via its promise return value, but the instance will also fire a 'complete' event for legacy reasons.

### Method
startRendering

### Parameters
#### Path Parameters
- **chunkSize** (optional) - The chunk size for rendering. (Exact type and requirements not specified in the source.)

### Response
Returns a Promise that resolves with the rendered audio data. Also fires a 'complete' event.
```

--------------------------------

### start(when, offset, duration)

Source: https://webaudio.github.io/web-audio-api/

Schedules a sound to playback at an exact time. Throws InvalidStateError if the source has already been started.

```APIDOC
## start(when, offset, duration)

### Description
Schedules a sound to playback at an exact time.

### Method
start

### Parameters
- **when** (double) - Optional - The time at which the sound should start playing.
- **offset** (double) - Optional - The offset into the buffer at which to start playback.
- **duration** (double) - Optional - The duration of the sound to play.

### Exceptions
- **InvalidStateError** - Thrown if the source has already been started.

### Steps
1. If the internal slot [[source started]] is true, throw an InvalidStateError.
2. Check for any errors due to parameter constraints.
3. Set the internal slot [[source started]] to true.
4. Queue a control message to start the AudioBufferSourceNode.
5. Acquire the contents of the buffer if set.
6. Send a control message to the associated AudioContext to start its rendering thread if conditions are met.
```

--------------------------------

### AudioParam Automation Example

Source: https://webaudio.github.io/web-audio-api/

Demonstrates parameter automation using various AudioParam methods. The example creates a sine curve and schedules value changes, ramps, and a target value over time. It includes a comment explaining how to compute the value at a specific time to avoid discontinuity.

```javascript
const curveLength = 44100;const curve = new Float32Array(curveLength);for (const i = 0; i < curveLength; ++i)    curve[i] = Math.sin(Math.PI * i / curveLength);const t0 = 0;const t1 = 0.1;const t2 = 0.2;const t3 = 0.3;const t4 = 0.325;const t5 = 0.5;const t6 = 0.6;const t7 = 0.7;const t8 = 1.0;const timeConstant = 0.1;param.setValueAtTime(0.2, t0);param.setValueAtTime(0.3, t1);param.setValueAtTime(0.4, t2);param.linearRampToValueAtTime(1, t3);param.linearRampToValueAtTime(0.8, t4);param.setTargetAtTime(.5, t4, timeConstant);// Compute where the setTargetAtTime will be at time t5 so we can make// the following exponential start at the right point so there's no// jump discontinuity. From the spec, we have// v(t) = 0.5 + (0.8 - 0.5)*exp(-(t-t4)/timeConstant)// Thus v(t5) = 0.5 + (0.8 - 0.5)*exp(-(t5-t4)/timeConstant)param.setValueAtTime(0.5 + (0.8 - 0.5)*Math.exp(-(t5 - t4)/timeConstant), t5);param.exponentialRampToValueAtTime(0.75, t6);param.exponentialRampToValueAtTime(0.05, t7);param.setValueCurveAtTime(curve, t7, t8 - t7);
```

--------------------------------

### AudioBufferSourceNode.start(when, offset, duration)

Source: https://webaudio.github.io/web-audio-api/

Starts the playback of the audio buffer. The when parameter specifies the start time in seconds, offset specifies the playhead position, and duration specifies the length of sound to play. Throws RangeError if any parameter is negative.

```APIDOC
## AudioBufferSourceNode.start(when, offset, duration)

### Description
Starts the playback of the audio buffer. The `when` parameter specifies the start time in seconds, `offset` specifies the playhead position, and `duration` specifies the length of sound to play. Throws `RangeError` if any parameter is negative.

### Method
start

### Parameters
#### Parameters
- **when** (double) - Optional - The time (in seconds) when the sound should start playing. If 0 or less than currentTime, playback starts immediately. Throws RangeError if negative.
- **offset** (double) - Optional - The playhead position where playback begins. If 0, playback starts from the beginning. Throws RangeError if negative. Clamped to [0, duration] when startTime is reached.
- **duration** (double) - Optional - The duration of sound to be played, in seconds of total buffer content, including loop iterations. Throws RangeError if negative.

### Return Type
undefined

### Exceptions
- **RangeError** - Thrown if `when`, `offset`, or `duration` is negative.
```

--------------------------------

### VU meter entry point in index.js

Source: https://webaudio.github.io/web-audio-api/

Entry point that loads the processor module, creates an AudioContext, connects an oscillator to the VUMeterNode, and starts the drawing loop.

```javascript
/* index.js: Main global scope, entry point */
import VUMeterNode from './vumeter-node.js';

const context = new AudioContext();
context.audioWorklet.addModule('vumeter-processor.js').then(() => {
    const oscillator = new OscillatorNode(context);
    const vuMeterNode = new VUMeterNode(context, 25);
    oscillator.connect(vuMeterNode);
    oscillator.start();

    function drawMeter () {
        vuMeterNode.draw();
        requestAnimationFrame(drawMeter);
    }

    drawMeter();
});
```

--------------------------------

### resume()

Source: https://webaudio.github.io/web-audio-api/

Resumes the progression of the OfflineAudioContext's rendering. It returns a promise that resolves when the rendering has started.

```APIDOC
## resume()

### Description
Resumes the progression of the OfflineAudioContext's rendering. It returns a promise that resolves when the rendering has started.

### Method
resume()

### Parameters
_No parameters._

### Return Type
`Promise<undefined>`

### Behavior
- Sets the `[[rendering started]]` slot to `false`.
- Sets the `[[control thread state]]` flag to `running`.
- Queues a control message to resume the OfflineAudioContext.
- Returns a promise.

When the control message is processed on the rendering thread:
- Sets the `[[rendering thread state]]` to `running`.
- Starts rendering the audio graph.
- On failure, rejects the promise.
- On success, resolves the promise and, if the state is not already `running`, sets the state to `running` and fires a `statechange` event.
```

--------------------------------

### OfflineAudioContext.startRendering()

Source: https://webaudio.github.io/web-audio-api/

Starts rendering the audio offline. Returns a promise that resolves with the rendered AudioBuffer. The method follows a specific algorithm that handles chunked rendering and error conditions.

```APIDOC
## OfflineAudioContext.startRendering()

### Description
Starts rendering the audio offline. Returns a promise that resolves with the rendered AudioBuffer. The method follows a specific algorithm that handles chunked rendering and error conditions.

### Method
startRendering

### Parameters
None

### Algorithm
1. If the relevant global object's associated Document is not fully active, return a promise rejected with InvalidStateError DOMException.
2. Let promise be a new promise.
3. If the control thread state on the OfflineAudioContext is closed, reject promise with InvalidStateError and abort.
4. If the OfflineAudioContext's length is not null and committed frames is greater than or equal to length, reject promise with InvalidStateError and abort.
5. Let bufferLength be a number initialized to the value of chunkSize.
   - If length is null:
     - If chunkSize is null, set bufferLength to render quantum size.
   - Otherwise, if length is not null:
     - If chunkSize is not null and committed frames + chunkSize is less than length, set bufferLength to chunkSize.
     - Otherwise, set bufferLength to length - committed frames.
6. If bufferLength is not a multiple of render quantum size, round it up to the next multiple.
7. Create a new AudioBuffer with number of channels and sample rate from the constructor's contextOptions, and length equal to bufferLength.
8. If an exception was thrown during the AudioBuffer constructor call, reject promise with this exception and return promise.
9. Set rendering started to true.
10. Set committed frames to the sum of committed frames and the buffer's length.
11. Append buffer to rendered buffers and begin offline rendering for buffer.

### Return Value
A Promise that resolves with an AudioBuffer containing the rendered audio.

### Exceptions
- InvalidStateError - Thrown if the document is not fully active, the context is closed, or the committed frames have reached the length.
```

--------------------------------

### AudioContext.resume()

Source: https://webaudio.github.io/web-audio-api/

Resumes the progression of the AudioContext's currentTime, starts rendering the audio graph, and resolves a promise when the context is running. The promise is rejected if resource acquisition fails.

```APIDOC
## AudioContext.resume()

### Description
Resumes the progression of the AudioContext's currentTime and starts rendering the audio graph. The promise resolves when the context is running.

### Method
resume()

### Parameters
_No parameters._

### Return Type
Promise<undefined>

### Algorithm
1. Let promise be the promise passed into this algorithm.
2. Attempt to acquire system resources.
3. Set the rendering thread state on the AudioContext to running.
4. Start rendering the audio graph.
5. In case of failure, queue a media element task to reject all pending resume promises and clear them.
6. Queue a media element task to resolve all pending resume promises, clear them, resolve the promise, and if the state is not already running, set it to running and fire a statechange event.
```

--------------------------------

### Main thread: create AudioContext and AudioWorkletNode for BitCrusher

Source: https://webaudio.github.io/web-audio-api/

Sets up an AudioContext, loads the 'bitcrusher.js' module, and creates an AudioWorkletNode with parameterData for bitDepth. Connects an oscillator through the bitcrusher and a gain node to the destination.

```javascript
const context = new AudioContext();context.audioWorklet.addModule('bitcrusher.js').then(() => {    const osc = new OscillatorNode(context);    const amp = new GainNode(context);    // Create a worklet node. 'BitCrusher' identifies the    // AudioWorkletProcessor previously registered when    // bitcrusher.js was imported. The options automatically    // initialize the correspondingly named AudioParams.    const bitcrusher = new AudioWorkletNode(context, 'bitcrusher', {        parameterData: {bitDepth: 8}    });    osc.connect(bitcrusher).connect(amp).connect(context.destination);    osc.start();});
```

--------------------------------

### AudioBuffer.copyToChannel()

Source: https://webaudio.github.io/web-audio-api/

Copies data from a Float32Array to a specified channel of the AudioBuffer, starting at an optional buffer offset.

```APIDOC
## copyToChannel(source, channelNumber, bufferOffset)

### Description
Copies the sample data from the `source` array to the specified channel of the `AudioBuffer`, starting at the given `bufferOffset`. The number of frames copied is limited by the buffer's length and the offset.

### Method
copyToChannel

### Parameters
- **source** (Float32Array) - Required - The array the channel data will be copied from.
- **channelNumber** (unsigned long) - Required - The index of the channel to copy the data to. If `channelNumber` is greater or equal than the number of channels of the `AudioBuffer`, an `IndexSizeError` MUST be thrown.
- **bufferOffset** (unsigned long) - Optional - An optional offset, defaulting to 0. Data from the `source` is copied to the `AudioBuffer` starting at this offset.

### Return Type
`undefined`
```

--------------------------------

### AudioNode Initialization Algorithm

Source: https://webaudio.github.io/web-audio-api/

Steps to initialize an object that inherits from AudioNode, given the arguments context and dict passed to the constructor.

```APIDOC
## AudioNode Initialization Algorithm

### Description
Initializes an AudioNode subclass instance with the provided context and dictionary options.

### Steps
1. Set o's associated BaseAudioContext to context.
2. Set its value for numberOfInputs, numberOfOutputs, channelCount, channelCountMode, channelInterpretation to the default value for this specific interface.
3. For each member of dict passed in, execute these steps, with k the key of the member, and v its value. If any exceptions is thrown when executing these steps, abort the iteration and propagate the exception to the caller of the algorithm (constructor or factory method).
   - If k is the name of an AudioParam on this interface, set the value attribute of this AudioParam to v.
   - Else if k is the name of an attribute on this interface, set the object associated with this attribute to v.
```

--------------------------------

### copyToChannel

Source: https://webaudio.github.io/web-audio-api/

Copies the samples from the source Float32Array into the specified channel of the AudioBuffer, starting at the given buffer offset.

```APIDOC
## copyToChannel(source, channelNumber, bufferOffset)

### Description
Copies the samples from the source Float32Array into the specified channel of the AudioBuffer, starting at the given buffer offset.

### Method
Method

### Parameters
- **source** (Float32Array) - Required - The array containing the data to copy.
- **channelNumber** (unsigned long) - Required - The channel number to copy to.
- **bufferOffset** (unsigned long) - Optional - The offset into the source array to start copying. Defaults to 0.

### Example
```js
const src = new Float32Array(44100);
audioBuffer.copyToChannel(src, 0, 0);
```
```

--------------------------------

### AudioContext.constructor(contextOptions)

Source: https://webaudio.github.io/web-audio-api/

Constructs a new AudioContext with optional user-specified options. The constructor may fire a statechange event and may silently render the audio graph if resource acquisition fails.

```APIDOC
## AudioContext.constructor(contextOptions)

### Description
Constructs a new AudioContext with optional user-specified options. The constructor may fire a statechange event and may silently render the audio graph if resource acquisition fails.

### Method
Constructor

### Endpoint
AudioContext.constructor(contextOptions)

### Parameters
#### Constructor Parameters
- **contextOptions** (AudioContextOptions) - Optional - User-specified options controlling how the AudioContext should be constructed.

### Events
- **statechange** - Fired at the AudioContext when the constructor is invoked.

### Notes
- In cases where an AudioContext is constructed with no arguments and resource acquisition fails, the User-Agent will attempt to silently render the audio graph using a mechanism that emulates an audio output device.

```

--------------------------------

### copyFromChannel

Source: https://webaudio.github.io/web-audio-api/

Copies the samples from the specified channel of the AudioBuffer to the destination Float32Array, starting at the given buffer offset.

```APIDOC
## copyFromChannel(destination, channelNumber, bufferOffset)

### Description
Copies the samples from the specified channel of the AudioBuffer to the destination Float32Array, starting at the given buffer offset.

### Method
Method

### Parameters
- **destination** (Float32Array) - Required - The array to copy the channel data into.
- **channelNumber** (unsigned long) - Required - The channel number to copy from.
- **bufferOffset** (unsigned long) - Optional - The offset into the destination array to start copying. Defaults to 0.

### Example
```js
const dest = new Float32Array(44100);
audioBuffer.copyFromChannel(dest, 0, 0);
```
```

--------------------------------

### DynamicsCompressorNode(context, options)

Source: https://webaudio.github.io/web-audio-api/

Creates a new DynamicsCompressorNode. The constructor initializes the AudioNode with the given context and options, and sets the internal reduction slot to 0.0.

```APIDOC
## DynamicsCompressorNode(context, options)

### Description
Creates a new DynamicsCompressorNode. The constructor initializes the AudioNode with the given context and options, and sets the internal reduction slot to 0.0.

### Method
Constructor

### Parameters
- **context** (BaseAudioContext) - Required - The BaseAudioContext this new DynamicsCompressorNode will be associated with.
- **options** (DynamicsCompressorOptions) - Optional - Optional initial parameter value for this DynamicsCompressorNode.

### Notes
- The internal reduction slot is set to 0.0.
```

--------------------------------

### OscillatorNode.type attribute

Source: https://webaudio.github.io/web-audio-api/

Gets or sets the type of waveform the oscillator generates. The type is an OscillatorType enum value.

```APIDOC
## [ATTRIBUTE] OscillatorNode.type

### Description
Gets or sets the type of waveform the oscillator generates. The type is an OscillatorType enum value.

### Type
OscillatorType

### Values
- "sine" - A sine wave
- "square" - A square wave of duty period 0.5
- "sawtooth" - A sawtooth wave
- "triangle" - A triangle wave
- "custom" - A custom periodic wave

### Example
```js
oscillator.type = 'square';
```
```

--------------------------------

### AudioSinkInfo

Source: https://webaudio.github.io/web-audio-api/

The AudioSinkInfo interface is used to get information on the current audio output device via sinkId. It has a readonly type attribute.

```APIDOC
## AudioSinkInfo

### Description
The `AudioSinkInfo` interface is used to get information on the current audio output device via `sinkId`.

### Interface Definition
```
[Exposed=Window]
interface AudioSinkInfo {
    readonly attribute AudioSinkType type;
};
```

### Attributes

#### type
- Type: `AudioSinkType`
- Readonly: Yes
- Description: A value of `AudioSinkType` that represents the type of the device.
```
Tokens:
Raw