WorkletSourceNode

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.

WorkletSourceNode is a scheduled source that generates audio synchronously on the audio worklet runtime each render quantum. It extends AudioScheduledSourceNode, so you can start() and stop() it at specific times.

Use it for custom synthesizers, procedural generators, and other nodes that produce audio rather than process an existing input.

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

Constructor

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

const node = new WorkletSourceNode(context, callback);

Parameters

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

WorkletSourceNodeCallback

type WorkletSourceNodeCallback = (
  audioData: Array<Float32Array>,
  outputChannelCount: number,
  framesToProcess: number,
  currentTime: number,
  startOffset: number
) => void;

Argument	Description
audioData	Stable per-channel Float32Array views over a reused native buffer pool. Each view spans the full render quantum (128 frames); write samples into indices 0 .. framesToProcess - 1.
outputChannelCount	Active output channel count (audioData.length).
framesToProcess	Number of frames to generate this quantum. May be less than 128 when playback starts or stops mid-buffer.
currentTime	Audio context time in seconds at the start of this quantum.
startOffset	Silent prefix length (in samples) already zeroed in the output buffer when playback starts mid-quantum. Use for time math, not as a write index into audioData.

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

Sine generator → destination:

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

function SineGenerator() {
  const start = () => {
    const ctx = new AudioContext();
    const sampleRate = ctx.sampleRate;

    const source = new WorkletSourceNode(
      ctx,
      (audioData, outputChannelCount, framesToProcess, currentTime, startOffset) => {
        'worklet';

        const frequency = 440;

        for (let channel = 0; channel < outputChannelCount; channel++) {
          for (let i = 0; i < framesToProcess; i++) {
            const sampleTime = currentTime + (startOffset + i) / sampleRate;
            const phase = 2 * Math.PI * frequency * sampleTime;
            audioData[channel]![i] = Math.sin(phase) * 0.25;
          }
        }
      }
    );

    source.connect(ctx.destination);
    source.start();
    ctx.resume();
  };

  // ...
}

Understanding startOffset and currentTime

When a source starts mid-quantum, native code zeroes the silent prefix in the output buffer. Your worklet still writes from index 0, and native code copies those samples to the correct offset.

The absolute time for sample i is:

currentTime + (startOffset + i) / sampleRate

Use this for phase-continuous oscillators, LFOs, and envelopes.

Properties

Inherits all properties from AudioScheduledSourceNode.

AudioNodeproperties

Methods

Inherits all methods from AudioScheduledSourceNode, including start() and stop().

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

• WorkletProcessingNode — process an existing signal with a worklet
• WorkletNode — read-only snapshots on the UI runtime for visualizers
• Worklets introduction