API reference
Complete reference for the Speech class, its types, and the HighlightedText component.
Import
The library exports the Speech class (default) and the HighlightedText component:
import Speech, {HighlightedText} from '@mhpdev/react-native-speech';Speech class methods
| Method | Returns | Platform | Description |
|---|---|---|---|
Speech.speak(text) | Promise<string> | Both | Speaks text with the global options. Resolves with the utterance ID when queued. |
Speech.speak(text, options) | Promise<string> | Both | Speaks text with per-utterance options overriding the global settings. Resolves with the utterance ID. |
Speech.speakWithOptions(text, options) | Promise<string> | Both | Deprecated. Use Speech.speak(text, options) instead. |
Speech.stop() | Promise<void> | Both | Immediately stops any ongoing or queued speech. |
Speech.pause() | Promise<boolean> | Both | Pauses speech at the next word boundary. Android requires API 26+. Resolves false if nothing to pause. |
Speech.resume() | Promise<boolean> | Both | Resumes paused speech. Android requires API 26+. Resolves false if nothing to resume. |
Speech.isSpeaking() | Promise<boolean> | Both | Resolves true if speech is active (speaking or paused). |
Speech.configure(options) | void | Both | Sets the global options for all subsequent speak() calls. See VoiceOptions. |
Speech.reset() | void | Both | Resets all global speech options to their defaults. |
Speech.getAvailableVoices(language?) | Promise<VoiceProps[]> | Both | Lists available voices, optionally filtered by a language code or tag. See VoiceProps. |
Speech.getEngines() | Promise<EngineProps[]> | Android | Lists the installed text-to-speech engines. See EngineProps. |
Speech.setEngine(engineName) | Promise<void> | Android | Sets the text-to-speech engine for all subsequent synthesis. |
Speech.openVoiceDataInstaller() | Promise<void> | Android | Opens the system activity to install or manage TTS voice data. |
Constants
| Constant | Type | Description |
|---|---|---|
Speech.maxInputLength | number | Maximum characters per speak call. Android: from TextToSpeech.getMaxSpeechInputLength. iOS: Number.MAX_VALUE (no system limit). |
Events
Every event callback receives the utterance id and returns a subscription with a remove() method for cleanup.
| Event | Payload | Description |
|---|---|---|
Speech.onStart | {id: string} | Speech started. |
Speech.onFinish | {id: string} | Speech completed. |
Speech.onPause | {id: string} | Speech paused (Android: API 26+). |
Speech.onResume | {id: string} | Speech resumed (Android: API 26+). |
Speech.onStopped | {id: string} | Speech stopped. |
Speech.onProgress | {id: string; location: number; length: number} | Progress with the current position and range length (Android: API 26+). |
Speech.onError | {id: string} | An error occurred during synthesis. |
Types
VoiceOptions
| Property | Type | Description | Platform support |
|---|---|---|---|
language | string? | Language code or IETF BCP 47 language tag (e.g., 'en-US', 'fr-FR') | Both |
volume | number? | Volume level from 0.0 to 1.0 | Both |
voice | string? | Specific voice identifier to use (obtained from getAvailableVoices()) | Both |
pitch | number? | Pitch multiplier: Android 0.1–2.0, iOS 0.5–2.0 | Both |
rate | number? | Speech rate: Android 0.1–2.0, iOS varies based on AVSpeechUtterance limits | Both |
ducking | boolean? | Temporarily lowers audio from other apps while speech is active. Defaults to false | Both |
silentMode | 'obey' | 'respect' | 'ignore' | Controls how speech interacts with the silent switch. Ignored if ducking is true | iOS only |
VoiceProps
| Property | Type | Description |
|---|---|---|
name | string | The name of the voice. |
identifier | string | The unique identifier for the voice. |
language | string | The language code (e.g., 'en-US', 'fr-FR'). |
quality | 'Default' | 'Enhanced' | The quality level of the voice. |
EngineProps
| Property | Type | Description |
|---|---|---|
name | string | The unique system identifier (e.g., "com.google.android.tts"). |
label | string | The human-readable display name (e.g., "Google Text-to-Speech Engine"). |
isDefault | boolean | Whether this is the default engine. |
EventProps
| Property | Type | Description |
|---|---|---|
id | string | The utterance ID. |
ProgressEventProps
Extends EventProps.
| Property | Type | Description |
|---|---|---|
length | number | The text being spoken length. |
location | number | The current position in the spoken text. |
HighlightedTextProps
See the HighlightedText page for the full property table.
Native module
The Turbo Module is registered as RNSpeech. All methods and listeners above are declared in the library's Spec, so they are fully type-safe when written in TypeScript.