Expose TTS engine API

This is a new API for writing text-to-speech engines.
The existing API for apps that use TTS remains the same,
with some minor additions.

Change-Id: Id577db449ae0e5baec40621d4a08387dbd755342

4 files changed, 48 insertions, 15 deletions

diff --git a/api/current.txt b/api/current.txt
index ebf389361c5b..c76627f74aa3 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -17115,14 +17115,32 @@ package android.speech {
 
 package android.speech.tts {
 
+  public abstract class SynthesisRequest {
+    ctor public SynthesisRequest(java.lang.String);
+    method public abstract int audioAvailable(byte[], int, int);
+    method public abstract int completeAudioAvailable(int, int, int, byte[], int, int);
+    method public abstract int done();
+    method public abstract void error();
+    method public java.lang.String getCountry();
+    method public java.lang.String getLanguage();
+    method public abstract int getMaxBufferSize();
+    method public int getPitch();
+    method public int getSpeechRate();
+    method public java.lang.String getText();
+    method public java.lang.String getVariant();
+    method public abstract int start(int, int, int);
+  }
+
   public class TextToSpeech {
     ctor public TextToSpeech(android.content.Context, android.speech.tts.TextToSpeech.OnInitListener);
+    ctor public TextToSpeech(android.content.Context, android.speech.tts.TextToSpeech.OnInitListener, java.lang.String);
     method public int addEarcon(java.lang.String, java.lang.String, int);
     method public int addEarcon(java.lang.String, java.lang.String);
     method public int addSpeech(java.lang.String, java.lang.String, int);
     method public int addSpeech(java.lang.String, java.lang.String);
     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.Locale getLanguage();
     method public int isLanguageAvailable(java.util.Locale);
     method public boolean isSpeaking();
@@ -17167,12 +17185,20 @@ package android.speech.tts {
     field public static final java.lang.String EXTRA_VOICE_DATA_FILES = "dataFiles";
     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_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";
     field public static final java.lang.String KEY_PARAM_VOLUME = "volume";
   }
 
+  public static class TextToSpeech.EngineInfo {
+    ctor public TextToSpeech.EngineInfo();
+    field public int icon;
+    field public java.lang.String label;
+    field public java.lang.String name;
+  }
+
   public static abstract interface TextToSpeech.OnInitListener {
     method public abstract void onInit(int);
   }
@@ -17181,6 +17207,16 @@ package android.speech.tts {
     method public abstract void onUtteranceCompleted(java.lang.String);
   }
 
+  public abstract class TextToSpeechService extends android.app.Service {
+    ctor public TextToSpeechService();
+    method public android.os.IBinder onBind(android.content.Intent);
+    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);
+    method protected abstract void onStop();
+    method protected abstract void onSynthesizeText(android.speech.tts.SynthesisRequest);
+  }
+
 }
 
 package android.telephony {
diff --git a/core/java/android/speech/tts/SynthesisRequest.java b/core/java/android/speech/tts/SynthesisRequest.java
index 515218b2a38e..6df9af2d8418 100644
--- a/core/java/android/speech/tts/SynthesisRequest.java
+++ b/core/java/android/speech/tts/SynthesisRequest.java
@@ -24,8 +24,6 @@ package android.speech.tts;
  *
  * Alternatively, the engine can provide all the audio at once, by using
  * {@link #completeAudioAvailable}.
- *
- * @hide Pending approval
  */
 public abstract class SynthesisRequest {
 
@@ -92,16 +90,14 @@ public abstract class SynthesisRequest {
     }
 
     /**
-     * Gets the speech rate to use. {@link TextToSpeech.Engine#DEFAULT_RATE} (100)
-     * is the normal rate.
+     * Gets the speech rate to use. The normal rate is 100.
      */
     public int getSpeechRate() {
         return mSpeechRate;
     }
 
     /**
-     * Gets the pitch to use. {@link TextToSpeech.Engine#DEFAULT_PITCH} (100)
-     * is the normal pitch.
+     * Gets the pitch to use. The normal pitch is 100.
      */
     public int getPitch() {
         return mPitch;
diff --git a/core/java/android/speech/tts/TextToSpeech.java b/core/java/android/speech/tts/TextToSpeech.java
index e247df8dd9f3..1d26c22c7169 100755
--- a/core/java/android/speech/tts/TextToSpeech.java
+++ b/core/java/android/speech/tts/TextToSpeech.java
@@ -220,8 +220,6 @@ public class TextToSpeech {
          * extend {@link TextToSpeechService}. Normal applications should not use this intent
          * directly, instead they should talk to the TTS service using the the methods in this
          * class.
-         *
-         * @hide Pending API council approval
          */
         @SdkConstant(SdkConstantType.SERVICE_ACTION)
         public static final String INTENT_ACTION_TTS_SERVICE =
@@ -428,7 +426,7 @@ public class TextToSpeech {
     private final Bundle mParams = new Bundle();
 
     /**
-     * The constructor for the TextToSpeech class.
+     * The constructor for the TextToSpeech class, using the default TTS engine.
      * This will also initialize the associated TextToSpeech engine if it isn't already running.
      *
      * @param context
@@ -442,7 +440,15 @@ public class TextToSpeech {
     }
 
     /**
-     * @hide pending approval
+     * The constructor for the TextToSpeech class, using the given TTS engine.
+     * This will also initialize the associated TextToSpeech engine if it isn't already running.
+     *
+     * @param context
+     *            The context this instance is running in.
+     * @param listener
+     *            The {@link TextToSpeech.OnInitListener} that will be called when the
+     *            TextToSpeech engine has initialized.
+     * @param engine Package name of the TTS engine to use.
      */
     public TextToSpeech(Context context, OnInitListener listener, String engine) {
         mContext = context;
@@ -1060,8 +1066,6 @@ public class TextToSpeech {
      * Gets a list of all installed TTS engines.
      *
      * @return A list of engine info objects. The list can be empty, but will never by {@code null}.
-     *
-     * @hide Pending approval
      */
     public List<EngineInfo> getEngines() {
         PackageManager pm = mContext.getPackageManager();
@@ -1144,7 +1148,6 @@ public class TextToSpeech {
      * Information about an installed text-to-speech engine.
      *
      * @see TextToSpeech#getEngines
-     * @hide Pending approval
      */
     public static class EngineInfo {
         /**
diff --git a/core/java/android/speech/tts/TextToSpeechService.java b/core/java/android/speech/tts/TextToSpeechService.java
index da97fb4bdf80..590e2ef614a6 100644
--- a/core/java/android/speech/tts/TextToSpeechService.java
+++ b/core/java/android/speech/tts/TextToSpeechService.java
@@ -41,8 +41,6 @@ import java.util.Locale;
 
 /**
  * Abstract base class for TTS engine implementations.
- *
- * @hide Pending approval
  */
 public abstract class TextToSpeechService extends Service {