Skip to content

Commit

Permalink
refactor!: rename TTSOptions properties (#51)
Browse files Browse the repository at this point in the history 

BREAKING CHANGE: `TTSOptions` properties `locale`, `speechRate`, `pitchRate` renamed to `lang`, `rate`, `pitch`.
  • Loading branch information
@robingenz
robingenz authored Mar 14, 2021
1 parent 2c7d821 commit 83c4370
Show file tree
Hide file tree
Showing 7 changed files with 71 additions and 79 deletions.
52 changes: 21 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,9 @@ import { TextToSpeech } from '@capacitor-community/text-to-speech';
const speak = async () => {
await TextToSpeech.speak({
text: 'This is a sample text.',
locale: 'en_US',
speechRate: 1.0,
pitchRate: 1.0,
lang: 'en_US',
rate: 1.0,
pitch: 1.0,
volume: 1.0,
category: 'ambient',
});
Expand All @@ -99,18 +99,6 @@ const getSupportedLanguages = async () => {
const getSupportedVoices = async () => {
const voices = await TextToSpeech.getSupportedVoices();
};

const setPitchRate = async () => {
await TextToSpeech.setPitchRate({
pitchRate: 1.5,
});
};

const setSpeechRate = async () => {
await TextToSpeech.setSpeechRate({
speechRate: 0.5,
});
};
```

## API
Expand Down Expand Up @@ -189,6 +177,8 @@ openInstall() => Promise<void>

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

Only available for Android.

--------------------


Expand All @@ -197,28 +187,28 @@ Verifies proper installation and availability of resource files on the system.

#### TTSOptions

| Prop | Type | Description |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`text`** | <code>string</code> | Text to be spoken. |
| **`locale`** | <code>string</code> | Language spoken in. Possible languages can be queried using `getSupportedLanguages`. Default: `en-US` |
| **`speechRate`** | <code>number</code> | The speech rate. Default: `1.0` |
| **`pitchRate`** | <code>number</code> | The pitch rate. Default: `1.0` |
| **`volume`** | <code>number</code> | The volume. Default: `1.0` |
| **`voice`** | <code>number</code> | The index of the selected voice. Possible voices can be queried using `getSupportedVoices`. Only available for Web. |
| **`category`** | <code>string</code> | 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. Default: `ambient` |
| Prop | Type | Description |
| -------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`text`** | <code>string</code> | The text that will be synthesised when the utterance is spoken. |
| **`lang`** | <code>string</code> | The language of the utterance. Possible languages can be queried using `getSupportedLanguages`. Default: `en-US`. |
| **`rate`** | <code>number</code> | The speed at which the utterance will be spoken at. Default: `1.0`. |
| **`pitch`** | <code>number</code> | The pitch at which the utterance will be spoken at. Default: `1.0`. |
| **`volume`** | <code>number</code> | The volume that the utterance will be spoken at. Default: `1.0`. |
| **`voice`** | <code>number</code> | The index of the selected voice that will be used to speak the utterance. Possible voices can be queried using `getSupportedVoices`. Only available for Web. |
| **`category`** | <code>string</code> | 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. Default: `ambient`. |


#### SpeechSynthesisVoice

The <a href="#speechsynthesisvoice">SpeechSynthesisVoice</a> interface represents a voice that the system supports.

| Prop | Type | Description |
| ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`default`** | <code>boolean</code> | Specifies whether the voice is the default voice for the current app (`true`) or not (`false`). |
| **`lang`** | <code>string</code> | BCP 47 language tag indicating the language of the voice. Example: `en-US` |
| **`localService`** | <code>boolean</code> | Specifies whether the voice is supplied by a local (`true`) or remote (`false`) speech synthesizer service. |
| **`name`** | <code>string</code> | Human-readable name that represents the voice. Example: `Microsoft Zira Desktop - English (United States)` |
| **`voiceURI`** | <code>string</code> | Type of URI and location of the speech synthesis service for this voice. Example: `urn:moz-tts:sapi:Microsoft Zira Desktop - English (United States)?en-US` |
| Prop | Type | Description |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`default`** | <code>boolean</code> | Specifies whether the voice is the default voice for the current app (`true`) or not (`false`). |
| **`lang`** | <code>string</code> | BCP 47 language tag indicating the language of the voice. Example: `en-US`. |
| **`localService`** | <code>boolean</code> | Specifies whether the voice is supplied by a local (`true`) or remote (`false`) speech synthesizer service. |
| **`name`** | <code>string</code> | Human-readable name that represents the voice. Example: `Microsoft Zira Desktop - English (United States)`. |
| **`voiceURI`** | <code>string</code> | Type of URI and location of the speech synthesis service for this voice. Example: `urn:moz-tts:sapi:Microsoft Zira Desktop - English (United States)?en-US`. |

</docgen-api>

Expand Down
10 changes: 5 additions & 5 deletions android/src/main/java/com/getcapacitor/community/tts/TextToSpeech.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ public void onInit(int status) {

public void speak(
String text,
String locale,
String lang,
float rate,
float pitch,
float volume,
Expand Down Expand Up @@ -71,7 +71,7 @@ public void onError(String utteranceId) {
ttsParams.putSerializable(android.speech.tts.TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID, callbackId);
ttsParams.putSerializable(android.speech.tts.TextToSpeech.Engine.KEY_PARAM_VOLUME, volume);

tts.setLanguage(new Locale(locale));
tts.setLanguage(new Locale(lang));
tts.setSpeechRate(rate);
tts.setPitch(pitch);
tts.speak(text, android.speech.tts.TextToSpeech.QUEUE_FLUSH, ttsParams, callbackId);
Expand All @@ -80,7 +80,7 @@ public void onError(String utteranceId) {
ttsParams.put(android.speech.tts.TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID, callbackId);
ttsParams.put(android.speech.tts.TextToSpeech.Engine.KEY_PARAM_VOLUME, Float.toString(volume));

tts.setLanguage(new Locale(locale));
tts.setLanguage(new Locale(lang));
tts.setSpeechRate(rate);
tts.setPitch(pitch);
tts.speak(text, android.speech.tts.TextToSpeech.QUEUE_FLUSH, ttsParams);
Expand Down Expand Up @@ -133,9 +133,9 @@ public boolean isAvailable() {
return false;
}

public boolean isLocaleSupported(String locale) {
public boolean isLanguageSupported(String lang) {
Set<Locale> supportedLocales = tts.getAvailableLanguages();
if (supportedLocales.contains(Locale.forLanguageTag(locale))) {
if (supportedLocales.contains(Locale.forLanguageTag(lang))) {
return true;
}
return false;
Expand Down
16 changes: 8 additions & 8 deletions android/src/main/java/com/getcapacitor/community/tts/TextToSpeechPlugin.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ public class TextToSpeechPlugin extends Plugin {
public static final String LOG_TAG = "TextToSpeechPlugin";

public static final String ERROR_UTTERANCE = "Failed to read text.";
public static final String ERROR_UNSUPPORTED_LOCALE = "This locale is not supported.";
public static final String ERROR_UNSUPPORTED_LANGUAGE = "This language is not supported.";

private TextToSpeech implementation;

Expand All @@ -31,14 +31,14 @@ public void speak(PluginCall call) {
}

String text = call.getString("text", "");
String locale = call.getString("locale", "en-US");
float rate = call.getFloat("speechRate", 1.0f);
float pitch = call.getFloat("pitchRate", 1.0f);
String lang = call.getString("lang", "en-US");
float rate = call.getFloat("rate", 1.0f);
float pitch = call.getFloat("pitch", 1.0f);
float volume = call.getFloat("volume", 1.0f);

boolean isLocaleSupported = implementation.isLocaleSupported(locale);
if (!isLocaleSupported) {
call.reject(ERROR_UNSUPPORTED_LOCALE);
boolean isLanguageSupported = implementation.isLanguageSupported(lang);
if (!isLanguageSupported) {
call.reject(ERROR_UNSUPPORTED_LANGUAGE);
return;
}

Expand All @@ -55,7 +55,7 @@ public void onError() {
};

try {
implementation.speak(text, locale, rate, pitch, volume, call.getCallbackId(), resultCallback);
implementation.speak(text, lang, rate, pitch, volume, call.getCallbackId(), resultCallback);
} catch (Exception ex) {
call.reject(ex.getLocalizedMessage());
}
Expand Down
4 changes: 2 additions & 2 deletions ios/Plugin/TextToSpeech.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ import AVFoundation
} catch {}
}

@objc public func speak(_ text: String, _ locale: String, _ rate: Float, _ pitch: Float, _ category: String, _ volume: Float) throws {
@objc public func speak(_ text: String, _ lang: String, _ rate: Float, _ pitch: Float, _ category: String, _ volume: Float) throws {
var avAudioSessionCategory = AVAudioSession.Category.ambient
if category != "ambient" {
avAudioSessionCategory = AVAudioSession.Category.playback
Expand All @@ -30,7 +30,7 @@ import AVFoundation
self.synthesizer.stopSpeaking(at: .immediate)

self.utterance = type(of: AVSpeechUtterance()).init(string: text)
self.utterance?.voice = AVSpeechSynthesisVoice(language: locale)
self.utterance?.voice = AVSpeechSynthesisVoice(language: lang)
self.utterance?.rate = adjustRate(rate)
self.utterance?.pitchMultiplier = pitch
self.utterance?.volume = volume
Expand Down
16 changes: 8 additions & 8 deletions ios/Plugin/TextToSpeechPlugin.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,26 @@ import Capacitor
*/
@objc(TextToSpeechPlugin)
public class TextToSpeechPlugin: CAPPlugin {
private static let ERROR_UNSUPPORTED_LOCALE = "This locale is not supported."
private static let ERROR_UNSUPPORTED_LANGUAGE = "This language is not supported."

private let implementation = TextToSpeech()

@objc public func speak(_ call: CAPPluginCall) {
let text = call.getString("text") ?? ""
let locale = call.getString("locale") ?? "en-US"
let rate = call.getFloat("speechRate") ?? 1.0
let pitch = call.getFloat("pitchRate") ?? 1.0
let category = call.getString("category") ?? "ambient"
let lang = call.getString("lang") ?? "en-US"
let rate = call.getFloat("rate") ?? 1.0
let pitch = call.getFloat("pitch") ?? 1.0
let volume = call.getFloat("volume") ?? 1.0
let category = call.getString("category") ?? "ambient"

let isLanguageSupported = implementation.isLanguageSupported(locale)
let isLanguageSupported = implementation.isLanguageSupported(lang)
guard isLanguageSupported else {
call.reject(TextToSpeechPlugin.ERROR_UNSUPPORTED_LOCALE)
call.reject(TextToSpeechPlugin.ERROR_UNSUPPORTED_LANGUAGE)
return
}

do {
try implementation.speak(text, locale, rate, pitch, category, volume)
try implementation.speak(text, lang, rate, pitch, category, volume)
call.resolve()
} catch {
call.reject(error.localizedDescription)
Expand Down
38 changes: 20 additions & 18 deletions src/definitions.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,55 +17,57 @@ export interface TextToSpeechPlugin {
getSupportedVoices(): Promise<{ voices: SpeechSynthesisVoice[] }>;
/**
* Verifies proper installation and availability of resource files on the system.
*
* Only available for Android.
*/
openInstall(): Promise<void>;
}

export interface TTSOptions {
/**
* Text to be spoken.
* The text that will be synthesised when the utterance is spoken.
*/
text: string;
/**
* Language spoken in.
* The language of the utterance.
* Possible languages can be queried using `getSupportedLanguages`.
*
* Default: `en-US`
* Default: `en-US`.
*/
locale?: string;
lang?: string;
/**
* The speech rate.
* The speed at which the utterance will be spoken at.
*
* Default: `1.0`
* Default: `1.0`.
*/
speechRate?: number;
rate?: number;
/**
* The pitch rate.
* The pitch at which the utterance will be spoken at.
*
* Default: `1.0`
* Default: `1.0`.
*/
pitchRate?: number;
pitch?: number;
/**
* The volume.
* The volume that the utterance will be spoken at.
*
* Default: `1.0`
* Default: `1.0`.
*/
volume?: number;
/**
* The index of the selected voice.
* The index of the selected voice that will be used to speak the utterance.
* Possible voices can be queried using `getSupportedVoices`.
*
* Only available for Web.
*/
voice?: number;
/**
* Select the iOS Audio session category.
* Possible values: `ambient` and `playback`
* Possible values: `ambient` and `playback`.
* Use `playback` to play audio even when the app is in the background.
*
* Only available for iOS.
*
* Default: `ambient`
* Default: `ambient`.
*/
category?: string; // iOS only
}
Expand All @@ -80,7 +82,7 @@ export interface SpeechSynthesisVoice {
default: boolean;
/**
* BCP 47 language tag indicating the language of the voice.
* Example: `en-US`
* Example: `en-US`.
*/
lang: string;
/**
Expand All @@ -89,12 +91,12 @@ export interface SpeechSynthesisVoice {
localService: boolean;
/**
* Human-readable name that represents the voice.
* Example: `Microsoft Zira Desktop - English (United States)`
* Example: `Microsoft Zira Desktop - English (United States)`.
*/
name: string;
/**
* Type of URI and location of the speech synthesis service for this voice.
* Example: `urn:moz-tts:sapi:Microsoft Zira Desktop - English (United States)?en-US`
* Example: `urn:moz-tts:sapi:Microsoft Zira Desktop - English (United States)?en-US`.
*/
voiceURI: string;
}
14 changes: 7 additions & 7 deletions src/web.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,21 +61,21 @@ export class TextToSpeechWeb extends WebPlugin implements TextToSpeechPlugin {
): SpeechSynthesisUtterance {
const voices = this.getSpeechSynthesisVoices();
const utterance = new SpeechSynthesisUtterance();
const { text, locale, speechRate, volume, voice, pitchRate } = options;
const { text, lang, rate, pitch, volume, voice } = options;
if (voice) {
utterance.voice = voices[voice];
}
if (volume) {
utterance.volume = volume >= 0 && volume <= 1 ? volume : 1;
}
if (speechRate) {
utterance.rate = speechRate >= 0.1 && speechRate <= 10 ? speechRate : 1;
if (rate) {
utterance.rate = rate >= 0.1 && rate <= 10 ? rate : 1;
}
if (pitchRate) {
utterance.pitch = pitchRate >= 0 && pitchRate <= 2 ? pitchRate : 2;
if (pitch) {
utterance.pitch = pitch >= 0 && pitch <= 2 ? pitch : 2;
}
if (locale) {
utterance.lang = locale;
if (lang) {
utterance.lang = lang;
}
utterance.text = text;
return utterance;
Expand Down

0 comments on commit 83c4370

Please sign in to comment.