Skip to main content

​
createTTS()

Creates a TTS (Text-to-Speech) engine instance for batch speech generation. Use this for one-shot synthesis where you generate complete audio files at once. For streaming synthesis with chunk callbacks, use createStreamingTTS() instead. 
function createTTS(
  options: TTSInitializeOptions | ModelPathConfig
): Promise<TtsEngine>

​
Parameters

​
options
TTSInitializeOptions | ModelPathConfig
required
TTS initialization options. Can be either:
  • Full TTSInitializeOptions object with model path and configuration
  • Simple ModelPathConfig for quick initialization with defaults
See Configuration for details.

​
Returns

Returns a Promise that resolves to a TtsEngine instance.

​
Example

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

// Initialize TTS with full options
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/vits-piper-en' },
  modelType: 'vits',
  numThreads: 4,
  modelOptions: {
    vits: {
      noiseScale: 0.667,
      lengthScale: 1.0,
    },
  },
});

// Generate speech
const audio = await tts.generateSpeech('Hello, world!');
console.log(`Generated ${audio.samples.length} samples at ${audio.sampleRate}Hz`);

// Clean up
await tts.destroy();

​
Quick initialization

// Simple initialization with just a model path
const tts = await createTTS({
  type: 'asset',
  path: 'models/vits-piper-en',
});

​
TtsEngine

The TTS engine interface returned by createTTS(). Provides methods for batch speech synthesis and model information.

​
Properties

​
instanceId
string
Unique identifier for this TTS engine instance.

​
Methods

​
generateSpeech()

Generates complete audio for the given text. 
generateSpeech(
  text: string,
  options?: TtsGenerationOptions
): Promise<GeneratedAudio>
​
text
string
required
The text to synthesize into speech.
​
options
TtsGenerationOptions
Optional generation parameters (speaker ID, speed, voice cloning, etc.).See Configuration for details.
Returns: Promise<GeneratedAudio> - Generated audio samples and sample rate. Example: 
const audio = await tts.generateSpeech('Hello world', {
  sid: 0,
  speed: 1.2,
});

​
generateSpeechWithTimestamps()

Generates audio with word-level timestamps for subtitles. 
generateSpeechWithTimestamps(
  text: string,
  options?: TtsGenerationOptions
): Promise<GeneratedAudioWithTimestamps>
​
text
string
required
The text to synthesize into speech.
​
options
TtsGenerationOptions
Optional generation parameters.
Returns: Promise<GeneratedAudioWithTimestamps> - Audio with subtitle/timestamp metadata. Example: 
const result = await tts.generateSpeechWithTimestamps('Hello world');

console.log('Audio:', result.samples.length, 'samples');
console.log('Timestamps:');
result.subtitles.forEach((item) => {
  console.log(`  ${item.text}: ${item.start}s - ${item.end}s`);
});

​
updateParams()

Updates model-specific parameters at runtime without reloading the model. 
updateParams(options: TtsUpdateOptions): Promise<{
  success: boolean;
  detectedModels: Array<{ type: string; modelDir: string }>;
}>
​
options
TtsUpdateOptions
required
Parameters to update (noise scale, length scale, etc.).See Configuration for details.
Returns: Promise resolving to update result with success status. Example: 
await tts.updateParams({
  modelType: 'vits',
  modelOptions: {
    vits: {
      noiseScale: 0.8,
      lengthScale: 1.1,
    },
  },
});

​
getModelInfo()

Returns model capabilities (sample rate and number of speakers). 
getModelInfo(): Promise<TTSModelInfo>
Returns: Promise resolving to model information. Example: 
const info = await tts.getModelInfo();
console.log(`Sample rate: ${info.sampleRate}Hz`);
console.log(`Speakers: ${info.numSpeakers}`);

​
getSampleRate()

Returns the sample rate at which the model generates audio. 
getSampleRate(): Promise<number>
Returns: Promise resolving to sample rate in Hz (e.g., 22050, 44100).

​
getNumSpeakers()

Returns the number of speakers/voices available in the model. 
getNumSpeakers(): Promise<number>
Returns: Promise resolving to number of speakers:
  • 0 or 1 = single-speaker model
  • > 1 = multi-speaker model
Example: 
const numSpeakers = await tts.getNumSpeakers();
if (numSpeakers > 1) {
  // Generate with different speakers
  const audio1 = await tts.generateSpeech('Hello', { sid: 0 });
  const audio2 = await tts.generateSpeech('Hello', { sid: 1 });
}

​
destroy()

Releases native resources. Always call this when done to prevent memory leaks. 
destroy(): Promise<void>
Example: 
try {
  const audio = await tts.generateSpeech('Hello');
  // Use audio...
} finally {
  await tts.destroy();
}

​
Utility Functions

​
detectTtsModel()

Detects TTS model type without initializing an engine. Useful for validating models before initialization. 
function detectTtsModel(
  modelPath: ModelPathConfig,
  options?: { modelType?: TTSModelType }
): Promise<{
  success: boolean;
  detectedModels: Array<{ type: string; modelDir: string }>;
  modelType?: string;
}>
​
modelPath
ModelPathConfig
required
Path to the model directory to detect.
​
options.modelType
TTSModelType
Optional hint for model type. Default: 'auto'
Returns: Detection result with model type and directory information. Example: 
import { detectTtsModel } from 'react-native-sherpa-onnx';

const result = await detectTtsModel({
  type: 'asset',
  path: 'models/vits-piper-en',
});

if (result.success) {
  console.log('Detected model type:', result.modelType);
  console.log('Models found:', result.detectedModels);
} else {
  console.error('Model detection failed');
}

​
saveAudioToFile()

Saves generated audio to a WAV file. 
function saveAudioToFile(
  audio: GeneratedAudio,
  filePath: string
): Promise<string>
​
audio
GeneratedAudio
required
The generated audio to save.
​
filePath
string
required
Destination file path (e.g., /path/to/output.wav).
Returns: Promise resolving to the saved file path. Example: 
import { createTTS, saveAudioToFile } from 'react-native-sherpa-onnx';
import RNFS from 'react-native-fs';

const tts = await createTTS({ type: 'asset', path: 'models/vits-piper-en' });
const audio = await tts.generateSpeech('Hello world');

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

await tts.destroy();

​
saveAudioToContentUri() (Android only)

Saves audio to a file using Android Storage Access Framework (SAF). 
function saveAudioToContentUri(
  audio: GeneratedAudio,
  directoryUri: string,
  filename: string
): Promise<string>
​
audio
GeneratedAudio
required
The generated audio to save.
​
directoryUri
string
required
SAF directory content URI.
​
filename
string
required
Filename for the saved file (e.g., "speech.wav").
Returns: Promise resolving to the content URI of the saved file.

​
shareAudioFile()

Shares an audio file using the system share dialog. 
function shareAudioFile(
  fileUri: string,
  mimeType?: string
): Promise<void>
​
fileUri
string
required
File path or content URI to share.
​
mimeType
string
MIME type of the file. Default: 'audio/wav'
Example: 
import { createTTS, saveAudioToFile, shareAudioFile } from 'react-native-sherpa-onnx';
import RNFS from 'react-native-fs';

const tts = await createTTS({ type: 'asset', path: 'models/vits-piper-en' });
const audio = await tts.generateSpeech('Check out this audio!');

const filePath = `${RNFS.CachesDirectoryPath}/share.wav`;
await saveAudioToFile(audio, filePath);
await shareAudioFile(filePath);

await tts.destroy();

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us