Skip to main content
Create a TTS engine instance for batch (one-shot) speech synthesis. This is ideal for generating complete audio from text in a single operation. For streaming synthesis with incremental chunks, use createStreamingTTS() instead. 
function createTTS(
  options: TTSInitializeOptions | ModelPathConfig
): Promise<TtsEngine>

​
Parameters

​
options
TTSInitializeOptions | ModelPathConfig
required
Initialization options or a model path configuration.

​
Returns

​
Promise<TtsEngine>
TtsEngine
A promise that resolves to a TTS engine instance.

​
Examples

​
Basic Usage

import { createTTS, assetModelPath } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-piper-en_US-lessac-medium'),
});

const audio = await tts.generateSpeech('Hello, world!');
console.log('Generated samples:', audio.samples.length);
console.log('Sample rate:', audio.sampleRate);

await tts.destroy();

​
With Model Type and Options

import { createTTS, assetModelPath } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-piper-en'),
  modelType: 'vits',
  modelOptions: {
    vits: {
      noiseScale: 0.667,
      noiseScaleW: 0.8,
      lengthScale: 1.0,
    },
  },
  numThreads: 4,
});

const audio = await tts.generateSpeech('Welcome to React Native Sherpa ONNX!');
await tts.destroy();

​
Multi-Speaker Model

import { createTTS, assetModelPath } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-model-multi-speaker'),
});

const modelInfo = await tts.getModelInfo();
console.log('Number of speakers:', modelInfo.numSpeakers);

// Generate with different speakers
const audio1 = await tts.generateSpeech('Hello', { sid: 0 });
const audio2 = await tts.generateSpeech('Hello', { sid: 1 });
const audio3 = await tts.generateSpeech('Hello', { sid: 2 });

await tts.destroy();

​
With Speed Control

import { createTTS, assetModelPath } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-piper-en'),
});

// Generate at different speeds
const normalSpeed = await tts.generateSpeech('Hello world', { speed: 1.0 });
const slower = await tts.generateSpeech('Hello world', { speed: 0.75 });
const faster = await tts.generateSpeech('Hello world', { speed: 1.5 });

await tts.destroy();

​
With Timestamps

import { createTTS, assetModelPath } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-piper-en'),
});

const result = await tts.generateSpeechWithTimestamps(
  'The quick brown fox jumps over the lazy dog.'
);

console.log('Audio samples:', result.samples.length);
console.log('Subtitles:', result.subtitles);
// [
//   { text: 'The', start: 0.0, end: 0.2 },
//   { text: 'quick', start: 0.2, end: 0.5 },
//   ...
// ]

await tts.destroy();

​
Voice Cloning with Pocket TTS

import { createTTS, fileModelPath } from 'react-native-sherpa-onnx/tts';
import { readFile } from '@dr.pogodin/react-native-fs';

const tts = await createTTS({
  modelPath: fileModelPath('/path/to/pocket-tts-model'),
  modelType: 'pocket',
});

// Load reference audio (PCM float samples)
const referenceAudio = await loadAudioSamples('reference.wav');

const audio = await tts.generateSpeech(
  'This will sound like the reference voice.',
  {
    referenceAudio: {
      samples: referenceAudio.samples,
      sampleRate: referenceAudio.sampleRate,
    },
    referenceText: 'The transcript of the reference audio.',
    numSteps: 10,
  }
);

await tts.destroy();

​
Save to File

import { createTTS, assetModelPath, saveAudioToFile } from 'react-native-sherpa-onnx/tts';
import { DocumentDirectoryPath } from '@dr.pogodin/react-native-fs';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-piper-en'),
});

const audio = await tts.generateSpeech('Save this to a file.');

const outputPath = `${DocumentDirectoryPath}/output.wav`;
await saveAudioToFile(audio, outputPath);
console.log('Saved to:', outputPath);

await tts.destroy();

​
Update Parameters at Runtime

import { createTTS, assetModelPath } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: assetModelPath('models/vits-piper-en'),
  modelType: 'vits',
  modelOptions: {
    vits: { noiseScale: 0.667 },
  },
});

const audio1 = await tts.generateSpeech('First generation.');

// Update parameters
await tts.updateParams({
  modelType: 'vits',
  modelOptions: {
    vits: {
      noiseScale: 0.9,
      lengthScale: 1.2,
    },
  },
});

const audio2 = await tts.generateSpeech('Second generation with new params.');

await tts.destroy();

​
detectTtsModel()

Detect TTS model type without initializing the engine. 
function detectTtsModel(
  modelPath: ModelPathConfig,
  options?: { modelType?: TTSModelType }
): Promise<{
  success: boolean;
  detectedModels: Array<{ type: string; modelDir: string }>;
  modelType?: string;
}>

​
Example

import { detectTtsModel, assetModelPath } from 'react-native-sherpa-onnx/tts';

const result = await detectTtsModel(
  assetModelPath('models/vits-piper-en')
);

if (result.success) {
  console.log('Detected type:', result.modelType);
}

​
saveAudioToFile()

Save generated audio to a WAV file. 
function saveAudioToFile(
  audio: GeneratedAudio,
  filePath: string
): Promise<string>

​
saveAudioToContentUri()

Android only: Save audio via Storage Access Framework. 
function saveAudioToContentUri(
  audio: GeneratedAudio,
  directoryUri: string,
  filename: string
): Promise<string>

​
shareAudioFile()

Share a TTS audio file (Android). 
function shareAudioFile(
  fileUri: string,
  mimeType?: string
): Promise<void>

​
saveTextToContentUri()

Save text content to Android’s MediaStore (Android only). 
function saveTextToContentUri(
  text: string,
  displayName: string,
  mimeType?: string
): Promise<string>
​
text
string
required
Text content to save
​
displayName
string
required
Display name for the saved file
​
mimeType
string
MIME type (default: ‘text/plain’)
Returns a promise resolving to the content URI.

​
copyContentUriToCache()

Copy a file from a content URI to the app’s cache directory (Android only). 
function copyContentUriToCache(
  contentUri: string,
  cacheFileName: string
): Promise<string>
​
contentUri
string
required
Source content URI
​
cacheFileName
string
required
Destination filename in cache
Returns a promise resolving to the cache file path.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us