@capgo/capacitor-speech-synthesis

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

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 |