npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

cordova-plugin-capgo-speech-synthesis

v1.1.1

Published

Native text-to-speech for Cordova on Android, iOS and browser.

Downloads

544

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-synthesis

The 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 TextToSpeech engine 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 an error event and background media controls may be unavailable.
  • iOS uses AVSpeechSynthesizer and 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 to paused when 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; use Playback for background speech, not Ambient. Background playback requires the host app's UIBackgroundModes to include audio; 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 test

example-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 --nosave

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