Installation

Install the React Native Sherpa-ONNX SDK and configure it for your platform.

Install Package

npm install react-native-sherpa-onnx

Peer Dependencies

The SDK requires @dr.pogodin/react-native-fs for file system operations:

npm install @dr.pogodin/react-native-fs

Yarn v3+ / Plug’n’Play Users: If you use Yarn with PnP, configure the Node Modules linker to avoid postinstall issues:

.yarnrc.yml

nodeLinker: node-modules

Or set the environment variable during install:

YARN_NODE_LINKER=node-modules yarn install

Platform Setup

Android
iOS

Android Configuration

No additional setup required! The library automatically handles native dependencies via Gradle.The SDK includes:

sherpa-onnx native libraries - Automatically downloaded during build
ONNX Runtime - Bundled with execution provider support
Hardware acceleration - CPU, NNAPI, XNNPACK, and QNN support

Optional: QNN (Qualcomm Neural Network) Setup

For Qualcomm Snapdragon devices with AI accelerator support:

Check device support

QNN provides hardware acceleration on Qualcomm Snapdragon chipsets with AI Engine (Hexagon DSP).

import { getQnnSupport } from 'react-native-sherpa-onnx';

const support = await getQnnSupport();
console.log('QNN available:', support.providerCompiled);
console.log('QNN accelerator:', support.hasAccelerator);
console.log('Can initialize:', support.canInit);

Configure execution provider

Pass provider: 'qnn' when initializing STT or TTS:

const stt = await createSTT({
  modelPath: { type: 'asset', path: 'models/whisper-tiny' },
  provider: 'qnn', // Use QNN acceleration
});

See Execution Provider Support for details on NNAPI, XNNPACK, and QNN configuration.

Build from Source (Advanced)

To build Android native libraries yourself:

cd node_modules/react-native-sherpa-onnx
# See third_party/sherpa-onnx-prebuilt/README.md for build instructions

Release versions are pinned in third_party/sherpa-onnx-prebuilt/ANDROID_RELEASE_TAG.

iOS Configuration

The sherpa-onnx XCFramework (~80MB) is automatically downloaded when you run pod install. No manual steps required.

Install dependencies

Navigate to your iOS directory and install pods:

cd ios
bundle install
bundle exec pod install

The podspec automatically:

Downloads the XCFramework from GitHub Releases
Compiles libarchive from source (for model archive support)
Links everything correctly

Verify installation

After pod install completes, you should see:

Installing react-native-sherpa-onnx (x.x.x)
Downloading sherpa-onnx XCFramework...
Building libarchive...

Build your app

Build and run normally:

npx react-native run-ios

Or open the workspace in Xcode:

open ios/YourApp.xcworkspace

Version Information

XCFramework version: Pinned in third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG
libarchive version: Pinned in third_party/libarchive_prebuilt/IOS_RELEASE_TAG
Download source: GitHub Releases

Core ML Acceleration

iOS devices automatically use Core ML for hardware acceleration when available:

import { getCoreMlSupport } from 'react-native-sherpa-onnx';

const support = await getCoreMlSupport();
console.log('Core ML available:', support.providerCompiled);
console.log('Neural Engine:', support.hasAccelerator); // Apple Neural Engine

To explicitly use Core ML:

const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/vits-piper-en' },
  provider: 'coreml', // Use Core ML
});

Build Framework Locally (Advanced)

If you need a custom sherpa-onnx build:

Building the XCFramework yourself

The repo does not include an iOS build script. To build locally:

Use the CI workflow: The build-sherpa-onnx-ios-framework workflow produces the XCFramework. You can run equivalent steps locally.
Manual build: See the workflow for exact build steps, including:
- Building libsherpa-onnx-cxx-api.a (C++ API)
- Merging static libraries
- Creating the XCFramework with multiple architectures
Place the framework: After building, place sherpa-onnx.xcframework in ios/Frameworks/ before running pod install.

The XCFramework must include the C++ API (libsherpa-onnx-cxx-api.a merged) so that the iOS Obj-C++ code can use sherpa_onnx::cxx::* classes.

Verify Installation

Test that the native library loads correctly:

App.tsx

import { useEffect } from 'react';
import { testSherpaInit } from 'react-native-sherpa-onnx';

export default function App() {
  useEffect(() => {
    testSherpaInit()
      .then((result) => console.log('Sherpa-ONNX initialized:', result))
      .catch((err) => console.error('Initialization failed:', err));
  }, []);

  return <Text>Testing Sherpa-ONNX...</Text>;
}

Expected output:

Sherpa-ONNX initialized: sherpa-onnx native library loaded successfully

Check Execution Providers

Verify available hardware acceleration:

import { getAvailableProviders } from 'react-native-sherpa-onnx';

const providers = await getAvailableProviders();
console.log('Available providers:', providers);
// Example output: ['CPU', 'CoreML', 'XNNPACK'] on iOS
// Example output: ['CPU', 'NNAPI', 'XNNPACK', 'QNN'] on Android

Next Step: Follow the Quick Start Guide to transcribe your first audio file or generate speech.

Troubleshooting

iOS: XCFramework download fails

If pod install fails to download the XCFramework:

Check internet connection: The framework is ~80MB and requires a stable connection.
Manual download: Download from GitHub Releases and place in node_modules/react-native-sherpa-onnx/ios/Frameworks/.
Check version: Ensure the release tag matches third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG.

Android: Build fails with native library errors

Common issues:

Gradle sync: Run cd android && ./gradlew clean then rebuild.
NDK version: Ensure you have NDK 21 or later installed.
Memory: Gradle may need more memory. Add to android/gradle.properties:
```
org.gradle.jvmargs=-Xmx4096m
```

Yarn PnP issues

If using Yarn v3+ with Plug’n’Play:

.yarnrc.yml

nodeLinker: node-modules

Or use the environment variable:

YARN_NODE_LINKER=node-modules yarn install

Missing peer dependency error

Install the required peer dependency:

npm install @dr.pogodin/react-native-fs

Then rebuild:

cd ios && pod install
cd android && ./gradlew clean

Next Steps

Quick Start

Build your first speech recognition app

Download Models

Learn how to download and bundle models

STT API Reference

Explore speech-to-text features

TTS API Reference

Explore text-to-speech features

Get Started

Core Features

Guides

Platform Specific

Advanced

Installation

Installation

Install Package

Peer Dependencies

Platform Setup

Android Configuration

Optional: QNN (Qualcomm Neural Network) Setup

Build from Source (Advanced)

iOS Configuration

Version Information

Core ML Acceleration

Build Framework Locally (Advanced)

Verify Installation

Check Execution Providers

Troubleshooting

Next Steps

Quick Start

Download Models

STT API Reference

TTS API Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Platform Specific

Advanced

​Installation

​Install Package

​Peer Dependencies

​Platform Setup

​Android Configuration

​Optional: QNN (Qualcomm Neural Network) Setup

​Build from Source (Advanced)

​iOS Configuration

​Version Information

​Core ML Acceleration

​Build Framework Locally (Advanced)

​Verify Installation

​Check Execution Providers

​Troubleshooting

​Next Steps

Quick Start

Download Models

STT API Reference

TTS API Reference

Build docs developers (and LLMs) love

Installation

Install Package

Peer Dependencies

Platform Setup

Android Configuration

Optional: QNN (Qualcomm Neural Network) Setup

Build from Source (Advanced)

iOS Configuration

Version Information

Core ML Acceleration

Build Framework Locally (Advanced)

Verify Installation

Check Execution Providers

Troubleshooting

Next Steps