Worklets

Mobile only

Worklet support in React Native Audio API is provided by a separate package — react-native-audio-worklets. It bridges the audio engine with react-native-worklets so you can react to live audio on the UI thread — for example, to drive Reanimated visualizers from an RMS meter.

Requirements

• react-native-audio-api >= 1.0.0
• react-native-worklets >= 0.10.0
• React Native New Architecture (TurboModules / Fabric)

Installation

Install both peer dependencies and the worklets integration package:

npm

npm install react-native-audio-api react-native-worklets react-native-audio-worklets

yarn

yarn add react-native-audio-api react-native-worklets react-native-audio-worklets

Follow the react-native-worklets setup guide (Babel plugin, native rebuild). Then rebuild your app so the native modules are linked:

iOS

cd ios && pod install && cd ..
npx react-native run-ios

Android

npx react-native run-android

Import react-native-audio-worklets before creating any worklet node. The package installs its native extensions on top of react-native-audio-api:

import 'react-native-audio-api';
import {
  WorkletAudioContext,
  WorkletNode,
  WorkletProcessingNode,
  WorkletSourceNode,
} from 'react-native-audio-worklets';

WorkletAudioContext

Worklet nodes accept any BaseAudioContext, but WorkletAudioContext is the dedicated context for worklet graphs that do not need speaker output. It renders on a background thread and discards audio at destination, which keeps visualization or analysis graphs separate from your main AudioContext playback session.

See the WorkletAudioContext page for constructor options, lifecycle (resume / suspend / close), and usage patterns.

tip

If you only use core audio nodes and never import react-native-audio-worklets, you do not need react-native-worklets installed — the main library builds without it.

What is a worklet?

You can read more about worklets in the RNWorklets documentation.

Simply put, a worklet is a piece of JavaScript that can run on a runtime other than the one it was created on — for example, the shared UI worklet runtime used by Reanimated.

UI runtime

WorkletNode dispatches your callback on the UI worklet runtime provided by react-native-worklets. That lets you update Reanimated shared values and animated styles directly from audio-driven logic.

Use it when you want to:

• Build visualizers or meters from live audio
• Drive UI animations from audio analysis (RMS, peak level, etc.)
• Integrate with Reanimated shared values and withSpring / withTiming

Audio still flows through the node unchanged — the worklet receives a read-only snapshot for analysis.

Audio runtime

WorkletSourceNode and WorkletProcessingNode invoke your callback synchronously on a dedicated audio worklet runtime each render quantum (128 frames).

Use them when you want to:

• Build custom synthesizers or procedural generators (WorkletSourceNode)
• Implement in-graph JavaScript effects, filters, or dynamics processors (WorkletProcessingNode)
• Process audio sample-by-sample with synchronous control over the output buffer

These callbacks run on the audio path. Keep them short and allocation-free — a slow worklet can cause dropouts.

How to use audio worklets mindfully

WorkletNode (UI visualization)

WorkletNode is designed for UI visualization, not sample-accurate audio processing. The audio thread accumulates frames into a snapshot buffer and schedules your callback on the UI thread — it never blocks playback.

bufferLength is the number of frames in each down-mixed mono snapshot. It controls how often the callback runs when the UI keeps up:

$$\text{callback rate (Hz)} \approx \frac{\text{sampleRate}}{\text{bufferLength}}$$

At 44.1 kHz with bufferLength = 128, that is roughly 344 callbacks per second (~2.9 ms between dispatches). A slow UI callback does not cause audio dropouts — while your worklet is still running, new snapshots are skipped and audio continues to pass through unchanged. You may simply miss visualization updates.

• Smaller bufferLength — lower analysis latency, more frequent UI callbacks, more JS work
• Larger bufferLength — smoother analysis windows (e.g. RMS over more samples), fewer callbacks

Use a larger bufferLength such as 256, 512, or 1024 if you do not need more than ~40 fps of meter updates.

WorkletSourceNode and WorkletProcessingNode (audio path)

These nodes invoke your worklet synchronously on the audio thread each render quantum (128 frames). The entire callback — including your DSP and any other graph processing in that quantum — must finish within one quantum's time budget.

At 44.1 kHz, 128 frames is roughly 2.9 ms. If your worklet takes longer, you may experience audio dropouts or glitches.

General tips

• Avoid blocking operations inside any worklet (e.g. network calls or async APIs). Offload that work to the JS thread via callbacks.
• Do not overuse worklets. Before creating several chained worklet nodes, consider whether a single node can do the job — each one adds latency on the audio path.
• Measure performance and memory usage, and check logs to ensure you are not dropping frames.