@capgo/capacitor-speech-synthesis
June 16, 2026 · View on GitHub
Synthesize speech from text with full control over language, voice, pitch, rate, and volume.
Why Speech Synthesis?
A free, open-source alternative providing complete text-to-speech capabilities:
- Cross-platform - Works on iOS, Android, and Web with consistent API
- Full voice control - Choose from system voices, adjust pitch, rate, and volume
- Event-driven - Listen to speech events (start, end, word boundaries, errors)
- File export - Save speech to audio files on iOS and Android
- Modern APIs - Uses AVSpeechSynthesizer (iOS), TextToSpeech (Android), and Web Speech API
- Production-ready - Complete TypeScript support with comprehensive documentation
Perfect for accessibility features, language learning apps, audiobook players, and any app needing text-to-speech.
Compatibility
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
Install
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
Then use the following prompt:
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-speech-synthesis` plugin in my project.
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
npm install @capgo/capacitor-speech-synthesis
npx cap sync
API
speak(...)synthesizeToFile(...)cancel()pause()resume()isSpeaking()isAvailable()getVoices()getLanguages()isLanguageAvailable(...)isVoiceAvailable(...)initialize()activateAudioSession(...)deactivateAudioSession()getPluginVersion()addListener('start', ...)addListener('end', ...)addListener('boundary', ...)addListener('error', ...)removeAllListeners()- Interfaces
Speech Synthesis Plugin for synthesizing speech from text.
speak(...)
speak(options: SpeakOptions) => Promise<SpeakResult>
Speaks the given text with specified options. The utterance is added to the speech queue.
| Param | Type | Description |
|---|---|---|
options | SpeakOptions | - The speech options including text and voice settings |
Returns: Promise<SpeakResult>
Since: 1.0.0
synthesizeToFile(...)
synthesizeToFile(options: SpeakOptions) => Promise<SynthesizeToFileResult>
Synthesizes speech to an audio file (Android/iOS only). Returns the file path where the audio was saved.
| Param | Type | Description |
|---|---|---|
options | SpeakOptions | - The speech options including text and voice settings |
Returns: Promise<SynthesizeToFileResult>
Since: 1.0.0
cancel()
cancel() => Promise<void>
Cancels all queued utterances and stops current speech.
Since: 1.0.0
pause()
pause() => Promise<void>
Pauses speech immediately.
Since: 1.0.0
resume()
resume() => Promise<void>
Resumes paused speech.
Since: 1.0.0
isSpeaking()
isSpeaking() => Promise<{ isSpeaking: boolean; }>
Checks if speech synthesis is currently speaking.
Returns: Promise<{ isSpeaking: boolean; }>
Since: 1.0.0
isAvailable()
isAvailable() => Promise<{ isAvailable: boolean; }>
Checks if speech synthesis is available on the device.
Returns: Promise<{ isAvailable: boolean; }>
Since: 1.0.0
getVoices()
getVoices() => Promise<{ voices: VoiceInfo[]; }>
Gets all available voices.
Returns: Promise<{ voices: VoiceInfo[]; }>
Since: 1.0.0
getLanguages()
getLanguages() => Promise<{ languages: string[]; }>
Gets all available languages.
Returns: Promise<{ languages: string[]; }>
Since: 1.0.0
isLanguageAvailable(...)
isLanguageAvailable(options: IsLanguageAvailableOptions) => Promise<{ isAvailable: boolean; }>
Checks if a specific language is available.
| Param | Type | Description |
|---|---|---|
options | IsLanguageAvailableOptions | - The language to check |
Returns: Promise<{ isAvailable: boolean; }>
Since: 1.0.0
isVoiceAvailable(...)
isVoiceAvailable(options: IsVoiceAvailableOptions) => Promise<{ isAvailable: boolean; }>
Checks if a specific voice is available.
| Param | Type | Description |
|---|---|---|
options | IsVoiceAvailableOptions | - The voice ID to check |
Returns: Promise<{ isAvailable: boolean; }>
Since: 1.0.0
initialize()
initialize() => Promise<void>
Initializes the speech synthesis engine (iOS optimization). This can reduce latency for the first speech request.
Since: 1.0.0
activateAudioSession(...)
activateAudioSession(options: ActivateAudioSessionOptions) => Promise<void>
Activates the audio session with a specific category (iOS only).
| Param | Type | Description |
|---|---|---|
options | ActivateAudioSessionOptions | - The audio session category |
Since: 1.0.0
deactivateAudioSession()
deactivateAudioSession() => Promise<void>
Deactivates the audio session (iOS only).
Since: 1.0.0
getPluginVersion()
getPluginVersion() => Promise<{ version: string; }>
Gets the native plugin version.
Returns: Promise<{ version: string; }>
Since: 1.0.0
addListener('start', ...)
addListener(eventName: 'start', listenerFunc: (event: UtteranceEvent) => void) => Promise<PluginListenerHandle>
Listens for when an utterance starts speaking.
| Param | Type | Description |
|---|---|---|
eventName | 'start' | - The event name ('start') |
listenerFunc | (event: UtteranceEvent) => void | - The callback function |
Returns: Promise<PluginListenerHandle>
Since: 1.0.0
addListener('end', ...)
addListener(eventName: 'end', listenerFunc: (event: UtteranceEvent) => void) => Promise<PluginListenerHandle>
Listens for when an utterance finishes speaking.
| Param | Type | Description |
|---|---|---|
eventName | 'end' | - The event name ('end') |
listenerFunc | (event: UtteranceEvent) => void | - The callback function |
Returns: Promise<PluginListenerHandle>
Since: 1.0.0
addListener('boundary', ...)
addListener(eventName: 'boundary', listenerFunc: (event: BoundaryEvent) => void) => Promise<PluginListenerHandle>
Listens for word boundaries during speech.
| Param | Type | Description |
|---|---|---|
eventName | 'boundary' | - The event name ('boundary') |
listenerFunc | (event: BoundaryEvent) => void | - The callback function |
Returns: Promise<PluginListenerHandle>
Since: 1.0.0
addListener('error', ...)
addListener(eventName: 'error', listenerFunc: (event: ErrorEvent) => void) => Promise<PluginListenerHandle>
Listens for synthesis errors.
| Param | Type | Description |
|---|---|---|
eventName | 'error' | - The event name ('error') |
listenerFunc | (event: ErrorEvent) => void | - The callback function |
Returns: Promise<PluginListenerHandle>
Since: 1.0.0
removeAllListeners()
removeAllListeners() => Promise<void>
Removes all event listeners.
Since: 1.0.0
Interfaces
SpeakResult
Result from speaking text.
| Prop | Type | Description | Since |
|---|---|---|---|
utteranceId | string | Unique identifier for this utterance. | 1.0.0 |
SpeakOptions
Options for speaking text.
| Prop | Type | Description | Since |
|---|---|---|---|
text | string | The text to speak. | 1.0.0 |
language | string | The BCP-47 language tag (e.g., 'en-US', 'es-ES'). | 1.0.0 |
voiceId | string | The voice identifier to use. | 1.0.0 |
pitch | number | The pitch of the voice (0.5 to 2.0, default: 1.0). | 1.0.0 |
rate | number | The speaking rate (0.1 to 10.0, default: 1.0). | 1.0.0 |
volume | number | The volume (0.0 to 1.0, default: 1.0). | 1.0.0 |
queueStrategy | 'Add' | 'Flush' | The queue strategy: 'Add' to append or 'Flush' to replace queue. Default: 'Add' | 1.0.0 |
SynthesizeToFileResult
Result from synthesizing to file.
| Prop | Type | Description | Since |
|---|---|---|---|
filePath | string | The file path where audio was saved. | 1.0.0 |
utteranceId | string | Unique identifier for this utterance. | 1.0.0 |
VoiceInfo
Information about a voice.
| Prop | Type | Description | Since |
|---|---|---|---|
id | string | Unique voice identifier. | 1.0.0 |
name | string | Display name of the voice. | 1.0.0 |
language | string | BCP-47 language code. | 1.0.0 |
gender | 'male' | 'female' | 'neutral' | Gender of the voice (iOS only). | 1.0.0 |
isNetworkConnectionRequired | boolean | Whether this voice requires a network connection. | 1.0.0 |
default | boolean | Whether this is the default voice (Web only). | 1.0.0 |
IsLanguageAvailableOptions
Options for checking language availability.
| Prop | Type | Description | Since |
|---|---|---|---|
language | string | The BCP-47 language code to check. | 1.0.0 |
IsVoiceAvailableOptions
Options for checking voice availability.
| Prop | Type | Description | Since |
|---|---|---|---|
voiceId | string | The voice ID to check. | 1.0.0 |
ActivateAudioSessionOptions
Options for activating the audio session (iOS only).
| Prop | Type | Description | Since |
|---|---|---|---|
category | 'Ambient' | 'Playback' | The audio session category. - 'Ambient': Mixes with other audio - 'Playback': Stops other audio | 1.0.0 |
PluginListenerHandle
| Prop | Type |
|---|---|
remove | () => Promise<void> |
UtteranceEvent
Event emitted when utterance starts or ends.
| Prop | Type | Description | Since |
|---|---|---|---|
utteranceId | string | The utterance identifier. | 1.0.0 |
BoundaryEvent
Event emitted at word boundaries.
| Prop | Type | Description | Since |
|---|---|---|---|
utteranceId | string | The utterance identifier. | 1.0.0 |
charIndex | number | The character index in the text. | 1.0.0 |
charLength | number | The character length of the current word. | 1.0.0 |
ErrorEvent
Event emitted on synthesis error.
| Prop | Type | Description | Since |
|---|---|---|---|
utteranceId | string | The utterance identifier. | 1.0.0 |
error | string | The error message. | 1.0.0 |