Text to Speech

@capacitor-community/text-to-speech

Capacitor community plugin for synthesizing speech from text.

## Maintainers | Maintainer | GitHub | Social | | ---------- | ----------------------------------------- | --------------------------------------------- | | Robin Genz | [robingenz](https://github.com/robingenz) | [@robin_genz](https://twitter.com/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](https://github.com/robingenz/capacitor-plugin-demo) ## Usage ```typescript 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(...)`](#speak) * [`stop()`](#stop) * [`getSupportedLanguages()`](#getsupportedlanguages) * [`getSupportedVoices()`](#getsupportedvoices) * [`isLanguageSupported(...)`](#islanguagesupported) * [`openInstall()`](#openinstall) * [`addListener('onRangeStart', ...)`](#addlisteneronrangestart-) * [Interfaces](#interfaces) * [Enums](#enums) ### speak(...) ```typescript speak(options: TTSOptions) => Promise ``` Starts the TTS engine and plays the desired text. | Param | Type | | ------------- | ------------------------------------------------- | | **`options`** | TTSOptions | -------------------- ### stop() ```typescript stop() => Promise ``` Stops the TTS engine. -------------------- ### getSupportedLanguages() ```typescript getSupportedLanguages() => Promise<{ languages: string[]; }> ``` Returns a list of supported BCP 47 language tags. **Returns:** Promise<{ languages: string[]; }> -------------------- ### getSupportedVoices() ```typescript getSupportedVoices() => Promise<{ voices: SpeechSynthesisVoice[]; }> ``` Returns a list of supported voices. **Returns:** Promise<{ voices: SpeechSynthesisVoice[]; }> -------------------- ### isLanguageSupported(...) ```typescript 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() ```typescript openInstall() => Promise ``` Verifies proper installation and availability of resource files on the system. Only available for Android. -------------------- ### addListener('onRangeStart', ...) ```typescript addListener(eventName: 'onRangeStart', listenerFunc: (info: { start: number; end: number; spokenWord: string; }) => void) => Promise ``` | 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](https://github.com/capacitor-community/text-to-speech/blob/master/CHANGELOG.md). ## License See [LICENSE](https://github.com/capacitor-community/text-to-speech/blob/master/LICENSE).