@capgo/capacitor-speech-synthesis

Read text aloud in your Capacitor app with native text-to-speech, and control the language, voice, pitch, rate and volume.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-speech-synthesis in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-speech-synthesis to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Speak: speak() with language, voice, pitch, rate, volume and queue strategy.
• Playback control: pause(), resume(), cancel() and isSpeaking(). Pause and resume are not supported on Android.
• Voices and languages: getVoices(), getLanguages(), isLanguageAvailable() and isVoiceAvailable().
• Save to file: synthesizeToFile() writes speech to an audio file on iOS and Android.
• Events: start, end, boundary and error listeners.
• Platforms: iOS, Android and Web. iOS uses AVSpeechSynthesizer, Android uses TextToSpeech. Web uses the Web Speech API.

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

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.

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.

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.

Returns: Promise<{ isAvailable: boolean; }>

Since: 1.0.0

isVoiceAvailable(...)

isVoiceAvailable(options: IsVoiceAvailableOptions) => Promise<{ isAvailable: boolean; }>

Checks if a specific voice is available.

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

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.

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.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('boundary', ...)

addListener(eventName: 'boundary', listenerFunc: (event: BoundaryEvent) => void) => Promise<PluginListenerHandle>

Listens for word boundaries during speech.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('error', ...)

addListener(eventName: 'error', listenerFunc: (event: ErrorEvent) => void) => Promise<PluginListenerHandle>

Listens for synthesis errors.

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.

SpeakOptions

Options for speaking text.

SynthesizeToFileResult

Result from synthesizing to file.

VoiceInfo

Information about a voice.

IsLanguageAvailableOptions

Options for checking language availability.

IsVoiceAvailableOptions

Options for checking voice availability.

ActivateAudioSessionOptions

Options for activating the audio session (iOS only).

PluginListenerHandle

UtteranceEvent

Event emitted when utterance starts or ends.

BoundaryEvent

Event emitted at word boundaries.

ErrorEvent

Event emitted on synthesis error.