TextToSpeech javadoc update.
diff --git a/core/java/android/speech/tts/TextToSpeech.java b/core/java/android/speech/tts/TextToSpeech.java
index a6d76d6..3f369dd 100755
--- a/core/java/android/speech/tts/TextToSpeech.java
+++ b/core/java/android/speech/tts/TextToSpeech.java
@@ -35,9 +35,13 @@
/**
*
* Synthesizes speech from text for immediate playback or to create a sound file.
+ * <p>A TextToSpeech instance can only be used to synthesize text once it has completed its
+ * initialization. Implement the {@link TextToSpeech.OnInitListener} to be
+ * notified of the completion of the initialization.<br>
+ * When you are done using the TextToSpeech instance, call the {@link #shutdown()} method
+ * to release the native resources used by the TextToSpeech engine.
*
*/
-//TODO complete javadoc + add links to constants
public class TextToSpeech {
/**
@@ -85,7 +89,7 @@
public static final int LANG_MISSING_DATA = -1;
/**
- * Denotes the language is not supported by the current TTS engine.
+ * Denotes the language is not supported.
*/
public static final int LANG_NOT_SUPPORTED = -2;
@@ -100,29 +104,38 @@
/**
- * Called when the TTS has initialized.
- *
- * The InitListener must implement the onInit function. onInit is passed a
- * status code indicating the result of the TTS initialization.
+ * Interface definition of a callback to be invoked indicating the completion of the
+ * TextToSpeech engine initialization.
*/
public interface OnInitListener {
+ /**
+ * Called to signal the completion of the TextToSpeech engine initialization.
+ * @param status {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
+ */
public void onInit(int status);
}
/**
- * Called when the TTS has completed saying something that has an utterance ID set.
+ * Interface definition of a callback to be invoked indicating the TextToSpeech engine has
+ * completed synthesizing an utterance with an utterance ID set.
*
- * The OnUtteranceCompletedListener must implement the onUtteranceCompleted function.
- * onUtteranceCompleted is passed a String that is the utteranceId given in
- * the original speak call.
*/
- public interface OnUtteranceCompletedListener {
+ public interface OnUtteranceCompletedListener {
+ /**
+ * Called to signal the completion of the synthesis of the utterance that was identified
+ * with the string parameter. This identifier is the one originally passed in the
+ * parameter hashmap of the synthesis request in
+ * {@link TextToSpeech#speak(String, int, HashMap)} or
+ * {@link TextToSpeech#synthesizeToFile(String, HashMap, String)} with the
+ * {@link TextToSpeech.Engine#KEY_PARAM_UTTERANCE_ID} key.
+ * @param utteranceId the identifier of the utterance.
+ */
public void onUtteranceCompleted(String utteranceId);
}
/**
- * Internal constants for the TTS functionality
+ * Internal constants for the TextToSpeech functionality
*
*/
public class Engine {
@@ -145,38 +158,41 @@
public static final String DEFAULT_SYNTH = "com.svox.pico";
// default values for rendering
+ /**
+ * Default audio stream used when playing synthesized speech.
+ */
public static final int DEFAULT_STREAM = AudioManager.STREAM_MUSIC;
// return codes for a TTS engine's check data activity
/**
* Indicates success when checking the installation status of the resources used by the
- * text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+ * TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
*/
public static final int CHECK_VOICE_DATA_PASS = 1;
/**
* Indicates failure when checking the installation status of the resources used by the
- * text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+ * TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
*/
public static final int CHECK_VOICE_DATA_FAIL = 0;
/**
* Indicates erroneous data when checking the installation status of the resources used by
- * the text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+ * the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
*/
public static final int CHECK_VOICE_DATA_BAD_DATA = -1;
/**
* Indicates missing resources when checking the installation status of the resources used
- * by the text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+ * by the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
*/
public static final int CHECK_VOICE_DATA_MISSING_DATA = -2;
/**
* Indicates missing storage volume when checking the installation status of the resources
- * used by the text-to-speech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+ * used by the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
*/
public static final int CHECK_VOICE_DATA_MISSING_VOLUME = -3;
// intents to ask engine to install data or check its data
/**
- * Activity Action: Triggers the platform Text-To-Speech engine to
+ * Activity Action: Triggers the platform TextToSpeech engine to
* start the activity that installs the resource files on the device
* that are required for TTS to be operational. Since the installation
* of the data can be interrupted or declined by the user, the application
@@ -197,7 +213,7 @@
public static final String ACTION_TTS_DATA_INSTALLED =
"android.speech.tts.engine.TTS_DATA_INSTALLED";
/**
- * Activity Action: Starts the activity from the platform Text-To-Speech
+ * Activity Action: Starts the activity from the platform TextToSpeech
* engine to verify the proper installation and availability of the
* resource files on the system. Upon completion, the activity will
* return one of the following codes:
@@ -210,9 +226,9 @@
* fields:
* <ul>
* <li>{@link #EXTRA_VOICE_DATA_ROOT_DIRECTORY} which
- * indicates the path to the location of the resource files</li>,
+ * indicates the path to the location of the resource files,</li>
* <li>{@link #EXTRA_VOICE_DATA_FILES} which contains
- * the list of all the resource files</li>,
+ * the list of all the resource files,</li>
* <li>and {@link #EXTRA_VOICE_DATA_FILES_INFO} which
* contains, for each resource file, the description of the language covered by
* the file in the xxx-YYY format, where xxx is the 3-letter ISO language code,
@@ -226,18 +242,18 @@
// extras for a TTS engine's check data activity
/**
* Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
- * the text-to-speech engine specifies the path to its resources.
+ * the TextToSpeech engine specifies the path to its resources.
*/
public static final String EXTRA_VOICE_DATA_ROOT_DIRECTORY = "dataRoot";
/**
* Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
- * the text-to-speech engine specifies the file names of its resources under the
+ * the TextToSpeech engine specifies the file names of its resources under the
* resource path.
*/
public static final String EXTRA_VOICE_DATA_FILES = "dataFiles";
/**
* Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
- * the text-to-speech engine specifies the locale associated with each resource file.
+ * the TextToSpeech engine specifies the locale associated with each resource file.
*/
public static final String EXTRA_VOICE_DATA_FILES_INFO = "dataFilesInfo";
@@ -272,11 +288,17 @@
/**
* Parameter key to specify the audio stream type to be used when speaking text
* or playing back a file.
+ * @see TextToSpeech#speak(String, int, HashMap)
+ * @see TextToSpeech#playEarcon(String, int, HashMap)
*/
public static final String KEY_PARAM_STREAM = "streamType";
/**
- * Parameter key to identify an utterance in the completion listener after text has been
+ * Parameter key to identify an utterance in the
+ * {@link TextToSpeech.OnUtteranceCompletedListener} after text has been
* spoken, a file has been played back or a silence duration has elapsed.
+ * @see TextToSpeech#speak(String, int, HashMap)
+ * @see TextToSpeech#playEarcon(String, int, HashMap)
+ * @see TextToSpeech#synthesizeToFile(String, HashMap, String)
*/
public static final String KEY_PARAM_UTTERANCE_ID = "utteranceId";
@@ -330,13 +352,14 @@
private String[] mCachedParams;
/**
- * The constructor for the TTS.
+ * The constructor for the TextToSpeech class.
+ * This will also initialize the associated TextToSpeech engine if it isn't already running.
*
* @param context
- * The context
+ * The context this instance is running in.
* @param listener
- * The InitListener that will be called when the TTS has
- * initialized successfully.
+ * The {@link TextToSpeech.OnInitListener} that will be called when the
+ * TextToSpeech engine has initialized.
*/
public TextToSpeech(Context context, OnInitListener listener) {
mContext = context;
@@ -402,9 +425,9 @@
/**
- * Shuts down the TTS. It is good practice to call this in the onDestroy
- * method of the Activity that is using the TTS so that the TTS is stopped
- * cleanly.
+ * Releases the resources used by the TextToSpeech engine.
+ * It is good practice for instance to call this method in the onDestroy() method of an Activity
+ * so the TextToSpeech engine can be cleanly stopped.
*/
public void shutdown() {
try {
@@ -418,11 +441,12 @@
/**
* Adds a mapping between a string of text and a sound resource in a
- * package.
- * @see #speak(String, int, HashMap)
+ * package. After a call to this method, subsequent calls to
+ * {@link #speak(String, int, HashMap)} will play the specified sound resource
+ * if it is available, or synthesize the text it is missing.
*
* @param text
- * Example: <b><code>"south_south_east"</code></b><br/>
+ * The string of text. Example: <code>"south_south_east"</code>
*
* @param packagename
* Pass the packagename of the application that contains the
@@ -438,7 +462,7 @@
* </p>
*
* @param resourceId
- * Example: <b><code>R.raw.south_south_east</code></b>
+ * Example: <code>R.raw.south_south_east</code>
*
* @return Code indicating success or failure. See {@link #ERROR} and {@link #SUCCESS}.
*/
@@ -476,10 +500,13 @@
/**
* Adds a mapping between a string of text and a sound file. Using this, it
- * is possible to add custom pronounciations for text.
+ * is possible to add custom pronounciations for a string of text.
+ * After a call to this method, subsequent calls to {@link #speak(String, int, HashMap)}
+ * will play the specified sound resource if it is available, or synthesize the text it is
+ * missing.
*
* @param text
- * The string of text
+ * The string of text. Example: <code>"south_south_east"</code>
* @param filename
* The full path to the sound file (for example:
* "/sdcard/mysounds/hello.wav")
@@ -520,28 +547,26 @@
/**
* Adds a mapping between a string of text and a sound resource in a
- * package.
+ * package. Use this to add custom earcons.
*
* @see #playEarcon(String, int, HashMap)
*
- * @param earcon The name of the earcon
- * Example: <b><code>"[tick]"</code></b><br/>
+ * @param earcon The name of the earcon.
+ * Example: <code>"[tick]"</code><br/>
*
* @param packagename
- * Pass the packagename of the application that contains the
- * resource. If the resource is in your own application (this is
- * the most common case), then put the packagename of your
- * application here.<br/>
+ * the package name of the application that contains the
+ * resource. This can for instance be the package name of your own application.
* Example: <b>"com.google.marvin.compass"</b><br/>
- * The packagename can be found in the AndroidManifest.xml of
- * your application.
+ * The package name can be found in the AndroidManifest.xml of
+ * the application containing the resource.
* <p>
* <code><manifest xmlns:android="..."
* package="<b>com.google.marvin.compass</b>"></code>
* </p>
*
* @param resourceId
- * Example: <b><code>R.raw.tick_snd</code></b>
+ * Example: <code>R.raw.tick_snd</code>
*
* @return Code indicating success or failure. See {@link #ERROR} and {@link #SUCCESS}.
*/
@@ -578,11 +603,14 @@
/**
- * Adds a mapping between a string of text and a sound file. Using this, it
- * is possible to add custom earcons.
+ * Adds a mapping between a string of text and a sound file.
+ * Use this to add custom earcons.
+ *
+ * @see #playEarcon(String, int, HashMap)
*
* @param earcon
- * The name of the earcon
+ * The name of the earcon.
+ * Example: <code>"[tick]"</code>
* @param filename
* The full path to the sound file (for example:
* "/sdcard/mysounds/tick.wav")
@@ -623,18 +651,18 @@
/**
* Speaks the string using the specified queuing strategy and speech
- * parameters. Note that the speech parameters are not universally supported
- * by all engines and will be treated as a hint. The TTS library will try to
- * fulfill these parameters as much as possible, but there is no guarantee
- * that the voice used will have the properties specified.
+ * parameters.
*
* @param text
* The string of text to be spoken.
* @param queueMode
* The queuing strategy to use.
- * See QUEUE_ADD and QUEUE_FLUSH.
+ * {@link #QUEUE_ADD} or {@link #QUEUE_FLUSH}.
* @param params
- * The hashmap of speech parameters to be used.
+ * The list of parameters to be used. Can be null if no parameters are given.
+ * They are specified using a (key, value) pair, where the key can be
+ * {@link Engine#KEY_PARAM_STREAM} or
+ * {@link Engine#KEY_PARAM_UTTERANCE_ID}.
*
* @return Code indicating success or failure. See {@link #ERROR} and {@link #SUCCESS}.
*/
@@ -690,9 +718,12 @@
* @param earcon
* The earcon that should be played
* @param queueMode
- * See QUEUE_ADD and QUEUE_FLUSH.
+ * {@link #QUEUE_ADD} or {@link #QUEUE_FLUSH}.
* @param params
- * The hashmap of parameters to be used.
+ * The list of parameters to be used. Can be null if no parameters are given.
+ * They are specified using a (key, value) pair, where the key can be
+ * {@link Engine#KEY_PARAM_STREAM} or
+ * {@link Engine#KEY_PARAM_UTTERANCE_ID}.
*
* @return Code indicating success or failure. See {@link #ERROR} and {@link #SUCCESS}.
*/
@@ -747,7 +778,11 @@
* @param durationInMs
* A long that indicates how long the silence should last.
* @param queueMode
- * See QUEUE_ADD and QUEUE_FLUSH.
+ * {@link #QUEUE_ADD} or {@link #QUEUE_FLUSH}.
+ * @param params
+ * The list of parameters to be used. Can be null if no parameters are given.
+ * They are specified using a (key, value) pair, where the key can be
+ * {@link Engine#KEY_PARAM_UTTERANCE_ID}.
*
* @return Code indicating success or failure. See {@link #ERROR} and {@link #SUCCESS}.
*/
@@ -791,9 +826,9 @@
/**
- * Returns whether or not the TTS is busy speaking.
+ * Returns whether or not the TextToSpeech engine is busy speaking.
*
- * @return Whether or not the TTS is busy speaking.
+ * @return Whether or not the TextToSpeech engine is busy speaking.
*/
public boolean isSpeaking() {
synchronized (mStartLock) {
@@ -827,7 +862,8 @@
/**
- * Stops speech from the TTS.
+ * Interrupts the current utterance (whether played or rendered to file) and discards other
+ * utterances in the queue.
*
* @return Code indicating success or failure. See {@link #ERROR} and {@link #SUCCESS}.
*/
@@ -865,15 +901,12 @@
/**
- * Sets the speech rate for the TTS engine.
+ * Sets the speech rate for the TextToSpeech engine.
*
- * Note that the speech rate is not universally supported by all engines and
- * will be treated as a hint. The TTS library will try to use the specified
- * speech rate, but there is no guarantee.
* This has no effect on any pre-recorded speech.
*
* @param speechRate
- * The speech rate for the TTS engine. 1 is the normal speed,
+ * The speech rate for the TextToSpeech engine. 1 is the normal speed,
* lower values slow down the speech (0.5 is half the normal speech rate),
* greater values accelerate it (2 is twice the normal speech rate).
*
@@ -917,15 +950,12 @@
/**
- * Sets the speech pitch for the TTS engine.
+ * Sets the speech pitch for the TextToSpeech engine.
*
- * Note that the pitch is not universally supported by all engines and
- * will be treated as a hint. The TTS library will try to use the specified
- * pitch, but there is no guarantee.
* This has no effect on any pre-recorded speech.
*
* @param pitch
- * The pitch for the TTS engine. 1 is the normal pitch,
+ * The pitch for the TextToSpeech engine. 1 is the normal pitch,
* lower values lower the tone of the synthesized voice,
* greater values increase it.
*
@@ -967,11 +997,11 @@
/**
- * Sets the language for the TTS engine.
- *
- * Note that the language is not universally supported by all engines and
- * will be treated as a hint. The TTS library will try to use the specified
- * language as represented by the Locale, but there is no guarantee.
+ * Sets the language for the TextToSpeech engine.
+ * The TextToSpeech engine will try to use the closest match to the specified
+ * language as represented by the Locale, but there is no guarantee that the exact same Locale
+ * will be used. Use {@link #isLanguageAvailable(Locale)} to check the level of support
+ * before choosing the language to use for the next utterances.
*
* @param loc
* The locale describing the language to be used.
@@ -1023,9 +1053,10 @@
/**
- * Returns a Locale instance describing the language currently being used by the TTS engine.
+ * Returns a Locale instance describing the language currently being used by the TextToSpeech
+ * engine.
* @return language, country (if any) and variant (if any) used by the engine stored in a Locale
- * instance, or null is the TTS engine has failed.
+ * instance, or null is the TextToSpeech engine has failed.
*/
public Locale getLanguage() {
synchronized (mStartLock) {
@@ -1063,7 +1094,7 @@
}
/**
- * Checks if the specified language as represented by the Locale is available.
+ * Checks if the specified language as represented by the Locale is available and supported.
*
* @param loc
* The Locale describing the language to be used.
@@ -1112,7 +1143,9 @@
* @param text
* The String of text that should be synthesized
* @param params
- * A hashmap of parameters.
+ * The list of parameters to be used. Can be null if no parameters are given.
+ * They are specified using a (key, value) pair, where the key can be
+ * {@link Engine#KEY_PARAM_UTTERANCE_ID}.
* @param filename
* The string that gives the full output filename; it should be
* something like "/sdcard/myappsounds/mysound.wav".
