java.lang.Object | |
↳ | android.speech.tts.TextToSpeech |
Synthesizes speech from text for immediate playback or to create a sound file.
A TextToSpeech instance can only be used to synthesize text once it has completed its
initialization. Implement the TextToSpeech.OnInitListener
to be
notified of the completion of the initialization.
When you are done using the TextToSpeech instance, call the shutdown()
method
to release the native resources used by the TextToSpeech engine.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
TextToSpeech.Engine | Constants and parameter names for controlling text-to-speech. | ||||||||||
TextToSpeech.EngineInfo | Information about an installed text-to-speech engine. | ||||||||||
TextToSpeech.OnInitListener | Interface definition of a callback to be invoked indicating the completion of the TextToSpeech engine initialization. | ||||||||||
TextToSpeech.OnUtteranceCompletedListener |
This interface was deprecated
in API level 18.
Use UtteranceProgressListener instead.
|
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | ACTION_TTS_QUEUE_PROCESSING_COMPLETED | Broadcast Action: The TextToSpeech synthesizer has completed processing of all the text in the speech queue. | |||||||||
int | ERROR | Denotes a generic operation failure. | |||||||||
int | LANG_AVAILABLE | Denotes the language is available for the language by the locale, but not the country and variant. | |||||||||
int | LANG_COUNTRY_AVAILABLE | Denotes the language is available for the language and country specified by the locale, but not the variant. | |||||||||
int | LANG_COUNTRY_VAR_AVAILABLE | Denotes the language is available exactly as specified by the locale. | |||||||||
int | LANG_MISSING_DATA | Denotes the language data is missing. | |||||||||
int | LANG_NOT_SUPPORTED | Denotes the language is not supported. | |||||||||
int | QUEUE_ADD | Queue mode where the new entry is added at the end of the playback queue. | |||||||||
int | QUEUE_FLUSH | Queue mode where all entries in the playback queue (media to be played and text to be synthesized) are dropped and replaced by the new entry. | |||||||||
int | SUCCESS | Denotes a successful operation. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
The constructor for the TextToSpeech class, using the default TTS engine.
| |||||||||||
The constructor for the TextToSpeech class, using the given TTS engine.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds a mapping between a string of text and a sound file.
| |||||||||||
Adds a mapping between a string of text and a sound resource in a
package.
| |||||||||||
Adds a mapping between a string of text and a sound resource in a
package.
| |||||||||||
Adds a mapping between a string of text and a sound file.
| |||||||||||
Checks whether the user's settings should override settings requested
by the calling application.
| |||||||||||
Gets the package name of the default speech synthesis engine.
| |||||||||||
Returns a Locale instance describing the language currently being used as the default
Text-to-speech language.
| |||||||||||
Gets a list of all installed TTS engines.
| |||||||||||
Queries the engine for the set of features it supports for a given locale.
| |||||||||||
Returns a Locale instance describing the language currently being used for synthesis
requests sent to the TextToSpeech engine.
| |||||||||||
Limit of length of input string passed to speak and synthesizeToFile.
| |||||||||||
Checks if the specified language as represented by the Locale is available and supported.
| |||||||||||
Checks whether the TTS engine is busy speaking.
| |||||||||||
Plays the earcon using the specified queueing mode and parameters.
| |||||||||||
Plays silence for the specified amount of time using the specified
queue mode.
| |||||||||||
This method was deprecated
in API level 14.
This doesn't inform callers when the TTS engine has been
initialized.
TextToSpeech(Context, OnInitListener, String)
can be used with the appropriate engine name. Also, there is no
guarantee that the engine specified will be loaded. If it isn't
installed or disabled, the user / system wide defaults will apply. | |||||||||||
Sets the text-to-speech language.
| |||||||||||
This method was deprecated
in API level 15.
Use
setOnUtteranceProgressListener(UtteranceProgressListener)
instead.
| |||||||||||
Sets the listener that will be notified of various events related to the
synthesis of a given utterance.
| |||||||||||
Sets the speech pitch for the TextToSpeech engine.
| |||||||||||
Sets the speech rate.
| |||||||||||
Releases the resources used by the TextToSpeech engine.
| |||||||||||
Speaks the string using the specified queuing strategy and speech parameters.
| |||||||||||
Interrupts the current utterance (whether played or rendered to file) and discards other
utterances in the queue.
| |||||||||||
Synthesizes the given text to a file using the specified parameters.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Broadcast Action: The TextToSpeech synthesizer has completed processing
of all the text in the speech queue.
Note that this notifies callers when the engine has finished has
processing text data. Audio playback might not have completed (or even started)
at this point. If you wish to be notified when this happens, see
TextToSpeech.OnUtteranceCompletedListener
.
Denotes a generic operation failure.
Denotes the language is available for the language by the locale, but not the country and variant.
Denotes the language is available for the language and country specified by the locale, but not the variant.
Denotes the language is available exactly as specified by the locale.
Denotes the language data is missing.
Denotes the language is not supported.
Queue mode where the new entry is added at the end of the playback queue.
Queue mode where all entries in the playback queue (media to be played and text to be synthesized) are dropped and replaced by the new entry. Queues are flushed with respect to a given calling app. Entries in the queue from other callees are not discarded.
Denotes a successful operation.
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.
context | The context this instance is running in. |
---|---|
listener | The TextToSpeech.OnInitListener that will be called when the
TextToSpeech engine has initialized. In a case of a failure the listener
may be called immediately, before TextToSpeech instance is fully constructed.
|
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.
context | The context this instance is running in. |
---|---|
listener | The TextToSpeech.OnInitListener that will be called when the
TextToSpeech engine has initialized. In a case of a failure the listener
may be called immediately, before TextToSpeech instance is fully constructed. |
engine | Package name of the TTS engine to use. |
Adds a mapping between a string of text and a sound file. Use this to add custom earcons.
earcon | The name of the earcon.
Example: "[tick]" |
---|---|
filename | The full path to the sound file (for example: "/sdcard/mysounds/tick.wav") |
Adds a mapping between a string of text and a sound resource in a package. Use this to add custom earcons.
earcon | The name of the earcon.
Example: "[tick]" |
---|---|
packagename | the package name of the application that contains the
resource. This can for instance be the package name of your own application.
Example: "com.google.marvin.compass" The package name can be found in the AndroidManifest.xml of the application containing the resource.
|
resourceId | Example: R.raw.tick_snd |
Adds a mapping between a string of text and a sound resource in a
package. After a call to this method, subsequent calls to
speak(String, int, HashMap)
will play the specified sound resource
if it is available, or synthesize the text it is missing.
text | The string of text. Example: "south_south_east" |
---|---|
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. Example: "com.google.marvin.compass" The packagename can be found in the AndroidManifest.xml of your application.
|
resourceId | Example: R.raw.south_south_east |
Adds a mapping between a string of text and a sound file. Using this, it
is possible to add custom pronounciations for a string of text.
After a call to this method, subsequent calls to speak(String, int, HashMap)
will play the specified sound resource if it is available, or synthesize the text it is
missing.
text | The string of text. Example: "south_south_east" |
---|---|
filename | The full path to the sound file (for example: "/sdcard/mysounds/hello.wav") |
Checks whether the user's settings should override settings requested by the calling application. As of the Ice cream sandwich release, user settings never forcibly override the app's settings.
Gets the package name of the default speech synthesis engine.
Returns a Locale instance describing the language currently being used as the default Text-to-speech language.
null
on error.
Gets a list of all installed TTS engines.
null
.
Queries the engine for the set of features it supports for a given locale.
Features can either be framework defined, e.g.
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
speak(String, int, java.util.HashMap)
and
synthesizeToFile(String, java.util.HashMap, String)
.
Features are boolean flags, and their values in the synthesis parameters
must be behave as per parseBoolean(String)
.
locale | The locale to query features for. |
---|
null
on error.
Returns a Locale instance describing the language currently being used for synthesis
requests sent to the TextToSpeech engine.
In Android 4.2 and before (API <= 17) this function returns the language that is currently
being used by the TTS engine. That is the last language set by this or any other
client by a setLanguage(Locale)
call to the same engine.
In Android versions after 4.2 this function returns the language that is currently being
used for the synthesis requests sent from this client. That is the last language set
by a setLanguage(Locale)
call on this instance.
null
on error.
Limit of length of input string passed to speak and synthesizeToFile.
Checks if the specified language as represented by the Locale is available and supported.
loc | The Locale describing the language to be used. |
---|
LANG_AVAILABLE
,
LANG_COUNTRY_AVAILABLE
, LANG_COUNTRY_VAR_AVAILABLE
,
LANG_MISSING_DATA
and LANG_NOT_SUPPORTED
.
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 written to a file. There might be a finite lag between this point, and when the audio hardware completes playback.
true
if the TTS engine is speaking.
Plays the earcon using the specified queueing mode and parameters.
The earcon must already have been added with addEarcon(String, String)
or
addEarcon(String, String, int)
.
This method is asynchronous, i.e. the method just adds the request to the queue of TTS
requests and then returns. The synthesis might not have finished (or even started!) at the
time when this method returns. In order to reliably detect errors during synthesis,
we recommend setting an utterance progress listener (see
setOnUtteranceProgressListener(UtteranceProgressListener)
) and using the
KEY_PARAM_UTTERANCE_ID
parameter.
earcon | The earcon that should be played |
---|---|
queueMode | QUEUE_ADD or QUEUE_FLUSH . |
params | Parameters for the request. Can be null.
Supported parameter names:
KEY_PARAM_STREAM ,
KEY_PARAM_UTTERANCE_ID .
Engine specific parameters may be passed in but the parameter keys
must be prefixed by the name of the engine they are intended for. For example
the keys "com.svox.pico_foo" and "com.svox.pico:bar" will be passed to the
engine named "com.svox.pico" if it is being used. |
Plays silence for the specified amount of time using the specified
queue mode.
This method is asynchronous, i.e. the method just adds the request to the queue of TTS
requests and then returns. The synthesis might not have finished (or even started!) at the
time when this method returns. In order to reliably detect errors during synthesis,
we recommend setting an utterance progress listener (see
setOnUtteranceProgressListener(UtteranceProgressListener)
) and using the
KEY_PARAM_UTTERANCE_ID
parameter.
durationInMs | The duration of the silence. |
---|---|
queueMode | QUEUE_ADD or QUEUE_FLUSH . |
params | Parameters for the request. Can be null.
Supported parameter names:
KEY_PARAM_UTTERANCE_ID .
Engine specific parameters may be passed in but the parameter keys
must be prefixed by the name of the engine they are intended for. For example
the keys "com.svox.pico_foo" and "com.svox.pico:bar" will be passed to the
engine named "com.svox.pico" if it is being used. |
This method was deprecated
in API level 14.
This doesn't inform callers when the TTS engine has been
initialized. TextToSpeech(Context, OnInitListener, String)
can be used with the appropriate engine name. Also, there is no
guarantee that the engine specified will be loaded. If it isn't
installed or disabled, the user / system wide defaults will apply.
Sets the TTS engine to use.
enginePackageName | The package name for the synthesis engine (e.g. "com.svox.pico") |
---|
Sets the text-to-speech language.
The TTS 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 isLanguageAvailable(Locale)
to check the level of support
before choosing the language to use for the next utterances.
loc | The locale describing the language to be used. |
---|
LANG_AVAILABLE
,
LANG_COUNTRY_AVAILABLE
, LANG_COUNTRY_VAR_AVAILABLE
,
LANG_MISSING_DATA
and LANG_NOT_SUPPORTED
.
This method was deprecated
in API level 15.
Use setOnUtteranceProgressListener(UtteranceProgressListener)
instead.
Sets the listener that will be notified when synthesis of an utterance completes.
listener | The listener to use. |
---|
Sets the listener that will be notified of various events related to the
synthesis of a given utterance.
See UtteranceProgressListener
and
KEY_PARAM_UTTERANCE_ID
.
listener | the listener to use. |
---|
Sets the speech rate. This has no effect on any pre-recorded speech.
speechRate | Speech rate. 1.0 is the normal speech rate,
lower values slow down the speech (0.5 is half the normal speech rate),
greater values accelerate it (2.0 is twice the normal speech rate). |
---|
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.
Speaks the string using the specified queuing strategy and speech parameters.
This method is asynchronous, i.e. the method just adds the request to the queue of TTS
requests and then returns. The synthesis might not have finished (or even started!) at the
time when this method returns. In order to reliably detect errors during synthesis,
we recommend setting an utterance progress listener (see
setOnUtteranceProgressListener(UtteranceProgressListener)
) and using the
KEY_PARAM_UTTERANCE_ID
parameter.
text | The string of text to be spoken. No longer than
getMaxSpeechInputLength() characters. |
---|---|
queueMode | The queuing strategy to use, QUEUE_ADD or QUEUE_FLUSH . |
params | Parameters for the request. Can be null.
Supported parameter names:
KEY_PARAM_STREAM ,
KEY_PARAM_UTTERANCE_ID ,
KEY_PARAM_VOLUME ,
KEY_PARAM_PAN .
Engine specific parameters may be passed in but the parameter keys
must be prefixed by the name of the engine they are intended for. For example
the keys "com.svox.pico_foo" and "com.svox.pico:bar" will be passed to the
engine named "com.svox.pico" if it is being used. |
Synthesizes the given text to a file using the specified parameters.
This method is asynchronous, i.e. the method just adds the request to the queue of TTS
requests and then returns. The synthesis might not have finished (or even started!) at the
time when this method returns. In order to reliably detect errors during synthesis,
we recommend setting an utterance progress listener (see
setOnUtteranceProgressListener(UtteranceProgressListener)
) and using the
KEY_PARAM_UTTERANCE_ID
parameter.
text | The text that should be synthesized. No longer than
getMaxSpeechInputLength() characters. |
---|---|
params | Parameters for the request. Can be null.
Supported parameter names:
KEY_PARAM_UTTERANCE_ID .
Engine specific parameters may be passed in but the parameter keys
must be prefixed by the name of the engine they are intended for. For example
the keys "com.svox.pico_foo" and "com.svox.pico:bar" will be passed to the
engine named "com.svox.pico" if it is being used. |
filename | Absolute file filename to write the generated audio data to.It should be something like "/sdcard/myappsounds/mysound.wav". |