Skip to main content
Breaking Changes in 0.3.0If you are upgrading from an earlier version to 0.3.0, plan for the following migration steps. The SDK has been restructured with an instance-based API and improved type safety.

​
Instance-Based API (TTS + STT)

TTS and STT now use an instance-based factory pattern instead of module-level singletons. Each call to createTTS() / createSTT() returns an independent engine instance.
Important: You must call .destroy() when done to free native resources.

​
Text-to-Speech (TTS)

import { initializeTTS, generateSpeech, unloadTTS } from 'react-native-sherpa-onnx/tts';

await initializeTTS({ modelPath: { type: 'asset', path: 'models/vits' } });
const audio = await generateSpeech('Hello');
await unloadTTS();

​
Speech-to-Text (STT)

import { initializeSTT, transcribeFile, unloadSTT } from 'react-native-sherpa-onnx/stt';

await initializeSTT({ modelPath: { type: 'asset', path: 'models/whisper' } });
const result = await transcribeFile('/audio.wav');
await unloadSTT();

​
Speech-to-Text Changes

​
transcribeFile Return Type

transcribeFile now returns a full SttRecognitionResult object instead of just a string. 
const text: string = await transcribeFile(path);
For text only, use (await stt.transcribeFile(path)).text

​
Hotwords Support

createSTT now supports two additional optional options:
  • hotwordsFile (string): Path to hotwords file
  • hotwordsScore (number): Default boost score for hotwords
See the Hotwords Guide for details.

​
Native Method Renaming

The native TurboModule methods were renamed:
  • initializeSherpaOnnx → initializeStt
  • unloadSherpaOnnx → unloadStt
This only affects you if you’re calling the TurboModule directly. Use the high-level API instead.

​
Removed Deprecated Type

TranscriptionResult has been removed. Use SttRecognitionResult instead (same shape).

​
Text-to-Speech Changes

​
Model-Specific Options

Init and update no longer use flat noiseScale, noiseScaleW, and lengthScale on the options object. Use modelOptions instead, with one block per model type.

​
Initialization

await initializeTTS({
  modelPath: { type: 'asset', path: 'models/vits' },
  modelType: 'vits',
  noiseScale: 0.667,
  noiseScaleW: 0.8,
  lengthScale: 1.0,
});

​
Updating Parameters

await updateTtsParams({
  noiseScale: 0.7,
  lengthScale: 1.2,
});

​
Model Option Types

New types exported from the TTS module:
  • TtsModelOptions
  • TtsVitsModelOptions
  • TtsMatchaModelOptions
  • TtsKokoroModelOptions
  • TtsKittenModelOptions
  • TtsPocketModelOptions
See the TTS API documentation for details.

​
Instance-Bound Methods

If you call the TurboModule directly, all instance-bound methods now take instanceId as the first parameter.
Example: 
// Direct TurboModule call (not recommended)
const result = await RNSherpaOnnxTtsModule.generateSpeech(instanceId, text, options);

// Use the high-level API instead
const result = await tts.generateSpeech(text, options);

​
Removed Deprecated Type

SynthesisOptions has been removed. Use TtsGenerationOptions instead (same shape).

​
Migration Checklist

1

Update STT initialization

Replace initializeSTT / unloadSTT with createSTT / stt.destroy()
2

Update TTS initialization

Replace initializeTTS / unloadTTS with createTTS / tts.destroy()
3

Update transcribeFile usage

Change const text = await transcribeFile(path) to const result = await stt.transcribeFile(path); const text = result.text
4

Update TTS model options

Move flat noiseScale, noiseScaleW, lengthScale to nested modelOptions.vits (or appropriate model type)
5

Update method calls

Change module-level function calls to instance methods:
  • generateSpeech(text) → tts.generateSpeech(text)
  • transcribeFile(path) → stt.transcribeFile(path)
6

Add destroy calls

Ensure all createSTT() and createTTS() instances call .destroy() when done
7

Update type imports

Replace TranscriptionResult with SttRecognitionResultReplace SynthesisOptions with TtsGenerationOptions

​
Example: Complete Migration

import { initializeSTT, transcribeFile, unloadSTT } from 'react-native-sherpa-onnx/stt';
import { initializeTTS, generateSpeech, unloadTTS } from 'react-native-sherpa-onnx/tts';

// STT
await initializeSTT({
  modelPath: { type: 'asset', path: 'models/whisper' },
  modelType: 'whisper',
});
const text = await transcribeFile('/audio.wav');
console.log(text);
await unloadSTT();

// TTS
await initializeTTS({
  modelPath: { type: 'asset', path: 'models/vits' },
  modelType: 'vits',
  noiseScale: 0.667,
  lengthScale: 1.0,
});
const audio = await generateSpeech('Hello world');
await unloadTTS();

​
See Also

STT API

Complete Speech-to-Text API reference

TTS API

Complete Text-to-Speech API reference

Model Setup

Learn how to set up and manage models

Hotwords

Contextual biasing for better accuracy

Build docs developers (and LLMs) love

Get started for freeTalk to us