public class TextToSpeech extends Object
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.
Modifier and Type | Class and Description |
---|---|
class |
TextToSpeech.Engine
Constants and parameter names for controlling text-to-speech.
|
static class |
TextToSpeech.EngineInfo
Information about an installed text-to-speech engine.
|
static interface |
TextToSpeech.Error |
static interface |
TextToSpeech.OnInitListener
Interface definition of a callback to be invoked indicating the completion of the
TextToSpeech engine initialization.
|
static interface |
TextToSpeech.OnUtteranceCompletedListener
Deprecated.
Use
UtteranceProgressListener instead. |
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_TTS_QUEUE_PROCESSING_COMPLETED
Broadcast Action: The TextToSpeech synthesizer has completed processing
of all the text in the speech queue.
|
static int |
ERROR
Denotes a generic operation failure.
|
static int |
ERROR_INVALID_REQUEST
Denotes a failure caused by an invalid request.
|
static int |
ERROR_NETWORK
Denotes a failure caused by a network connectivity problems.
|
static int |
ERROR_NETWORK_TIMEOUT
Denotes a failure caused by network timeout.
|
static int |
ERROR_NOT_INSTALLED_YET
Denotes a failure caused by an unfinished download of the voice data.
|
static int |
ERROR_OUTPUT
Denotes a failure related to the output (audio device or a file).
|
static int |
ERROR_SERVICE
Denotes a failure of a TTS service.
|
static int |
ERROR_SYNTHESIS
Denotes a failure of a TTS engine to synthesize the given input.
|
static int |
LANG_AVAILABLE
Denotes the language is available for the language by the locale,
but not the country and variant.
|
static int |
LANG_COUNTRY_AVAILABLE
Denotes the language is available for the language and country specified
by the locale, but not the variant.
|
static int |
LANG_COUNTRY_VAR_AVAILABLE
Denotes the language is available exactly as specified by the locale.
|
static int |
LANG_MISSING_DATA
Denotes the language data is missing.
|
static int |
LANG_NOT_SUPPORTED
Denotes the language is not supported.
|
static int |
QUEUE_ADD
Queue mode where the new entry is added at the end of the playback queue.
|
static 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.
|
static int |
STOPPED
Denotes a stop requested by a client.
|
static int |
SUCCESS
Denotes a successful operation.
|
Constructor and Description |
---|
TextToSpeech(Context context,
TextToSpeech.OnInitListener listener)
The constructor for the TextToSpeech class, using the default TTS engine.
|
TextToSpeech(Context context,
TextToSpeech.OnInitListener listener,
String engine)
The constructor for the TextToSpeech class, using the given TTS engine.
|
TextToSpeech(Context context,
TextToSpeech.OnInitListener listener,
String engine,
String packageName,
boolean useFallback)
Used by the framework to instantiate TextToSpeech objects with a supplied
package name, instead of using
Context.getPackageName() |
Modifier and Type | Method and Description |
---|---|
int |
addEarcon(String earcon,
File file)
Adds a mapping between a string of text and a sound file.
|
int |
addEarcon(String earcon,
String filename)
Deprecated.
As of API level 21, replaced by
addEarcon(String, File) . |
int |
addEarcon(String earcon,
String packagename,
int resourceId)
Adds a mapping between a string of text and a sound resource in a
package.
|
int |
addSpeech(CharSequence text,
File file)
Adds a mapping between a CharSequence (may be spanned with TtsSpans and a sound file.
|
int |
addSpeech(CharSequence text,
String packagename,
int resourceId)
Adds a mapping between a CharSequence (may be spanned with TtsSpans) of text
and a sound resource in a package.
|
int |
addSpeech(String text,
String filename)
Adds a mapping between a string of text and a sound file.
|
int |
addSpeech(String text,
String packagename,
int resourceId)
Adds a mapping between a string of text and a sound resource in a
package.
|
boolean |
areDefaultsEnforced()
Deprecated.
|
Set<Locale> |
getAvailableLanguages()
Query the engine about the set of available languages.
|
String |
getCurrentEngine() |
String |
getDefaultEngine()
Gets the package name of the default speech synthesis engine.
|
Locale |
getDefaultLanguage()
Deprecated.
As of API level 21, use
getDefaultVoice().getLocale() (getDefaultVoice() ) |
Voice |
getDefaultVoice()
Returns a Voice instance that's the default voice for the default Text-to-speech language.
|
List<TextToSpeech.EngineInfo> |
getEngines()
Gets a list of all installed TTS engines.
|
Set<String> |
getFeatures(Locale locale)
Deprecated.
As of API level 21, please use voices. In order to query features of the voice,
call
getVoices() to retrieve the list of available voices and
Voice.getFeatures() to retrieve the set of features. |
Locale |
getLanguage()
Deprecated.
As of API level 21, please use
getVoice().getLocale()
(getVoice() ). |
static int |
getMaxSpeechInputLength()
Limit of length of input string passed to speak and synthesizeToFile.
|
Voice |
getVoice()
Returns a Voice instance describing the voice currently being used for synthesis
requests sent to the TextToSpeech engine.
|
Set<Voice> |
getVoices()
Query the engine about the set of available voices.
|
int |
isLanguageAvailable(Locale loc)
Checks if the specified language as represented by the Locale is available and supported.
|
boolean |
isSpeaking()
Checks whether the TTS engine is busy speaking.
|
int |
playEarcon(String earcon,
int queueMode,
Bundle params,
String utteranceId)
Plays the earcon using the specified queueing mode and parameters.
|
int |
playEarcon(String earcon,
int queueMode,
HashMap<String,String> params)
Deprecated.
As of API level 21, replaced by
playEarcon(String, int, Bundle, String) . |
int |
playSilence(long durationInMs,
int queueMode,
HashMap<String,String> params)
Deprecated.
As of API level 21, replaced by
playSilentUtterance(long, int, String) . |
int |
playSilentUtterance(long durationInMs,
int queueMode,
String utteranceId)
Plays silence for the specified amount of time using the specified
queue mode.
|
int |
setAudioAttributes(AudioAttributes audioAttributes)
Sets the audio attributes to be used when speaking text or playing
back a file.
|
int |
setEngineByPackageName(String enginePackageName)
Deprecated.
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. |
int |
setLanguage(Locale loc)
Sets the text-to-speech language.
|
int |
setOnUtteranceCompletedListener(TextToSpeech.OnUtteranceCompletedListener listener)
Deprecated.
|
int |
setOnUtteranceProgressListener(UtteranceProgressListener listener)
Sets the listener that will be notified of various events related to the
synthesis of a given utterance.
|
int |
setPitch(float pitch)
Sets the speech pitch for the TextToSpeech engine.
|
int |
setSpeechRate(float speechRate)
Sets the speech rate.
|
int |
setVoice(Voice voice)
Sets the text-to-speech voice.
|
void |
shutdown()
Releases the resources used by the TextToSpeech engine.
|
int |
speak(CharSequence text,
int queueMode,
Bundle params,
String utteranceId)
Speaks the text using the specified queuing strategy and speech parameters, the text may
be spanned with TtsSpans.
|
int |
speak(String text,
int queueMode,
HashMap<String,String> params)
Deprecated.
As of API level 21, replaced by
speak(CharSequence, int, Bundle, String) . |
int |
stop()
Interrupts the current utterance (whether played or rendered to file) and discards other
utterances in the queue.
|
int |
synthesizeToFile(CharSequence text,
Bundle params,
File file,
String utteranceId)
Synthesizes the given text to a file using the specified parameters.
|
int |
synthesizeToFile(String text,
HashMap<String,String> params,
String filename)
Deprecated.
As of API level 21, replaced by
synthesizeToFile(CharSequence, Bundle, File, String) . |
public static final int SUCCESS
public static final int ERROR
public static final int STOPPED
public static final int ERROR_SYNTHESIS
public static final int ERROR_SERVICE
public static final int ERROR_OUTPUT
public static final int ERROR_NETWORK
public static final int ERROR_NETWORK_TIMEOUT
public static final int ERROR_INVALID_REQUEST
public static final int ERROR_NOT_INSTALLED_YET
public static final int QUEUE_FLUSH
public static final int QUEUE_ADD
public static final int LANG_COUNTRY_VAR_AVAILABLE
public static final int LANG_COUNTRY_AVAILABLE
public static final int LANG_AVAILABLE
public static final int LANG_MISSING_DATA
public static final int LANG_NOT_SUPPORTED
public static final String ACTION_TTS_QUEUE_PROCESSING_COMPLETED
TextToSpeech.OnUtteranceCompletedListener
.public TextToSpeech(Context context, TextToSpeech.OnInitListener listener)
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.public TextToSpeech(Context context, TextToSpeech.OnInitListener listener, String engine)
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.public TextToSpeech(Context context, TextToSpeech.OnInitListener listener, String engine, String packageName, boolean useFallback)
Context.getPackageName()
public void shutdown()
public int addSpeech(String text, String packagename, @RawRes int resourceId)
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.
<manifest xmlns:android="..."
package="com.google.marvin.compass">
resourceId
- Example: R.raw.south_south_east
ERROR
and SUCCESS
.public int addSpeech(CharSequence text, String packagename, @RawRes int resourceId)
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.
<manifest xmlns:android="..."
package="com.google.marvin.compass">
resourceId
- Example: R.raw.south_south_east
ERROR
and SUCCESS
.public int addSpeech(String text, String filename)
speak(String, int, HashMap)
will play the specified sound resource if it is available, or synthesize the text it is
missing.public int addSpeech(CharSequence text, File file)
speak(String, int, HashMap)
will play the specified sound resource if it is available, or synthesize the text it is
missing.public int addEarcon(String earcon, String packagename, @RawRes int resourceId)
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"
<manifest xmlns:android="..."
package="com.google.marvin.compass">
resourceId
- Example: R.raw.tick_snd
ERROR
and SUCCESS
.playEarcon(String, int, HashMap)
@Deprecated public int addEarcon(String earcon, String filename)
addEarcon(String, File)
.earcon
- The name of the earcon.
Example: "[tick]"
filename
- The full path to the sound file (for example:
"/sdcard/mysounds/tick.wav")ERROR
and SUCCESS
.playEarcon(String, int, HashMap)
public int addEarcon(String earcon, File file)
earcon
- The name of the earcon.
Example: "[tick]"
file
- File object pointing to the sound file.ERROR
and SUCCESS
.playEarcon(String, int, HashMap)
public int speak(CharSequence text, int queueMode, Bundle params, String utteranceId)
setOnUtteranceProgressListener(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.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:
TextToSpeech.Engine.KEY_PARAM_STREAM
,
TextToSpeech.Engine.KEY_PARAM_VOLUME
,
TextToSpeech.Engine.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.utteranceId
- An unique identifier for this request.ERROR
or SUCCESS
of queuing the speak operation.@Deprecated public int speak(String text, int queueMode, HashMap<String,String> params)
speak(CharSequence, int, Bundle, String)
.setOnUtteranceProgressListener(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.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:
TextToSpeech.Engine.KEY_PARAM_STREAM
,
TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID
,
TextToSpeech.Engine.KEY_PARAM_VOLUME
,
TextToSpeech.Engine.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.ERROR
or SUCCESS
of queuing the speak operation.public int playEarcon(String earcon, int queueMode, Bundle params, String utteranceId)
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(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID
parameter.earcon
- The earcon that should be playedqueueMode
- QUEUE_ADD
or QUEUE_FLUSH
.params
- Parameters for the request. Can be null.
Supported parameter names:
TextToSpeech.Engine.KEY_PARAM_STREAM
,
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.ERROR
or SUCCESS
of queuing the playEarcon operation.@Deprecated public int playEarcon(String earcon, int queueMode, HashMap<String,String> params)
playEarcon(String, int, Bundle, String)
.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(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID
parameter.earcon
- The earcon that should be playedqueueMode
- QUEUE_ADD
or QUEUE_FLUSH
.params
- Parameters for the request. Can be null.
Supported parameter names:
TextToSpeech.Engine.KEY_PARAM_STREAM
,
TextToSpeech.Engine.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.ERROR
or SUCCESS
of queuing the playEarcon operation.public int playSilentUtterance(long durationInMs, int queueMode, String utteranceId)
setOnUtteranceProgressListener(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID
parameter.durationInMs
- The duration of the silence.queueMode
- QUEUE_ADD
or QUEUE_FLUSH
.utteranceId
- An unique identifier for this request.ERROR
or SUCCESS
of queuing the playSilentUtterance operation.@Deprecated public int playSilence(long durationInMs, int queueMode, HashMap<String,String> params)
playSilentUtterance(long, int, String)
.setOnUtteranceProgressListener(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.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:
TextToSpeech.Engine.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.ERROR
or SUCCESS
of queuing the playSilence operation.@Deprecated public Set<String> getFeatures(Locale locale)
getVoices()
to retrieve the list of available voices and
Voice.getFeatures()
to retrieve the set of features.TextToSpeech.Engine.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 values are strings and their values must meet restrictions described in their
documentation.locale
- The locale to query features for.null
on error.public boolean isSpeaking()
true
if the TTS engine is speaking.public int stop()
public int setSpeechRate(float speechRate)
public int setPitch(float pitch)
public int setAudioAttributes(AudioAttributes audioAttributes)
public String getCurrentEngine()
@Deprecated public Locale getDefaultLanguage()
getDefaultVoice().getLocale()
(getDefaultVoice()
)getLanguage()
. Please refer to getLanguage()
for more information.null
on error.public int setLanguage(Locale loc)
isLanguageAvailable(Locale)
to check the level of support
before choosing the language to use for the next utterances.
This method sets the current voice to the default one for the given Locale;
getVoice()
can be used to retrieve it.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
.@Deprecated public Locale getLanguage()
getVoice().getLocale()
(getVoice()
).setLanguage(java.util.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(java.util.Locale)
call on this instance.
If a voice is set (by setVoice(Voice)
), getLanguage will return the language of
the currently set voice.
Please note that the Locale object returned by this method is NOT a valid Locale object. Its
language field contains a three-letter ISO 639-2/T code (where a proper Locale would use
a two-letter ISO 639-1 code), and the country field contains a three-letter ISO 3166 country
code (where a proper Locale would use a two-letter ISO 3166-1 code).null
on error.public Set<Locale> getAvailableLanguages()
public Set<Voice> getVoices()
setVoice(Voice)
,
Voice
public int setVoice(Voice voice)
voice
- One of objects returned by getVoices()
.ERROR
or SUCCESS
.getVoices()
,
Voice
public Voice getVoice()
null
if not set or on error.getVoices()
,
setVoice(android.speech.tts.Voice)
,
Voice
public Voice getDefaultVoice()
null
if not set or
on error.public int isLanguageAvailable(Locale loc)
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
.public int synthesizeToFile(CharSequence text, Bundle params, File file, String utteranceId)
setOnUtteranceProgressListener(android.speech.tts.UtteranceProgressListener)
).text
- The text that should be synthesized. No longer than
getMaxSpeechInputLength()
characters.params
- Parameters for the request. Can be null.
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.file
- File to write the generated audio data to.utteranceId
- An unique identifier for this request.ERROR
or SUCCESS
of queuing the synthesizeToFile operation.@Deprecated public int synthesizeToFile(String text, HashMap<String,String> params, String filename)
synthesizeToFile(CharSequence, Bundle, File, String)
.setOnUtteranceProgressListener(android.speech.tts.UtteranceProgressListener)
) and using the
TextToSpeech.Engine.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:
TextToSpeech.Engine.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".ERROR
or SUCCESS
of queuing the synthesizeToFile operation.@Deprecated public int setOnUtteranceCompletedListener(TextToSpeech.OnUtteranceCompletedListener listener)
setOnUtteranceProgressListener(UtteranceProgressListener)
instead.public int setOnUtteranceProgressListener(UtteranceProgressListener listener)
UtteranceProgressListener
and
TextToSpeech.Engine.KEY_PARAM_UTTERANCE_ID
.@Deprecated public int setEngineByPackageName(String enginePackageName)
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.public String getDefaultEngine()
@Deprecated public boolean areDefaultsEnforced()
public List<TextToSpeech.EngineInfo> getEngines()
null
.public static int getMaxSpeechInputLength()