TTS API: Replace "voice id" with "voice name"

"Voice id" and "voice name" are both used to reference a voice in a
speech synthesis request. Voice id was a random integer, where
voice name is human readable string, that provides more debug
information and readability. Also, it's expected that voice name
will stay consistent, and won't change during the life of the speech
connection. Though, it may disappear.

Change-Id: I180296d413a18301cead1c8e3212de2bd0c7e32d

6 files changed, 65 insertions, 57 deletions

diff --git a/core/java/android/speech/tts/EventLoggerV2.java b/core/java/android/speech/tts/EventLoggerV2.java
index ca0e49c..b8e4dae 100644
--- a/core/java/android/speech/tts/EventLoggerV2.java
+++ b/core/java/android/speech/tts/EventLoggerV2.java
@@ -65,7 +65,7 @@ class EventLoggerV2 extends AbstractEventLogger {
         mRequest.getVoiceParams().size();
         mRequest.getAudioParams().size();
 
-        return new StringBuilder(64).append("VoiceId: ").append(mRequest.getVoiceId())
+        return new StringBuilder(64).append("VoiceName: ").append(mRequest.getVoiceName())
             .append(" ,VoiceParams: ").append(mRequest.getVoiceParams())
             .append(" ,SystemParams: ").append(mRequest.getAudioParams())
             .append("]").toString();
diff --git a/core/java/android/speech/tts/RequestConfig.java b/core/java/android/speech/tts/RequestConfig.java
index 8b761b5..4b5385f 100644
--- a/core/java/android/speech/tts/RequestConfig.java
+++ b/core/java/android/speech/tts/RequestConfig.java
@@ -57,8 +57,8 @@ public final class RequestConfig {
          *            from {@link VoiceInfo#getParamsWithDefaults()}
          * @param value
          *            Value of the parameter. Its type can be one of: Integer, Float,
-         *            Boolean, String, VoiceInfo (will be set as an Integer, result of a call to
-         *            the {@link VoiceInfo#getId()}) or byte[]. It has to be of the same type
+         *            Boolean, String, VoiceInfo (will be set as a String, result of a call to
+         *            the {@link VoiceInfo#getName()}) or byte[]. It has to be of the same type
          *            as the default value from {@link VoiceInfo#getParamsWithDefaults()}
          *            for that parameter.
          * @throws IllegalArgumentException
@@ -75,13 +75,13 @@ public final class RequestConfig {
             Object defaultValue = mCurrentVoiceInfo.getParamsWithDefaults().get(paramName);
             if (defaultValue == null) {
                 throw new IllegalArgumentException(
-                        "Parameter \"" + paramName + "\" is not available in set voice with id: " +
-                                mCurrentVoiceInfo.getId());
+                        "Parameter \"" + paramName + "\" is not available in set voice with " +
+                                "name: " + mCurrentVoiceInfo.getName());
             }
 
-            // If it's VoiceInfo, get its id
+            // If it's VoiceInfo, get its name
             if (value instanceof VoiceInfo) {
-                value = ((VoiceInfo)value).getId();
+                value = ((VoiceInfo)value).getName();
             }
 
             // Check type information
diff --git a/core/java/android/speech/tts/SynthesisRequestV2.java b/core/java/android/speech/tts/SynthesisRequestV2.java
index 2fec012..ed268b7 100644
--- a/core/java/android/speech/tts/SynthesisRequestV2.java
+++ b/core/java/android/speech/tts/SynthesisRequestV2.java
@@ -10,7 +10,7 @@ import android.speech.tts.TextToSpeechClient.UtteranceId;
  * <ul>
  *   <li>The utterance to synthesize</li>
  *   <li>The id of the utterance (String, result of {@link UtteranceId#toUniqueString()}</li>
- *   <li>The synthesis voice ID (Integer, result of {@link VoiceInfo#getId()})</li>
+ *   <li>The synthesis voice name (String, result of {@link VoiceInfo#getName()})</li>
  *   <li>Voice parameters (Bundle of parameters)</li>
  *   <li>Audio parameters (Bundle of parameters)</li>
  * </ul>
@@ -23,7 +23,7 @@ public final class SynthesisRequestV2 implements Parcelable {
     private final String mUtteranceId;
 
     /** Voice ID. */
-    private final int mVoiceId;
+    private final String mVoiceName;
 
     /** Voice Parameters. */
     private final Bundle mVoiceParams;
@@ -39,7 +39,7 @@ public final class SynthesisRequestV2 implements Parcelable {
     public SynthesisRequestV2(Parcel in) {
         this.mText = in.readString();
         this.mUtteranceId = in.readString();
-        this.mVoiceId = in.readInt();
+        this.mVoiceName = in.readString();
         this.mVoiceParams = in.readBundle();
         this.mAudioParams = in.readBundle();
     }
@@ -47,7 +47,7 @@ public final class SynthesisRequestV2 implements Parcelable {
     SynthesisRequestV2(String text, String utteranceId, RequestConfig rconfig) {
         this.mText = text;
         this.mUtteranceId = utteranceId;
-        this.mVoiceId = rconfig.getVoice().getId();
+        this.mVoiceName = rconfig.getVoice().getName();
         this.mVoiceParams = rconfig.getVoiceParams();
         this.mAudioParams = rconfig.getAudioParams();
     }
@@ -61,7 +61,7 @@ public final class SynthesisRequestV2 implements Parcelable {
     public void writeToParcel(Parcel dest, int flags) {
         dest.writeString(mText);
         dest.writeString(mUtteranceId);
-        dest.writeInt(mVoiceId);
+        dest.writeString(mVoiceName);
         dest.writeBundle(mVoiceParams);
         dest.writeBundle(mAudioParams);
     }
@@ -83,11 +83,11 @@ public final class SynthesisRequestV2 implements Parcelable {
     }
 
     /**
-     * @return the id of the voice to use for this synthesis request. Result of a call to
-     * the {@link VoiceInfo#getId()} method.
+     * @return the name of the voice to use for this synthesis request. Result of a call to
+     * the {@link VoiceInfo#getName()} method.
      */
-    public int getVoiceId() {
-        return mVoiceId;
+    public String getVoiceName() {
+        return mVoiceName;
     }
 
     /**
diff --git a/core/java/android/speech/tts/TextToSpeechClient.java b/core/java/android/speech/tts/TextToSpeechClient.java
index 65a68e7..9a98e1c 100644
--- a/core/java/android/speech/tts/TextToSpeechClient.java
+++ b/core/java/android/speech/tts/TextToSpeechClient.java
@@ -93,7 +93,7 @@ public final class TextToSpeechClient {
         /**
          * Maximum allowed time for a single request attempt, in milliseconds, before synthesis
          * fails (or fallback request starts, if requested using
-         * {@link #FALLBACK_VOICE_ID}).
+         * {@link #FALLBACK_VOICE_NAME}).
          */
         public static final String NETWORK_TIMEOUT_MS = "networkTimeoutMs";
 
@@ -111,13 +111,13 @@ public final class TextToSpeechClient {
         /**
          * If a voice exposes this parameter then it supports the fallback request feature.
          *
-         * If it is set to a valid id of some other voice ({@link VoiceInfo#getId()}) then
+         * If it is set to a valid name of some other voice ({@link VoiceInfo#getName()}) then
          * in case of request failure (due to network problems or missing data), fallback request
          * will be attempted. Request will be done using the voice referenced by this parameter.
          * If it is the case, the client will be informed by a callback to the {@link
          * RequestCallbacks#onSynthesisFallback(UtteranceId)}.
          */
-        public static final String FALLBACK_VOICE_ID = "fallbackVoiceId";
+        public static final String FALLBACK_VOICE_NAME = "fallbackVoiceName";
 
         /**
          * Audio parameter for specifying a linear multiplier to the speaking speed of the voice.
@@ -252,7 +252,7 @@ public final class TextToSpeechClient {
         /**
          * Called when requested synthesis failed and fallback synthesis is about to be attempted.
          *
-         * Requires voice with available {@link TextToSpeechClient.Params#FALLBACK_VOICE_ID}
+         * Requires voice with available {@link TextToSpeechClient.Params#FALLBACK_VOICE_NAME}
          * parameter, and request with this parameter enabled.
          *
          * This callback will be followed by callback to the {@link #onSynthesisStart},
@@ -260,7 +260,7 @@ public final class TextToSpeechClient {
          * fallback outcome.
          *
          * For more fallback feature reference, look at the
-         * {@link TextToSpeechClient.Params#FALLBACK_VOICE_ID}.
+         * {@link TextToSpeechClient.Params#FALLBACK_VOICE_NAME}.
          *
          * @param utteranceId
          *            Unique identifier of synthesized utterance.
diff --git a/core/java/android/speech/tts/TextToSpeechService.java b/core/java/android/speech/tts/TextToSpeechService.java
index b3e01ce..d7c51fc 100644
--- a/core/java/android/speech/tts/TextToSpeechService.java
+++ b/core/java/android/speech/tts/TextToSpeechService.java
@@ -115,7 +115,7 @@ public abstract class TextToSpeechService extends Service {
     private final Object mVoicesInfoLock = new Object();
 
     private List<VoiceInfo> mVoicesInfoList;
-    private Map<Integer, VoiceInfo> mVoicesInfoLookup;
+    private Map<String, VoiceInfo> mVoicesInfoLookup;
 
     @Override
     public void onCreate() {
@@ -236,8 +236,8 @@ public abstract class TextToSpeechService extends Service {
             SynthesisCallback callback);
 
     /**
-     * Check the available voices data and return immutable list of available voices.
-     * Output of this method will be passed to clients to allow them to configure synthesis
+     * Check the available voices data and return an immutable list of the available voices.
+     * The output of this method will be passed to clients to allow them to configure synthesis
      * requests.
      *
      * Can be called on multiple threads.
@@ -291,14 +291,14 @@ public abstract class TextToSpeechService extends Service {
 
             if (features == null || features.contains(
                     TextToSpeech.Engine.KEY_FEATURE_EMBEDDED_SYNTHESIS)) {
-                builder.setId(id++);
+                builder.setName(locale.toString() + "-embedded");
                 builder.setRequiresNetworkConnection(false);
                 voicesInfo.add(builder.build());
             }
 
             if (features != null && features.contains(
                     TextToSpeech.Engine.KEY_FEATURE_NETWORK_SYNTHESIS)) {
-                builder.setId(id++);
+                builder.setName(locale.toString() + "-network");
                 builder.setRequiresNetworkConnection(true);
                 voicesInfo.add(builder.build());
             }
@@ -391,11 +391,12 @@ public abstract class TextToSpeechService extends Service {
                 // Get voices. Defensive copy to make sure TTS engine won't alter the list.
                 mVoicesInfoList = new ArrayList<VoiceInfo>(checkVoicesInfo());
                 // Build lookup map
-                mVoicesInfoLookup = new HashMap<Integer, VoiceInfo>((int) (mVoicesInfoList.size()*1.5f));
+                mVoicesInfoLookup = new HashMap<String, VoiceInfo>((int) (
+                        mVoicesInfoList.size()*1.5f));
                 for (VoiceInfo voiceInfo : mVoicesInfoList) {
-                    VoiceInfo prev = mVoicesInfoLookup.put(voiceInfo.getId(), voiceInfo);
+                    VoiceInfo prev = mVoicesInfoLookup.put(voiceInfo.getName(), voiceInfo);
                     if (prev != null) {
-                        Log.e(TAG, "Duplicate ID (" + voiceInfo.getId() + ") of the voice ");
+                        Log.e(TAG, "Duplicate name (" + voiceInfo.getName() + ") of the voice ");
                     }
                 }
             }
@@ -403,10 +404,10 @@ public abstract class TextToSpeechService extends Service {
         }
     }
 
-    public VoiceInfo getVoicesInfoWithId(int id) {
+    public VoiceInfo getVoicesInfoWithName(String name) {
         synchronized (mVoicesInfoLock) {
             if (mVoicesInfoLookup != null) {
-                return mVoicesInfoLookup.get(id);
+                return mVoicesInfoLookup.get(name);
             }
         }
         return null;
@@ -885,13 +886,13 @@ public abstract class TextToSpeechService extends Service {
             }
 
             // Get voice info
-            VoiceInfo voiceInfo = getVoicesInfoWithId(mSynthesisRequest.getVoiceId());
+            VoiceInfo voiceInfo = getVoicesInfoWithName(mSynthesisRequest.getVoiceName());
             if (voiceInfo != null) {
                 // Primary voice
                 TextToSpeechService.this.onSynthesizeTextV2(mSynthesisRequest, voiceInfo,
                         synthesisCallback);
             } else {
-                Log.e(TAG, "Unknown voice id:" + mSynthesisRequest.getVoiceId());
+                Log.e(TAG, "Unknown voice name:" + mSynthesisRequest.getVoiceName());
                 synthesisCallback.error(TextToSpeechClient.Status.ERROR_INVALID_REQUEST);
             }
 
diff --git a/core/java/android/speech/tts/VoiceInfo.java b/core/java/android/speech/tts/VoiceInfo.java
index 61e4dde..16b9a97 100644
--- a/core/java/android/speech/tts/VoiceInfo.java
+++ b/core/java/android/speech/tts/VoiceInfo.java
@@ -10,11 +10,12 @@ import java.util.Locale;
  * Characteristics and features of a Text-To-Speech Voice. Each TTS Engine can expose
  * multiple voices for multiple locales, with different set of features.
  *
- * Each VoiceInfo has an unique ID. This ID can be obtained using the {@link #getId()} method and
- * will persist until the client is asked to re-evaluate the list of available voices in the
+ * Each VoiceInfo has an unique name. This name can be obtained using the {@link #getName()} method
+ * and will persist until the client is asked to re-evaluate the list of available voices in the
  * {@link TextToSpeechClient.ConnectionCallbacks#onEngineStatusChange(android.speech.tts.TextToSpeechClient.EngineStatus)}
- * callback. The id can be used to reference a VoiceInfo in an instance of {@link RequestConfig};
- * the {@link TextToSpeechClient.Params#FALLBACK_VOICE_ID} voice parameter is an example of this.
+ * callback. The name can be used to reference a VoiceInfo in an instance of {@link RequestConfig};
+ * the {@link TextToSpeechClient.Params#FALLBACK_VOICE_NAME} voice parameter is an example of this.
+ * It is recommended that the voice name never change during the TTS service lifetime.
  */
 public final class VoiceInfo implements Parcelable {
     /** Very low, but still intelligible quality of speech synthesis */
@@ -60,16 +61,16 @@ public final class VoiceInfo implements Parcelable {
      *
      * Making a request with a voice that has this feature may result in a
      * {@link TextToSpeechClient.Status#ERROR_DOWNLOADING_ADDITIONAL_DATA} error. It's recommended
-     * to set the {@link TextToSpeechClient.Params#FALLBACK_VOICE_ID} voice parameter to reference
+     * to set the {@link TextToSpeechClient.Params#FALLBACK_VOICE_NAME} voice parameter to reference
      * a fully installed voice (or network voice) that can serve as replacement.
      *
      * Note: It's a good practice for a TTS engine to provide a sensible fallback voice as the
-     * default value for {@link TextToSpeechClient.Params#FALLBACK_VOICE_ID} parameter if this
+     * default value for {@link TextToSpeechClient.Params#FALLBACK_VOICE_NAME} parameter if this
      * feature is present.
      */
     public static final String FEATURE_MAY_AUTOINSTALL = "mayAutoInstall";
 
-    private final int id;
+    private final String mName;
     private final Locale mLocale;
     private final int mQuality;
     private final int mLatency;
@@ -78,7 +79,7 @@ public final class VoiceInfo implements Parcelable {
     private final Bundle mAdditionalFeatures;
 
     private VoiceInfo(Parcel in) {
-        this.id = in.readInt();
+        this.mName = in.readString();
         String[] localesData = new String[3];
         in.readStringArray(localesData);
         this.mLocale = new Locale(localesData[0], localesData[1], localesData[2]);
@@ -91,14 +92,14 @@ public final class VoiceInfo implements Parcelable {
         this.mAdditionalFeatures = in.readBundle();
     }
 
-    private VoiceInfo(int id,
+    private VoiceInfo(String name,
             Locale locale,
             int quality,
             int latency,
             boolean requiresNetworkConnection,
             Bundle params,
             Bundle additionalFeatures) {
-        this.id = id;
+        this.mName = name;
         this.mLocale = locale;
         this.mQuality = quality;
         this.mLatency = latency;
@@ -109,7 +110,7 @@ public final class VoiceInfo implements Parcelable {
 
     /** Builder, allows TTS engines to create VoiceInfo instances. */
     public static final class Builder {
-        private int id;
+        private String name;
         private Locale locale;
         private int quality = VoiceInfo.QUALITY_NORMAL;
         private int latency = VoiceInfo.LATENCY_NORMAL;
@@ -125,7 +126,7 @@ public final class VoiceInfo implements Parcelable {
          * Copy fields from given VoiceInfo instance.
          */
         public Builder(VoiceInfo voiceInfo) {
-            this.id = voiceInfo.id;
+            this.name = voiceInfo.mName;
             this.locale = voiceInfo.mLocale;
             this.quality = voiceInfo.mQuality;
             this.latency = voiceInfo.mLatency;
@@ -135,11 +136,14 @@ public final class VoiceInfo implements Parcelable {
         }
 
         /**
-         * Sets the voice's unique ID. It will be used by clients to name the voice used by a
+         * Sets the voice's unique name. It will be used by clients to reference the voice used by a
          * request.
+         *
+         * It's recommended that each voice use the same consistent name during the TTS service
+         * lifetime.
          */
-        public Builder setId(int id) {
-            this.id = id;
+        public Builder setName(String name) {
+            this.name = name;
             return this;
         }
 
@@ -196,14 +200,17 @@ public final class VoiceInfo implements Parcelable {
         }
 
         /**
-         * @return The built VoiceInfo instance
+         * @return The built VoiceInfo instance.
          */
         public VoiceInfo build() {
+            if (name == null || name.isEmpty()) {
+                throw new IllegalStateException("Name can't be null or empty");
+            }
             if (locale == null) {
                 throw new IllegalStateException("Locale can't be null");
             }
 
-            return new VoiceInfo(id, locale, quality, latency,
+            return new VoiceInfo(name, locale, quality, latency,
                         requiresNetworkConnection,
                         ((params == null) ? new Bundle() :
                             (Bundle)params.clone()),
@@ -225,7 +232,7 @@ public final class VoiceInfo implements Parcelable {
      */
     @Override
     public void writeToParcel(Parcel dest, int flags) {
-        dest.writeInt(id);
+        dest.writeString(mName);
         String[] localesData = new String[]{mLocale.getLanguage(), mLocale.getCountry(), mLocale.getVariant()};
         dest.writeStringArray(localesData);
         dest.writeInt(mQuality);
@@ -286,14 +293,14 @@ public final class VoiceInfo implements Parcelable {
     }
 
     /**
-     * @return Unique voice identifier.
+     * @return Unique voice name.
      *
-     * Each VoiceInfo has an unique ID, that persists until client is asked to re-evaluate the
+     * Each VoiceInfo has an unique name, that persists until client is asked to re-evaluate the
      * set of the available languages in the {@link TextToSpeechClient.ConnectionCallbacks#onEngineStatusChange(android.speech.tts.TextToSpeechClient.EngineStatus)}
-     * callback.
+     * callback (Voice may disappear from the set if voice was removed by the user).
      */
-    public int getId() {
-        return id;
+    public String getName() {
+        return mName;
     }
 
     /**
@@ -306,7 +313,7 @@ public final class VoiceInfo implements Parcelable {
     @Override
     public String toString() {
         StringBuilder builder = new StringBuilder(64);
-        return builder.append("VoiceInfo[Id: ").append(id)
+        return builder.append("VoiceInfo[Name: ").append(mName)
                 .append(" ,locale: ").append(mLocale)
                 .append(" ,quality: ").append(mQuality)
                 .append(" ,latency: ").append(mLatency)