WorkletProcessingNode

warning

Requires react-native-audio-worklets, react-native-worklets >= 0.10.0, and react-native-audio-api >= 1.0.0. See the Worklets introduction for installation.

WorkletProcessingNode is an effect node that processes audio synchronously on the audio worklet runtime each render quantum. Unlike WorkletNode, which only provides read-only snapshots on the UI runtime, this node receives input audio and writes processed output back into the graph.

Use it for custom effects, filters, dynamics processors, and other in-graph DSP written in JavaScript.

For runtime differences and performance tips, see How to use audio worklets mindfully.

Constructor

import { AudioContext } from 'react-native-audio-api';
import { WorkletProcessingNode } from 'react-native-audio-worklets';

const node = new WorkletProcessingNode(context, callback);

Parameters

Parameter	Type	Description
context	BaseAudioContext	The audio context that owns this node.
callback	WorkletProcessingNodeCallback	Worklet invoked on the audio runtime each render quantum. Must include the 'worklet' directive.

WorkletProcessingNodeCallback

type WorkletProcessingNodeCallback = (
  inputData: Array<Float32Array>,
  outputData: Array<Float32Array>,
  inputChannelCount: number,
  outputChannelCount: number,
  framesToProcess: number,
  currentTime: number
) => void;

Argument	Description
inputData	Stable per-channel Float32Array views over the input pool (read-only for your callback). Each view spans the full render quantum (128 frames).
outputData	Stable per-channel Float32Array views over the output pool. Write processed samples into indices 0 .. framesToProcess - 1.
inputChannelCount	Active input channel count (inputData.length).
outputChannelCount	Active output channel count (outputData.length).
framesToProcess	Number of frames in this quantum (at most 128).
currentTime	Audio context time in seconds at the start of this quantum.

note

Input and output use separate buffer pools. You must write every output sample you want to hear — unwritten frames are not automatically copied from input.

Errors

Error type	Condition
NotSupportedError	react-native-audio-worklets native module not installed, worklet extensions are not linked, or New Architecture is disabled.
NotSupportedError	react-native-worklets is missing or below the supported version (>= 0.10.0).

Example

Simple gain effect:

import { AudioContext } from 'react-native-audio-api';
import { WorkletProcessingNode } from 'react-native-audio-worklets';

function GainEffect() {
  const start = () => {
    const ctx = new AudioContext();

    const gainNode = new WorkletProcessingNode(
      ctx,
      (inputData, outputData, inputChannelCount, outputChannelCount, framesToProcess) => {
        'worklet';

        const gain = 0.5;

        for (let ch = 0; ch < Math.min(inputChannelCount, outputChannelCount); ch++) {
          const input = inputData[ch]!;
          const output = outputData[ch]!;

          for (let i = 0; i < framesToProcess; i++) {
            output[i] = input[i]! * gain;
          }
        }
      }
    );

    const oscillator = ctx.createOscillator();
    oscillator.connect(gainNode);
    gainNode.connect(ctx.destination);
    oscillator.start();
    ctx.resume();
  };

  // ...
}

Audio Processing Pattern

A typical WorkletProcessingNode worklet follows this pattern:

const processor = (
  inputData: Array<Float32Array>,
  outputData: Array<Float32Array>,
  inputChannelCount: number,
  outputChannelCount: number,
  framesToProcess: number,
  currentTime: number
) => {
  'worklet';

  for (let channel = 0; channel < outputChannelCount; channel++) {
    const input = inputData[Math.min(channel, inputChannelCount - 1)]!;
    const output = outputData[channel]!;

    for (let sample = 0; sample < framesToProcess; sample++) {
      output[sample] = processSample(input[sample]!, currentTime);
    }
  }
};

Properties

Inherits all properties from AudioNode.

AudioNodeproperties

WorkletProcessingNode does not define any additional properties.

Methods

Inherits all methods from AudioNode.

AudioNodemethods

WorkletProcessingNode does not define any additional methods.

Performance considerations

Callbacks run synchronously on the audio path each render quantum. Keep worklet functions lightweight — heavy math or allocations can cause dropouts.

See also

• WorkletSourceNode — generate audio with a worklet
• WorkletNode — read-only snapshots on the UI runtime for visualizers
• Worklets introduction