AudioWorkletProcessor.process

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The process() method of an AudioWorkletProcessor-derived class implements the audio processing algorithm of the processor. Although the method is not a part of the AudioWorkletProcessor interface, each class that derives from it must have it implemented.

The method is called synchronously by the audio rendering thread at each rendering quantum ā€” that is 128 frames.

Syntax

var isActivelyProcessing = AudioWorkletProcessor.process(inputs, outputs, parameters);

Parameters

inputs

An array of inputs connected to the node, each item of which is, in turn, an array of channels. Each channel is a Float32Array containing 128 samples. For example, inputs[n][m][i] will access n-th input, m-th channel of that input, and i-th sample of that channel.

Each sample value is in range of [-1 .. 1].

The number of inputs and thus the length of that array is fixed at the construction of the node (see AudioWorkletNodeOptions). If there is no active node connected to the n-th input of the node, inputs[n] will be an empty array (zero input channels available).

The number of channels in each input may vary, depending on channelCount and channelCountMode properties.

outputs
An array of outputs that is similar to the inputs parameter in structure. It is intended to be filled during the execution of the process method. Each of the output channels is filled with zeros by default ā€” the processor will output silence unless the output arrays are modified.
parameters

An object containing string keys and Float32Array values. For each custom AudioParam defined using the parameterDescriptors getter, the key in the object is a name of that AudioParam, and the value is a Float32Array. The values of the array are calculated by taking scheduled automation events into consideration.

If the automation rate of the parameter is "a-rate", the array will contain 128 values ā€” one for each frame in the current render quantum. If there's no automation happening during the rendering quantum, the array may contain a single value that is constant during the render quantum, instead of 128 identical values.

If the automation rate is "k-rate", the array will contain a single value, which is to be used for each of 128 frames.

Return value

The returned value impacts the lifetime of the current AudioWorkletProcessor and affects the subsequent invocations of the process method. Returning true means that the node is healthy and generates an output; returning false means that, if the node has no active inputs, it will no longer generate any output, therefore, the browser will not call process again during the next render quantums.

The 3 most common types of audio node are:

  1. A source of output. An AudioWorkletProcessor implementing such a node should return true from the process method as long as it produces an output. The method should return false as soon as it's known that it will no longer produce an output. For example, take the AudioBufferSourceNode ā€” the processor behind such a node should return true from the process method while the buffer is playing, and start returning false when the buffer playing has ended (there's no way to call play on the same AudioBufferSourceNode again).
  2. A node that transforms its input. A processor implementing such a node should return false from the process method to allow the presence of active input nodes and references to the node to determine whether it can be garbage-collected. An example of a node with this behaviour is the GainNode. As soon as there are no inputs connected and references retained, gain can no longer be applied to anything, so it can be safely garbage-collected.
  3. A node that transforms its input, but has a so-called tail-time ā€” this means that it will produce an output for some time even after its inputs are disconnected or are inactive (producing zero-channels). A processor implementing such a node should return true from the process method for the period of the tail-time, beginning as soon as inputs are found that contain zero-channels. An example of such a node is the DelayNode ā€” it has a tail-time equal to its delayTime property.

Note: An absence of the return statement means that the method returns undefined, and as this is a falsy value, it is like returning false. Omitting an explicit return statement may cause hard-to-detect problems for your nodes.

Exceptions

As the process method is implemented by the user, it can throw anything. If an uncaught error is thrown, the node will emit an onprocessorerror event and will output silence for the rest of its lifetime.

Examples

In this example we create an AudioWorkletProcessor that outputs white noise to its first output. The gain can be controlled by the customGain parameter.

class WhiteNoiseProcessor extends AudioWorkletProcessor {
  process (inputs, outputs, parameters) {
    // take the first output
    const output = outputs[0]
    // fill each channel with random values multiplied by gain
    output.forEach(channel => {
      for (let i = 0; i < channel.length; i++) {
        // generate random value for each sample
        // Math.random range is [0; 1); we need [-1; 1]
        // this won't include exact 1 but is fine for now for simplicity
        channel[i] = (Math.random() * 2 - 1) *
          // the array can contain 1 or 128 values
          // depending on if the automation is present
          // and if the automation rate is k-rate or a-rate
          (parameters['customGain'].length > 1
            ? parameters['customGain'][i]
            : parameters['customGain'][0])
      }
    })
    // as this is a source node which generates its own output,
    // we return true so it won't accidentally get garbage-collected
    // if we don't have any references to it in the main thread
    return true
  }
  // define the customGain parameter used in process method
  static get parameterDescriptors () {
    return [{
      name: 'customGain',
      defaultValue: 1,
      minValue: 0,
      maxValue: 1,
      automationRate: 'a-rate'
    }]
  }
}

Specifications

Specification Status Comment
Web Audio API
The definition of 'process()' in that specification.
Working Draft

Browser compatibility

No compatibility data found. Please contribute data for "api.AudioWorkletProcessor.process" (depth: 1) to the MDN compatibility data repository.

See also