summaryrefslogtreecommitdiffstats
path: root/core/java/android/speech
diff options
context:
space:
mode:
Diffstat (limited to 'core/java/android/speech')
-rw-r--r--core/java/android/speech/RecognitionResult.java162
-rw-r--r--core/java/android/speech/RecognitionServiceUtil.java24
-rwxr-xr-xcore/java/android/speech/tts/TextToSpeech.java197
3 files changed, 230 insertions, 153 deletions
diff --git a/core/java/android/speech/RecognitionResult.java b/core/java/android/speech/RecognitionResult.java
index 978106b..95715ee 100644
--- a/core/java/android/speech/RecognitionResult.java
+++ b/core/java/android/speech/RecognitionResult.java
@@ -1,50 +1,63 @@
/*
- * Copyright (C) 2008 Google Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not
- * use this file except in compliance with the License. You may obtain a copy of
- * the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
* Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations under
- * the License.
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
*/
+
package android.speech;
import android.os.Parcel;
import android.os.Parcelable;
/**
- * RecognitionResult is a passive object that stores a single recognized
- * query and its search result.
- * TODO: revisit and improve. May be we should have a separate result
- * object for each type, and put them (type/value) in bundle?
+ * RecognitionResult is a passive object that stores a single recognized query
+ * and its search result.
*
+ * TODO: Revisit and improve this class, reconciling the different types of actions and
+ * the different ways they are represented. Maybe we should have a separate result object
+ * for each type, and put them (type/value) in bundle?
* {@hide}
*/
public class RecognitionResult implements Parcelable {
/**
* Status of the recognize request.
*/
- public static final int NETWORK_TIMEOUT = 1; // Network operation timed out.
- public static final int NETWORK_ERROR = 2; // Other networkrelated errors.
- public static final int AUDIO_ERROR = 3; // Audio recording error.
- public static final int SERVER_ERROR = 4; // Server sends error status.
- public static final int CLIENT_ERROR = 5; // Other client side errors.
- public static final int SPEECH_TIMEOUT = 6; // No speech input
- public static final int NO_MATCH = 7; // No recognition result matched.
- public static final int SERVICE_BUSY = 8; // RecognitionService busy.
+ public static final int NETWORK_TIMEOUT = 1; // Network operation timed out.
+
+ public static final int NETWORK_ERROR = 2; // Other network related errors.
+
+ public static final int AUDIO_ERROR = 3; // Audio recording error.
+
+ public static final int SERVER_ERROR = 4; // Server sends error status.
+
+ public static final int CLIENT_ERROR = 5; // Other client side errors.
+
+ public static final int SPEECH_TIMEOUT = 6; // No speech input
+
+ public static final int NO_MATCH = 7; // No recognition result matched.
+
+ public static final int SERVICE_BUSY = 8; // RecognitionService busy.
/**
- * Type of the recognition results.
+ * Type of the recognition results.
*/
- public static final int RAW_RECOGNITION_RESULT = 0;
- public static final int WEB_SEARCH_RESULT = 1;
+ public static final int RAW_RECOGNITION_RESULT = 0;
+
+ public static final int WEB_SEARCH_RESULT = 1;
+
public static final int CONTACT_RESULT = 2;
+
+ public static final int ACTION_RESULT = 3;
/**
* A factory method to create a raw RecognitionResult
@@ -56,11 +69,12 @@ public class RecognitionResult implements Parcelable {
}
/**
- * A factory method to create RecognitionResult for contacts.
+ * A factory method to create a RecognitionResult for contacts.
*
* @param contact the contact name.
* @param phoneType the phone type.
- * @param callAction whether this result included a command to "call", or just the contact name.
+ * @param callAction whether this result included a command to "call", or
+ * just the contact name.
*/
public static RecognitionResult newContactResult(String contact, int phoneType,
boolean callAction) {
@@ -68,49 +82,59 @@ public class RecognitionResult implements Parcelable {
}
/**
- * A factory method to create a RecognitionResult for Web Search Query.
+ * A factory method to create a RecognitionResult for a web search query.
*
- * @param query the query string.
+ * @param query the query string.
* @param html the html page of the search result.
- * @param url the url that performs the search with the query.
+ * @param url the url that performs the search with the query.
*/
public static RecognitionResult newWebResult(String query, String html, String url) {
return new RecognitionResult(WEB_SEARCH_RESULT, query, html, url);
}
- public static final Parcelable.Creator<RecognitionResult> CREATOR
- = new Parcelable.Creator<RecognitionResult>() {
+ /**
+ * A factory method to create a RecognitionResult for an action.
+ *
+ * @param action the action type
+ * @param query the query string associated with that action.
+ */
+ public static RecognitionResult newActionResult(int action, String query) {
+ return new RecognitionResult(ACTION_RESULT, action, query);
+ }
- public RecognitionResult createFromParcel(Parcel in) {
- return new RecognitionResult(in);
- }
+ public static final Parcelable.Creator<RecognitionResult> CREATOR =
+ new Parcelable.Creator<RecognitionResult>() {
+
+ public RecognitionResult createFromParcel(Parcel in) {
+ return new RecognitionResult(in);
+ }
- public RecognitionResult[] newArray(int size) {
- return new RecognitionResult[size];
- }
- };
+ public RecognitionResult[] newArray(int size) {
+ return new RecognitionResult[size];
+ }
+ };
/**
* Result type.
*/
public final int mResultType;
- /**
- * The recognized string when mResultType is WEB_SEARCH_RESULT.
- * The name of the contact when mResultType is CONTACT_RESULT.
+ /**
+ * The recognized string when mResultType is WEB_SEARCH_RESULT. The name of
+ * the contact when mResultType is CONTACT_RESULT. The relevant query when
+ * mResultType is ACTION_RESULT.
*/
public final String mText;
/**
- * The HTML result page for the query. If this is null, then the
- * application must use the url field to get the HTML result page.
+ * The HTML result page for the query. If this is null, then the application
+ * must use the url field to get the HTML result page.
*/
public final String mHtml;
/**
- * The url to get the result page for the query string. The
- * application must use this url instead of performing the search
- * with the query.
+ * The url to get the result page for the query string. The application must
+ * use this url instead of performing the search with the query.
*/
public final String mUrl;
@@ -120,17 +144,33 @@ public class RecognitionResult implements Parcelable {
public final int mPhoneType;
/**
- * Whether a contact recognition result included a command to "call". This is valid only
- * when mResultType == CONTACT_RESULT.
+ * Action type. This is valid only when mResultType == ACTION_RESULT.
+ */
+ public final int mAction;
+
+ /**
+ * Whether a contact recognition result included a command to "call". This
+ * is valid only when mResultType == CONTACT_RESULT.
*/
public final boolean mCallAction;
+ private RecognitionResult(int type, int action, String query) {
+ mResultType = type;
+ mAction = action;
+ mText = query;
+ mHtml = null;
+ mUrl = null;
+ mPhoneType = -1;
+ mCallAction = false;
+ }
+
private RecognitionResult(int type, String query, String html, String url) {
mResultType = type;
mText = query;
mHtml = html;
mUrl = url;
mPhoneType = -1;
+ mAction = -1;
mCallAction = false;
}
@@ -140,15 +180,17 @@ public class RecognitionResult implements Parcelable {
mPhoneType = phoneType;
mHtml = null;
mUrl = null;
+ mAction = -1;
mCallAction = callAction;
}
-
+
private RecognitionResult(Parcel in) {
mResultType = in.readInt();
mText = in.readString();
- mHtml= in.readString();
- mUrl= in.readString();
+ mHtml = in.readString();
+ mUrl = in.readString();
mPhoneType = in.readInt();
+ mAction = in.readInt();
mCallAction = (in.readInt() == 1);
}
@@ -158,15 +200,17 @@ public class RecognitionResult implements Parcelable {
out.writeString(mHtml);
out.writeString(mUrl);
out.writeInt(mPhoneType);
+ out.writeInt(mAction);
out.writeInt(mCallAction ? 1 : 0);
}
-
-
+
@Override
public String toString() {
- String resultType[] = { "RAW", "WEB", "CONTACT" };
- return "[type=" + resultType[mResultType] +
- ", text=" + mText+ ", mUrl=" + mUrl + ", html=" + mHtml + "]";
+ String resultType[] = {
+ "RAW", "WEB", "CONTACT", "ACTION"
+ };
+ return "[type=" + resultType[mResultType] + ", text=" + mText + ", mUrl=" + mUrl
+ + ", html=" + mHtml + ", mAction=" + mAction + ", mCallAction=" + mCallAction + "]";
}
public int describeContents() {
diff --git a/core/java/android/speech/RecognitionServiceUtil.java b/core/java/android/speech/RecognitionServiceUtil.java
index a8c7868..4207543 100644
--- a/core/java/android/speech/RecognitionServiceUtil.java
+++ b/core/java/android/speech/RecognitionServiceUtil.java
@@ -1,17 +1,17 @@
/*
- * Copyright (C) 2009 Google Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not
- * use this file except in compliance with the License. You may obtain a copy of
- * the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
* Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations under
- * the License.
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
*/
package android.speech;
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 @@ import java.util.Locale;
/**
*
* 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 class TextToSpeech {
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 @@ public class TextToSpeech {
/**
- * 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 class TextToSpeech {
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 class TextToSpeech {
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 @@ public class TextToSpeech {
* 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 @@ public class TextToSpeech {
// 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 @@ public class TextToSpeech {
/**
* 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 @@ public class TextToSpeech {
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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
* 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 @@ public class TextToSpeech {
* </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 @@ public class TextToSpeech {
/**
* 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 @@ public class TextToSpeech {
/**
* 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>&lt;manifest xmlns:android=&quot;...&quot;
* package=&quot;<b>com.google.marvin.compass</b>&quot;&gt;</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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
* 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 @@ public class TextToSpeech {
* @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 @@ public class TextToSpeech {
* @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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
/**
- * 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 @@ public class TextToSpeech {
}
/**
- * 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 @@ public class TextToSpeech {
* @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".
generated by cgit v1.1 at 2025-08-15 20:11:05 +0000