Turbo Modules
Developmentturbo-modulesTurbo Modules is an Agent Skill for development published in the software-mansion/react-native-audio-api repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
TurboModule spec, JSI binding injection, and platform native module entry points. Use when adding a new native method to NativeAudioAPIModule.ts, wiring a new top-level HostObject through AudioAPIModuleInstaller, debugging "native module not found" or "undefined is not a function" for a global, or understanding the install() bootstrap flow on iOS and Android. Trigger phrases: "native module not found", "install()", "NativeAudioAPIModule", "injectJSIBindings", "AudioAPIModuleInstaller", "JSI global", "TurboModule spec", "module bootstrap", "undefined is not a function".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/software-mansion/react-native-audio-api/blob/HEAD/.claude/skills/turbo-modules/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/turbo-modules, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Skill: TurboModules & JSI Installation
When to Use TurboModule vs HostObjects
Rule: if it needs AVAudioSession, AudioManager, MediaSession, or OS permissions → TurboModule. If it's audio processing → HostObject installed by AudioAPIModuleInstaller.
| Use TurboModule method | Use HostObject property/method |
|---|---|
| Platform system APIs (audio session, permissions, notifications, device routing) | All audio graph operations (create/connect/disconnect nodes, AudioParam, scheduling) |
One-time initialization (install) | Real-time playback control |
| Features that need native UI thread or system callbacks | Features that only need the JSI runtime |
| Android-only or iOS-only behavior | Cross-platform C++ engine behavior |
Most audio nodes do not need a TurboModule method — they are exposed entirely through JSI HostObjects injected by injectJSIBindings.
Reference
- RN TurboModules (new arch): https://reactnative.dev/docs/the-new-architecture/pure-cxx-modules
- RN JSI: https://reactnative.dev/docs/the-new-architecture/architecture-glossary#javascript-interface-jsi
- fbjni (Android JNI bridge): https://github.com/facebookincubator/fbjni
The Big Picture
Most audio functionality is exposed not through TurboModule method calls but through JSI HostObjects placed directly on the JS global object. The TurboModule's job is narrow:
- Be available early via the standard RN module system
- Provide
install()— one synchronous call that injects HostObject factories ontoglobalThis - Expose platform-specific system APIs (audio session, permissions, notifications, devices) that cannot be done through pure JSI
flowchart TD
A["JS: NativeAudioAPIModule.install()"]
subgraph ios["iOS — AudioAPIModule.mm"]
B["init AudioSessionManager · AudioEngine\nget jsi::Runtime* · CallInvoker"]
end
subgraph android["Android — AudioAPIModule.kt + .cpp"]
C["MediaSessionManager.initialize()\nJNI: injectJSIBindings()"]
end
D["AudioAPIModuleInstaller::injectJSIBindings\n(runtime, callInvoker, eventRegistry, uiRuntime?)"]
subgraph globals["globalThis — set by injectJSIBindings"]
G["createAudioContext\ncreateOfflineAudioContext\ncreateAudioRecorder\ncreateAudioBuffer\ncreateAudioDecoder\ncreateAudioFileUtils\nAudioEventEmitter HostObject"]
end
A --> ios
A --> android
ios --> D
android --> D
D --> globals
After install() returns, TypeScript code can call globalThis.createAudioContext(sampleRate) and get back a HostObject — no serialization, no bridge round-trip.
TurboModule Spec (src/specs/NativeAudioAPIModule.ts)
Defines the TypeScript interface for the native module. Codegen (React Native's codegen) generates the native binding glue from this file.
interface Spec extends TurboModule {
install(): boolean; // synchronous — MUST run first
getDevicePreferredSampleRate(): number; // synchronous
setAudioSessionActivity(enabled: boolean): Promise<boolean>;
setAudioSessionOptions(...): void;
observeAudioInterruptions(focusType, enabled): void;
requestRecordingPermissions(): Promise<PermissionStatus>;
// ... audio devices, notifications ...
}
const NativeAudioAPIModule = TurboModuleRegistry.get<Spec>('AudioAPIModule')!;
install() is synchronous (RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD on iOS, override fun install(): Boolean on Android). It must complete before the app tries to use any audio API. It is called once during module bootstrap in src/AudioAPIModule/index.ts.
Web mock (src/specs/NativeAudioAPIModule.web.ts): on the web platform, the whole spec is mocked with no-ops and resolved promises (e.g. permissions always return 'Granted'). This file replaces the native spec at bundle time for web builds.
AudioAPIModuleInstaller (common/cpp/audioapi/AudioAPIModuleInstaller.h)
The single C++ class that owns JSI injection. It is #include-d by both iOS (.mm) and Android (.cpp) native modules, keeping the injection logic platform-agnostic.
class AudioAPIModuleInstaller {
public:
static void injectJSIBindings(
jsi::Runtime *jsiRuntime,
const std::shared_ptr<react::CallInvoker> &jsCallInvoker,
const std::shared_ptr<AudioEventHandlerRegistry> &audioEventHandlerRegistry,
std::shared_ptr<worklets::WorkletRuntime> uiRuntime = nullptr);
};
Each get*Function() private method creates a jsi::Function via jsi::Function::createFromHostFunction(). The lambda captures the dependencies it needs (jsCallInvoker, audioEventHandlerRegistry, uiRuntime) by value (shared_ptr).
Worklets guard: functions that need the worklets runtime (AudioContext, OfflineAudioContext) have an #if RN_AUDIO_API_ENABLE_WORKLETS branch:
#if RN_AUDIO_API_ENABLE_WORKLETS
auto runtimeRegistry = RuntimeRegistry{.uiRuntime = uiRuntime};
if (count > 1 && args[1].isObject()) {
runtimeRegistry.audioRuntime = worklets::extractWorkletRuntime(runtime, args[1]);
}
#else
auto runtimeRegistry = RuntimeRegistry{};
#endif
Adding a new top-level global: add a static jsi::Function getCreateXxxFunction(...) private method and a setProperty("createXxx", ...) call in injectJSIBindings. This is only needed for objects that JS creates directly (not objects created as properties of another HostObject).
iOS Native Module (AudioAPIModule.mm)
Uses ObjC++ with RCT_EXPORT_MODULE and RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD.
Key steps in install:
- Allocate platform managers (
AudioSessionManager,AudioEngine,SystemNotificationManager,NotificationRegistry) - Get
jsi::Runtime *from the bridge:reinterpret_cast<facebook::jsi::Runtime *>(self.bridge.runtime) - Get
CallInvoker— different paths for old Bridge vs New Architecture:#if defined(RCT_NEW_ARCH_ENABLED) auto jsCallInvoker = _callInvoker.callInvoker; #else auto jsCallInvoker = self.bridge.jsCallInvoker; #endif - Create
AudioEventHandlerRegistry(owns JS callbacks, needs runtime + callInvoker) - Call
AudioAPIModuleInstaller::injectJSIBindings(...)
New Architecture support (getTurboModule):
#ifdef RCT_NEW_ARCH_ENABLED
- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
(const facebook::react::ObjCTurboModule::InitParams &)params
{
return std::make_shared<facebook::react::NativeAudioAPIModuleSpecJSI>(params);
}
#endif
This connects the ObjC implementation to the codegen-generated C++ TurboModule spec.
methodQueue: the module runs on a dedicated serial queue (com.swmansion.audioapi.MainModuleQueue), not the main thread.
invokeHandlerWithEventName:eventBody:: called from Objective-C system callbacks (audio session interruption, volume change, etc.) to fire events back into JS. It converts NSDictionary to std::unordered_map<std::string, EventValue> and calls audioEventHandlerRegistry_->invokeHandlerWithEventBody(...).
Android Native Module (AudioAPIModule.kt + AudioAPIModule.cpp)
Android uses fbjni HybridObject — a pattern where a Kotlin class holds a C++ peer via HybridData. The Kotlin class handles the Java/Kotlin TurboModule protocol; the C++ peer owns the JSI runtime pointer and call invoker.
Initialization flow
AudioAPIModule.kt (init block)
├── System.loadLibrary("react-native-audio-api") // load .so
├── get CallInvokerHolderImpl from reactContext
├── get WorkletsModule if worklets enabled
└── mHybridData = initHybrid(workletsModule, jsContext, callInvokerHolder)
│
▼
AudioAPIModule.cpp::initHybrid (JNI)
├── unwrap jsCallInvoker from holder
├── reinterpret_cast<jsi::Runtime *>(jsContext)
├── [if worklets] get WorkletsModuleProxy
└── makeCxxInstance(...) → creates C++ AudioAPIModule peer
└── stores: jsiRuntime_, jsCallInvoker_, audioEventHandlerRegistry_
AudioAPIModule.kt::install()
├── MediaSessionManager.initialize(...)
├── NativeFileInfo.initialize(...)
└── injectJSIBindings() // external fun → JNI call
│
▼
AudioAPIModule.cpp::injectJSIBindings()
└── AudioAPIModuleInstaller::injectJSIBindings(...)
external fun: Kotlin keyword for JNI-implemented methods. These are registered in AudioAPIModule.cpp::registerNatives():
void AudioAPIModule::registerNatives() {
registerHybrid({
makeNativeMethod("initHybrid", AudioAPIModule::initHybrid),
makeNativeMethod("injectJSIBindings", AudioAPIModule::injectJSIBindings),
makeNativeMethod("invokeHandlerWithEventNameAndEventBody", ...),
});
}
registerNatives() is called from android/src/main/cpp/audioapi/android/OnLoad.cpp at .so load time.
invokeHandlerWithEventNameAndEventBody: called from Kotlin (MediaSessionManager callbacks) to fire events into JS. Takes a Java Map<String, Object> and converts to std::unordered_map<std::string, EventValue>.
Two-Architecture Paths Summary
| Old Bridge | New Architecture (TurboModules/Fabric) | |
|---|---|---|
| iOS CallInvoker source | self.bridge.jsCallInvoker | _callInvoker.callInvoker |
| iOS runtime source | self.bridge.runtime (cast) | same |
| iOS codegen | RCT_EXPORT_MODULE only | + getTurboModule: implemented |
| Android CallInvoker | reactContext.jsCallInvokerHolder | same |
| Android codegen | NativeAudioAPIModuleSpec base class | same (generated) |
The JSI injection itself (AudioAPIModuleInstaller) is identical for both architectures — it only needs the jsi::Runtime * and CallInvoker, which are obtained differently but behave the same.
Pure C++ TurboModule library (react-native-audio-worklets)
Extension packages that expose a C++-only TurboModule (no JNI implementation) use a hybrid Android setup:
| Piece | Role |
|---|---|
react-native.config.js cxxModule* fields | Registers NativeAudioWorkletsModule in app autolinking (autolinking_cxxModuleProvider) |
android/build.gradle + com.facebook.react | Runs Codegen → react_codegen_rnaudioworklets (JSI spec headers) |
AudioWorkletsPackage.kt | Stub BaseReactPackage so Gradle autolinking includes the library project |
Root CMakeLists.txt | Static react-native-audio-worklets target; linked into libappmodules.so via autolinking |
common/cpp/NativeAudioWorkletsModule.h | Forwarding header — autolinking includes <NativeAudioWorkletsModule.h> |
iOS uses NativeAudioWorkletsModuleProvider.mm + codegenConfig.ios.modulesProvider instead.
RN guide: https://reactnative.dev/docs/the-new-architecture/pure-cxx-modules
Maintenance: see maintenance.md.