Maintainers

| Maintainer | GitHub | Social | | ---------- | ----------------------------------------- | --------------------------------------------- | | Robin Genz | robingenz | @robin_genz |

Installation

npm install @capacitor-community/text-to-speech
npx cap sync

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Usage

import { TextToSpeech } from '@capacitor-community/text-to-speech';

const speak = async () => {
  await TextToSpeech.speak({
    text: 'This is a sample text.',
    lang: 'en-US',
    rate: 1.0,
    pitch: 1.0,
    volume: 1.0,
    category: 'ambient',
    queueStrategy: 1
  });
};

const stop = async () => {
  await TextToSpeech.stop();
};

const getSupportedLanguages = async () => {
  const languages = await TextToSpeech.getSupportedLanguages();
};

const getSupportedVoices = async () => {
  const voices = await TextToSpeech.getSupportedVoices();
};

const isLanguageSupported = async (lang: string) => {
  const isSupported = await TextToSpeech.isLanguageSupported({ lang });
};

API

• speak(...)
• stop()
• getSupportedLanguages()
• getSupportedVoices()
• isLanguageSupported(...)
• openInstall()
• addListener('onRangeStart', ...)
• Interfaces
• Enums

speak(...)

speak(options: TTSOptions) => Promise<void>

Starts the TTS engine and plays the desired text.

| Param | Type | | ------------- | ------------------------------------------------- | | options | TTSOptions |

stop()

stop() => Promise<void>

Stops the TTS engine.

getSupportedLanguages()

getSupportedLanguages() => Promise<{ languages: string[]; }>

Returns a list of supported BCP 47 language tags.

Returns: Promise<{ languages: string[]; }>

getSupportedVoices()

getSupportedVoices() => Promise<{ voices: SpeechSynthesisVoice[]; }>

Returns a list of supported voices.

Returns: Promise<{ voices: SpeechSynthesisVoice[]; }>

isLanguageSupported(...)

isLanguageSupported(options: { lang: string; }) => Promise<{ supported: boolean; }>

Checks if a specific BCP 47 language tag is supported.

| Param | Type | | ------------- | ------------------------------ | | options | { lang: string; } |

Returns: Promise<{ supported: boolean; }>

openInstall()

openInstall() => Promise<void>

Verifies proper installation and availability of resource files on the system.

Only available for Android.

addListener('onRangeStart', ...)

addListener(eventName: 'onRangeStart', listenerFunc: (info: { start: number; end: number; spokenWord: string; }) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------- | | eventName | 'onRangeStart' | | listenerFunc | (info: { start: number; end: number; spokenWord: string; }) => void |

Returns: Promise<PluginListenerHandle>

Interfaces

TTSOptions

| Prop | Type | Description | Default | Since | | ------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----- | | text | string | The text that will be synthesised when the utterance is spoken. | | | | lang | string | The language of the utterance. Possible languages can be queried using getSupportedLanguages. | "en-US" | | | rate | number | The speed at which the utterance will be spoken at. | 1.0 | | | pitch | number | The pitch at which the utterance will be spoken at. | 1.0 | | | volume | number | The volume that the utterance will be spoken at. | 1.0 | | | voice | number | The index of the selected voice that will be used to speak the utterance. Possible voices can be queried using getSupportedVoices. | | | | category | string | Select the iOS Audio session category. Possible values: ambient and playback. Use playback to play audio even when the app is in the background. Only available for iOS. | "ambient" | | | queueStrategy | QueueStrategy | Select the strategy to adopt when several requests to speak overlap. | QueueStrategy.Flush | 5.1.0 |

SpeechSynthesisVoice

The SpeechSynthesisVoice interface represents a voice that the system supports.

| Prop | Type | Description | | ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------- | | default | boolean | Specifies whether the voice is the default voice for the current app (true) or not (false). | | lang | string | BCP 47 language tag indicating the language of the voice. | | localService | boolean | Specifies whether the voice is supplied by a local (true) or remote (false) speech synthesizer service. | | name | string | Human-readable name that represents the voice. | | voiceURI | string | Type of URI and location of the speech synthesis service for this voice. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Enums

QueueStrategy

| Members | Value | Description | | ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | | Flush | 0 | Use Flush to stop the current request when a new request is sent. | | Add | 1 | Use Add to buffer the speech request. The request will be executed when all previous requests have been completed. |

Changelog

See CHANGELOG.md.

License

See LICENSE.