feat(ios): allow to customize audio session (for background playback)

Author: farfromrefug

src/index.d.ts

@@ -37,6 +37,32 @@ export interface SpeakOptions {
     locale?: string;
     language?: string;
     finishedCallback?: Function;
+
+    /**
+     * Callback to execute when info is emitted from the player.
+     * @returns {Object} An object containing the native values for the info callback.
+     */
+    infoCallback?: Function;
+
+    /**
+     * iOS: The category for playing recorded music or other sounds that are central to the successful use of your app.
+     *  https://developer.apple.com/documentation/avfaudio/avaudiosessioncategory?language=objc
+     */
+    sessionCategory?: string;
+
+    /**
+     * iOS: Audio session mode identifiers.
+     * https://developer.apple.com/documentation/avfaudio/avaudiosessionmode
+     */
+    sessionMode?: string;
+
+    /**
+     * iOS: Cases that indicate the possible route-sharing policies for an audio session.
+     * https://developer.apple.com/documentation/avfaudio/avaudiosessionroutesharingpolicy
+     */
+    sessionRouteSharingPolicy?: AVAudioSessionRouteSharingPolicy;
+
+    audioMixing?: boolean;
 }
 
 export interface Language {

src/texttospeech.android.ts

@@ -103,22 +103,11 @@ export class TNSTextToSpeech {
     }
 
     private speakText(options: SpeakOptions) {
-        if (this.isString(options.locale) && this.isValidLocale(options.locale)) {
-            const localeArray = options.locale.split('-');
-            const locale = new java.util.Locale(localeArray[0], localeArray[1]);
+        const localeStr = options.locale || options.language;
+        if (localeStr) {
+            const localeArray = localeStr.split('-');
+            const locale = new java.util.Locale(localeArray[0], localeArray[1] || localeStr.toUpperCase());
             this._tts.setLanguage(locale);
-        } else if (this.isString(options.language)) {
-            let locale = null;
-            if (this.isValidLocale(options.language)) {
-                // only for backwards compatbility with old API
-                const languageArray = options.language.split('-');
-                locale = new java.util.Locale(languageArray[0], languageArray[1]);
-            } else {
-                locale = new java.util.Locale(options.language);
-            }
-            if (locale) {
-                this._tts.setLanguage(locale);
-            }
         }
 
         if (!this.isBoolean(options.queue)) {

src/texttospeech.ios.ts

@@ -59,7 +59,26 @@ export class TNSTextToSpeech {
 
         this._lastOptions = options;
 
-        this.delegate.doneCallback = options.finishedCallback;
+        const needsAudioSession = options.sessionCategory || options.sessionMode || options.sessionRouteSharingPolicy || options.audioMixing;
+        const audioSession = AVAudioSession.sharedInstance();
+
+        if (needsAudioSession) {
+            audioSession.setCategoryModeRouteSharingPolicyOptionsError(
+                options.sessionCategory || AVAudioSessionCategoryAmbient,
+                options.sessionMode || AVAudioSessionModeDefault,
+                options.sessionRouteSharingPolicy || AVAudioSessionRouteSharingPolicy.LongForm,
+                options.audioMixing ? AVAudioSessionCategoryOptions.MixWithOthers : AVAudioSessionCategoryOptions.DuckOthers,
+                //@ts-ignore
+                null
+            );
+            audioSession.setActiveError(true);
+        }
+        this.delegate.doneCallback = () => {
+            if (needsAudioSession) {
+                audioSession.setActiveError(false);
+            }
+            options?.finishedCallback?.();
+        };
 
         // valid values for pitch are 0.5 to 2.0
         if (!isNumber(options.pitch)) {
@@ -72,7 +91,7 @@ export class TNSTextToSpeech {
 
         // valid values are AVSpeechUtteranceMinimumSpeechRate to AVSpeechUtteranceMaximumSpeechRate
         if (!isNumber(options.speakRate)) {
-            options.speakRate = AVSpeechUtteranceMaximumSpeechRate / 4.0; // default rate is way too fast
+            options.speakRate = AVSpeechUtteranceMaximumSpeechRate / 2.5; // default rate is way too fast
         } else if (options.speakRate < AVSpeechUtteranceMinimumSpeechRate) {
             options.speakRate = AVSpeechUtteranceMinimumSpeechRate;
         } else if (options.speakRate > AVSpeechUtteranceMaximumSpeechRate) {
@@ -88,12 +107,13 @@ export class TNSTextToSpeech {
 
         const speechUtterance = AVSpeechUtterance.alloc().initWithString(options.text);
 
-        if (isString(options.locale) && this.isValidLocale(options.locale)) {
-            speechUtterance.voice = AVSpeechSynthesisVoice.voiceWithLanguage(options.locale);
-        } else if (isString(options.language) && this.isValidLocale(options.language)) {
-            speechUtterance.voice = AVSpeechSynthesisVoice.voiceWithLanguage(options.language);
+        let localeStr = options.locale || options.language;
+        if (localeStr) {
+            if (localeStr.indexOf('-') === -1) {
+                localeStr = localeStr + '-' + localeStr.toUpperCase();
+            }
+            speechUtterance.voice = AVSpeechSynthesisVoice.voiceWithLanguage(localeStr);
         }
-
         speechUtterance.pitchMultiplier = options.pitch;
         speechUtterance.volume = options.volume;
         speechUtterance.rate = options.speakRate;