Add an API for querying / enabling network TTS support.

bug:5284966
Change-Id: I01708f40bf0e975449125320dbcd4842210ca168

Author: narayank

api/current.txt

@@ -18808,6 +18808,7 @@ package android.speech.tts {
     method public boolean areDefaultsEnforced();
     method public java.lang.String getDefaultEngine();
     method public java.util.List<android.speech.tts.TextToSpeech.EngineInfo> getEngines();
+    method public java.util.Set<java.lang.String> getFeatures(java.util.Locale);
     method public java.util.Locale getLanguage();
     method public int isLanguageAvailable(java.util.Locale);
     method public boolean isSpeaking();
@@ -18853,6 +18854,8 @@ package android.speech.tts {
     field public static final java.lang.String EXTRA_VOICE_DATA_FILES_INFO = "dataFilesInfo";
     field public static final java.lang.String EXTRA_VOICE_DATA_ROOT_DIRECTORY = "dataRoot";
     field public static final java.lang.String INTENT_ACTION_TTS_SERVICE = "android.intent.action.TTS_SERVICE";
+    field public static final java.lang.String KEY_FEATURE_EMBEDDED_SYNTHESIS = "embeddedTts";
+    field public static final java.lang.String KEY_FEATURE_NETWORK_SYNTHESIS = "networkTts";
     field public static final java.lang.String KEY_PARAM_PAN = "pan";
     field public static final java.lang.String KEY_PARAM_STREAM = "streamType";
     field public static final java.lang.String KEY_PARAM_UTTERANCE_ID = "utteranceId";
@@ -18878,6 +18881,7 @@ package android.speech.tts {
   public abstract class TextToSpeechService extends android.app.Service {
     ctor public TextToSpeechService();
     method public android.os.IBinder onBind(android.content.Intent);
+    method protected java.util.Set<java.lang.String> onGetFeaturesForLanguage(java.lang.String, java.lang.String, java.lang.String);
     method protected abstract java.lang.String[] onGetLanguage();
     method protected abstract int onIsLanguageAvailable(java.lang.String, java.lang.String, java.lang.String);
     method protected abstract int onLoadLanguage(java.lang.String, java.lang.String, java.lang.String);

core/java/android/speech/tts/ITextToSpeechService.aidl

@@ -113,6 +113,21 @@ interface ITextToSpeechService {
      */
     int isLanguageAvailable(in String lang, in String country, in String variant);
 
+    /**
+     * Returns a list of features available for a given language. Elements of the returned
+     * string array can be passed in as keys to {@link TextToSpeech#speak} and
+     * {@link TextToSpeech#synthesizeToFile} to select a given feature or features to be
+     * used during synthesis.
+     *
+     * @param lang ISO-3 language code.
+     * @param country ISO-3 country code. May be empty or null.
+     * @param variant Language variant. May be empty or null.
+     * @return An array of strings containing the set of features supported for
+     *         the supplied locale. The array of strings must not contain 
+     *         duplicates.
+     */
+    String[] getFeaturesForLanguage(in String lang, in String country, in String variant);
+
     /**
      * Notifies the engine that it should load a speech synthesis language.
      *

core/java/android/speech/tts/TextToSpeech.java

@@ -31,10 +31,13 @@
 import android.text.TextUtils;
 import android.util.Log;
 
+import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Set;
 
 /**
  *
@@ -147,7 +150,25 @@ public interface OnUtteranceCompletedListener {
     }
 
     /**
-     * Constants and parameter names for controlling text-to-speech.
+     * Constants and parameter names for controlling text-to-speech. These include:
+     *
+     * <ul>
+     *     <li>
+     *         Intents to ask engine to install data or check its data and
+     *         extras for a TTS engine's check data activity.
+     *     </li>
+     *     <li>
+     *         Keys for the parameters passed with speak commands, e.g.
+     *         {@link Engine#KEY_PARAM_UTTERANCE_ID}, {@link Engine#KEY_PARAM_STREAM}.
+     *     </li>
+     *     <li>
+     *         A list of feature strings that engines might support, e.g
+     *         {@link Engine#KEY_FEATURE_NETWORK_SYNTHESIS}). These values may be passed in to
+     *         {@link TextToSpeech#speak} and {@link TextToSpeech#synthesizeToFile} to modify
+     *         engine behaviour. The engine can be queried for the set of features it supports
+     *         through {@link TextToSpeech#getFeatures(java.util.Locale)}.
+     *     </li>
+     * </ul>
      */
     public class Engine {
 
@@ -435,6 +456,25 @@ public class Engine {
          */
         public static final String KEY_PARAM_PAN = "pan";
 
+        /**
+         * Feature key for network synthesis. See {@link TextToSpeech#getFeatures(Locale)}
+         * for a description of how feature keys work. If set (and supported by the engine
+         * as per {@link TextToSpeech#getFeatures(Locale)}, the engine must
+         * use network based synthesis.
+         *
+         * @see TextToSpeech#speak(String, int, java.util.HashMap)
+         * @see TextToSpeech#synthesizeToFile(String, java.util.HashMap, String)
+         * @see TextToSpeech#getFeatures(java.util.Locale)
+         */
+        public static final String KEY_FEATURE_NETWORK_SYNTHESIS = "networkTts";
+
+        /**
+         * Feature key for embedded synthesis. See {@link TextToSpeech#getFeatures(Locale)}
+         * for a description of how feature keys work. If set and supported by the engine
+         * as per {@link TextToSpeech#getFeatures(Locale)}, the engine must synthesize
+         * text on-device (without making network requests).
+         */
+        public static final String KEY_FEATURE_EMBEDDED_SYNTHESIS = "embeddedTts";
     }
 
     private final Context mContext;
@@ -811,6 +851,36 @@ public Integer run(ITextToSpeechService service) throws RemoteException {
         }, ERROR, "playSilence");
     }
 
+    /**
+     * Queries the engine for the set of features it supports for a given locale.
+     * Features can either be framework defined, e.g.
+     * {@link TextToSpeech.Engine#KEY_FEATURE_NETWORK_SYNTHESIS} or engine specific.
+     * Engine specific keys must be prefixed by the name of the engine they
+     * are intended for. These keys can be used as parameters to
+     * {@link TextToSpeech#speak(String, int, java.util.HashMap)} and
+     * {@link TextToSpeech#synthesizeToFile(String, java.util.HashMap, String)}.
+     *
+     * Features are boolean flags, and their values in the synthesis parameters
+     * must be behave as per {@link Boolean#parseBoolean(String)}.
+     *
+     * @param locale The locale to query features for.
+     */
+    public Set<String> getFeatures(final Locale locale) {
+        return runAction(new Action<Set<String>>() {
+            @Override
+            public Set<String> run(ITextToSpeechService service) throws RemoteException {
+                String[] features = service.getFeaturesForLanguage(
+                        locale.getISO3Language(), locale.getISO3Country(), locale.getVariant());
+                if (features != null) {
+                    final Set<String> featureSet = new HashSet<String>();
+                    Collections.addAll(featureSet, features);
+                    return featureSet;
+                }
+                return null;
+            }
+        }, null, "getFeatures");
+    }
+
     /**
      * Checks whether the TTS engine is busy speaking. Note that a speech item is
      * considered complete once it's audio data has been sent to the audio mixer, or
@@ -1017,6 +1087,9 @@ private Bundle getParams(HashMap<String, String> params) {
             copyFloatParam(bundle, params, Engine.KEY_PARAM_VOLUME);
             copyFloatParam(bundle, params, Engine.KEY_PARAM_PAN);
 
+            // Copy feature strings defined by the framework.
+            copyStringParam(bundle, params, Engine.KEY_FEATURE_NETWORK_SYNTHESIS);
+
             // Copy over all parameters that start with the name of the
             // engine that we are currently connected to. The engine is
             // free to interpret them as it chooses.

core/java/android/speech/tts/TextToSpeechService.java

@@ -36,6 +36,7 @@
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.Locale;
+import java.util.Set;
 
 
 /**
@@ -67,7 +68,6 @@
  * any. Any pending data from the current synthesis will be discarded.
  *
  */
-// TODO: Add a link to the sample TTS engine once it's done.
 public abstract class TextToSpeechService extends Service {
 
     private static final boolean DBG = false;
@@ -196,6 +196,18 @@ public void onDestroy() {
     protected abstract void onSynthesizeText(SynthesisRequest request,
             SynthesisCallback callback);
 
+    /**
+     * Queries the service for a set of features supported for a given language.
+     *
+     * @param lang ISO-3 language code.
+     * @param country ISO-3 country code. May be empty or null.
+     * @param variant Language variant. May be empty or null.
+     * @return A list of features supported for the given language.
+     */
+    protected Set<String> onGetFeaturesForLanguage(String lang, String country, String variant) {
+        return null;
+    }
+
     private int getDefaultSpeechRate() {
         return getSecureSettingInt(Settings.Secure.TTS_DEFAULT_RATE, Engine.DEFAULT_RATE);
     }
@@ -778,6 +790,13 @@ public int isLanguageAvailable(String lang, String country, String variant) {
             return onIsLanguageAvailable(lang, country, variant);
         }
 
+        public String[] getFeaturesForLanguage(String lang, String country, String variant) {
+            Set<String> features = onGetFeaturesForLanguage(lang, country, variant);
+            String[] featuresArray = new String[features.size()];
+            features.toArray(featuresArray);
+            return featuresArray;
+        }
+
         /*
          * There is no point loading a non default language if defaults
          * are enforced.