react-native-sherpa-tts

React Native wrapper for sherpa-onnx offline TTS — powered by Supertonic 3 (31 languages, on-device, no network).

⚠️ Android only — iOS support is not included in this version.

Setup

1. Install

npm install react-native-sherpa-tts

2. Copy model files to Android assets

Copy the Supertonic 3 model files into your RN project:

# From the model directory on your machine:
cp -r sherpa-onnx-supertonic-3-tts-int8-2026-05-11 \
  android/app/src/main/assets/

The android/app/src/main/assets/ directory should contain:

sherpa-onnx-supertonic-3-tts-int8-2026-05-11/
├── duration_predictor.int8.onnx   (~3.5 MB)
├── text_encoder.int8.onnx         (~35 MB)
├── vector_estimator.int8.onnx     (~75 MB)
├── vocoder.int8.onnx              (~25 MB)
├── tts.json                       (~8 KB)
├── unicode_indexer.bin            (~256 KB)
└── voice.bin                      (~505 KB)

If the assets directory doesn't exist, create it:

mkdir -p android/app/src/main/assets

3. Rebuild

cd android && ./gradlew clean && cd ..
npx react-native run-android

Usage

import SherpaTts from 'react-native-sherpa-tts';

// 1. Init (once, takes 1–3 seconds to load models)
await SherpaTts.init({ lang: 'zh' });

// 2a. Streaming playback — audio starts almost immediately
await SherpaTts.speak('你好世界！今天天气真不错。', { speed: 1.0 });

// 2b. Or generate to file — returns path when done
const { filePath, duration } = await SherpaTts.synthesize('Hello world');

// 3. Stop playback mid-stream
await SherpaTts.stop();

// 4. Release resources (optional — call before app exit)
await SherpaTts.release();

Events

// Listen for speak completion
const sub = SherpaTts.addListener('onSpeakEnd', ({ filePath, duration }) => {
  console.log(`Playback finished: ${duration}s → ${filePath}`);
});

// Listen for errors
SherpaTts.addListener('onSherpaTtsError', ({ context, message }) => {
  console.error(`[${context}] ${message}`);
});

// Unsubscribe
sub.remove();

API

| Method | Returns | Description | |--------|---------|-------------| | init(options?) | Promise<void> | Load models from assets (~1-3s) | | synthesize(text, options?) | Promise<AudioResult> | Generate WAV, returns file path | | speak(text, options?) | Promise<AudioResult> | Stream + play in real-time | | stop() | Promise<void> | Stop current speak() | | release() | Promise<void> | Free memory | | getState() | Promise<string> | Current engine state | | addListener(event, fn) | { remove() } | Subscribe to events |

Options

interface TtsInitOptions {
  modelDir?: string;  // default: 'sherpa-onnx-supertonic-3-tts-int8-2026-05-11'
  lang?: TtsLanguage; // default: 'en' — 31 languages supported
}

interface TtsSynthesizeOptions {
  speed?: number;     // default: 1.0
  lang?: TtsLanguage; // default: uses init lang
}

Supported Languages

en ko ja ar bg cs da de el es et fi fr hi hr hu id it lt lv nl pl pt ro ru sk sl sv tr uk vi

Architecture

JS (src/index.ts)
  ↓ React Native Bridge
Kotlin (SherpaTtsModule.kt)
  ↓ JNI call
C++ (libsherpa-onnx-jni.so)
  ↓ ONNX Runtime
Supertonic 3 ONNX models → PCM audio → AudioTrack / WAV file

License

MIT