@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.

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 |