cordova-plugin-capgo-speech-synthesis
v1.1.1
Published
Native text-to-speech for Cordova on Android, iOS and browser.
Downloads
544
Maintainers
Readme
Table of Contents
Cordova Speech Synthesis
Cordova port of Capgo's Capacitor speech synthesis plugin. It provides text-to-speech on Android, iOS and Cordova's browser platform while retaining the source plugin's method names, options, result shapes and event payloads.
The source implementation is maintained at Capgo's Capacitor speech synthesis plugin. This port retains the source plugin's MPL-2.0 licence and attribution.
Feature comparison
| Feature | This Cordova fork | Original Capgo Capacitor plugin |
| --- | --- | --- |
| Core speech synthesis | Cordova on Android, iOS and browser; supports speech options, voices, languages and native file synthesis. | Capacitor on Android, iOS and Web; supports the same core speech and voice features. |
| Android pause/resume | Supported. Uses app-owned PCM output when available; otherwise resumes by re-synthesizing from the last reported word boundary, which can repeat or skip a small fragment. | Not supported on Android. |
| Android background playback | Uses a media-playback foreground service and media notification while speech is active. | No plugin-managed media-playback foreground service or notification. |
| Bluetooth headset and lock-screen controls | Android and iOS publish native media-session controls for play, pause and stop. Audio follows the operating system's selected output route. | No plugin-provided media-session or remote controls. |
| Android audio interruptions | Requests transient audio focus, pauses speech when focus is temporarily lost, and resumes when focus returns. | Does not explicitly manage Android audio focus; behavior is left to the TTS engine and system. |
| iOS audio interruptions | Pauses speech and updates playback state when an audio interruption begins; automatically resumes only when iOS recommends resumption. | Uses native synthesizer behavior without this plugin's interruption-state recovery. |
| iOS pause/resume | Supported through AVSpeechSynthesizer pause/continue. | Supported through AVSpeechSynthesizer pause/continue. |
| Playback-state API | Provides getPlaybackState() and the playbackStateChange event. | Not exposed by the upstream API. |
Install
From a Cordova application:
cordova plugin add cordova-plugin-capgo-speech-synthesisThe API is exposed at cordova.plugins.speechSynthesis. Wait for Cordova's deviceready event before calling it:
document.addEventListener('deviceready', async function () {
const speech = cordova.plugins.speechSynthesis;
await speech.initialize();
const { voices } = await speech.getVoices();
console.log('Available voices:', voices);
const listener = await speech.addListener('end', function (event) {
console.log('Finished:', event.utteranceId);
});
await speech.speak({
text: 'Hello, Cornwall!',
language: 'en-GB',
rate: 1,
pitch: 1,
volume: 1,
queueStrategy: 'Add',
});
// Later, when the event is no longer needed:
await listener.remove();
});API
All methods return Promises. addListener() resolves to a handle with a remove() method. removeAllListeners() removes all event subscriptions registered through this API.
| Method | Result |
| --- | --- |
| speak(options) | { utteranceId } |
| synthesizeToFile(options) | { filePath, utteranceId } |
| cancel() | void |
| pause() / resume() | void |
| isSpeaking() | { isSpeaking } |
| getPlaybackState() | { state, utteranceId? } |
| isAvailable() | { isAvailable } |
| getVoices() | { voices } |
| getLanguages() | { languages } |
| isLanguageAvailable({ language }) | { isAvailable } |
| isVoiceAvailable({ voiceId }) | { isAvailable } |
| initialize() | void |
| activateAudioSession({ category }) | void |
| deactivateAudioSession() | void |
| getPluginVersion() | { version } |
| addListener(eventName, callback) | PluginListenerHandle |
| removeAllListeners() | void |
SpeakOptions contains a required text string and optional language, voiceId, pitch, rate, volume and queueStrategy ('Add' or 'Flush', default 'Add'). Voice records contain id, name, language, and optional gender, isNetworkConnectionRequired and default.
The event names are start and end (each with utteranceId), boundary (with utteranceId, charIndex and optional charLength), error (with utteranceId and error), and playbackStateChange (with state and optional utteranceId). Playback states are idle, speaking, and paused. isSpeaking() remains the existing platform-specific boolean query; use getPlaybackState() when the distinction between paused, idle, and speaking matters.
Platform behaviour
- Android uses the system
TextToSpeechengine and requests transient audio focus while speaking, allowing other audio apps to pause; focus is released on pause, stop, and completion, and reacquired on resume.initialize()resolves when the engine reports ready, so availability and voice queries can safely follow it. On Android 7.0+, synthesized PCM is rendered through an app-owned audio track when the TTS engine provides audio callbacks, keeping Android's active audio player and media session associated with the same app for headset media-button routing. PCM callbacks enqueue audio promptly while a Cordova worker writes it to the track, avoiding blocking the TTS service; pending PCM buffering is bounded to 4 MiB. Before ending the utterance, the plugin waits for Android's best-effort output timestamp to reach the final PCM frames, with a bounded playback-head fallback, then allows a short output-drain interval. Pause retains that audio track and the in-progress synthesis stream, so resume continues from the actual playback position without depending on text-range callbacks. If PCM callbacks are unavailable or their byte count does not match the completed WAV payload, playback falls back to the TTS engine's own output; Android may then be unable to route headset media buttons to the app session, and pause/resume re-synthesises text from the last reported word-range position when available. Background speech uses an Android media-playback foreground service and media notification. If Android denies the foreground-service start, speech can continue but the plugin emits anerrorevent and background media controls may be unavailable. - iOS uses
AVSpeechSynthesizerand supports native pause/continue. On iOS 27 and later, the plugin observes audio-session lifecycle and resumption notifications; on earlier versions, it observes interruption begin/end notifications. Speech changes topausedwhen an interruption begins and resumes only when iOS recommends resumption. Otherwise it remains paused and can be resumed through the API or media controls. Audio-session category controls are available there; usePlaybackfor background speech, notAmbient. Background playback requires the host app'sUIBackgroundModesto includeaudio; this plugin's example app configuration includes it. - Browser uses the Web Speech API and waits briefly for asynchronously loaded voices during initialization.
synthesizeToFile()is unsupported and rejects with an error. Audio-session controls are no-ops. getPluginVersion()returns the plugin package version on native platforms and'web'in the browser.
Bluetooth headsets
When speech is active, Android and iOS publish native media-session controls for paired Bluetooth headsets, earbuds, lock screens, and system media controls. TTS audio follows the operating system's selected output route. Headset hardware volume buttons adjust system/media output volume; SpeakOptions.volume remains a separate per-utterance loudness value.
This is not a BLE GATT peripheral. The phone does not advertise a custom service, and the plugin defines no BLE characteristics or Bluetooth scan/connect/advertise permissions. A separate BLE controller that connects directly to the phone would require a different GATT design.
Manual headset smoke test
On a physical Android or iOS device, pair a headset through system settings, start a long utterance in the example app, and verify that the headset can pause, resume, and stop speech. Trigger an audio interruption, such as an incoming call, and check that playback state changes to paused; after the interruption, verify automatic resumption only when the system recommends it, and verify manual resume otherwise. Let an utterance run to completion and confirm its final word finishes before the end event. Repeat with the app backgrounded and the screen locked, then adjust the headset's volume buttons and confirm they change system/media volume. Check that playbackStateChange reports transitions and that SpeakOptions.volume remains per-utterance. On Android, allow for a small repeat or skip at the resumed word boundary.
Development
Run the focused API and browser-proxy tests with:
npm testexample-app/ is a separate Cordova application for local plugin installation and platform smoke testing.
Its iOS deployment target is 15.0 to match current Xcode SDK support.
Install its dependencies from example-app/ before preparing or building a platform; this includes the
cordova-ios package required by Cordova's generated iOS API loader.
To test the local source in that app, package the plugin and extract the archive to a temporary directory inside the example. This avoids a local npm symlink back into the parent package, which would otherwise recursively include the example app:
cd example-app
npm pack .. --pack-destination .
mkdir -p plugin-under-test
tar -xzf cordova-plugin-capgo-speech-synthesis-1.1.0.tgz -C plugin-under-test --strip-components=1
cordova plugin add ./plugin-under-test --nosaveRegenerate the archive after changing the plugin. Cordova CLI treats the example as a standalone project because example-app/platforms/.gitkeep marks its project root; generated platform directories and the temporary plugin package are ignored by Git.
