TheAudioWorkletProcessor interface of theWeb Audio API represents an audio processing code behind a customAudioWorkletNode. It lives in theAudioWorkletGlobalScope and runs on the Web Audio rendering thread. In turn, anAudioWorkletNode based on it runs on the main thread.

Constructor

AudioWorkletProcessor()

Creates a new instance of anAudioWorkletProcessor object.

Instance properties

portRead only

Returns aMessagePort used for bidirectional communication between the processor and theAudioWorkletNode which it belongs to. The other end is available under theport property of the node.

Instance methods

TheAudioWorkletProcessor interface does not define any methods of its own. However, you must provide aprocess() method, which is called in order to process the audio stream.

Events

TheAudioWorkletProcessor interface doesn't respond to any events.

Usage notes

Deriving classes

To define custom audio processing code you have to derive a class from theAudioWorkletProcessor interface. Although not defined on the interface, the deriving class must have theprocess method. This method gets called for each block of 128 sample-frames and takes input and output arrays and calculated values of customAudioParams (if they are defined) as parameters. You can use inputs and audio parameter values to fill the outputs array, which by default holds silence.

Optionally, if you want customAudioParams on your node, you can supply aparameterDescriptors property as astatic getter on the processor. The array ofAudioParamDescriptor-based objects returned is used internally to create theAudioParams during the instantiation of theAudioWorkletNode.

The resultingAudioParams reside in theparameters property of the node and can be automated using standard methods such aslinearRampToValueAtTime. Their calculated values will be passed into theprocess() method of the processor for you to shape the node output accordingly.

Processing audio

An example algorithm of creating a custom audio processing mechanism is:

1. Create a separate file;

2. In the file:

   1. Extend theAudioWorkletProcessor class (see"Deriving classes" section) and supply your ownprocess() method in it;
   2. Register the processor usingAudioWorkletGlobalScope.registerProcessor() method;

3. Load the file usingaddModule() method on your audio context'saudioWorklet property;

4. Create anAudioWorkletNode based on the processor. The processor will be instantiated internally by theAudioWorkletNode constructor.

5. Connect the node to the other nodes.

Examples

In the example below we create a customAudioWorkletNode that outputs white noise.

First, we need to define a customAudioWorkletProcessor, which will output white noise, and register it. Note that this should be done in a separate file.

// white-noise-processor.jsclass WhiteNoiseProcessor extends AudioWorkletProcessor {  process(inputs, outputs, parameters) {    const output = outputs[0];    output.forEach((channel) => {      for (let i = 0; i < channel.length; i++) {        channel[i] = Math.random() * 2 - 1;      }    });    return true;  }}registerProcessor("white-noise-processor", WhiteNoiseProcessor);

Next, in our main script file we'll load the processor, create an instance ofAudioWorkletNode, passing it the name of the processor, then connect the node to an audio graph.

const audioContext = new AudioContext();await audioContext.audioWorklet.addModule("white-noise-processor.js");const whiteNoiseNode = new AudioWorkletNode(  audioContext,  "white-noise-processor",);whiteNoiseNode.connect(audioContext.destination);

Specifications

Browser compatibility

See also

• Web Audio API
• Using the Web Audio API
• Using AudioWorklet