public class

TextToSpeech

extends Object
java.lang.Object
   ↳ android.speech.tts.TextToSpeech

Class Overview

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.

Summary

Nested Classes
class TextToSpeech.Engine Internal constants for the TextToSpeech functionality  
interface TextToSpeech.OnInitListener Interface definition of a callback to be invoked indicating the completion of the TextToSpeech engine initialization. 
interface TextToSpeech.OnUtteranceCompletedListener Interface definition of a callback to be invoked indicating the TextToSpeech engine has completed synthesizing an utterance with an utterance ID set. 
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
TextToSpeech(Context context, TextToSpeech.OnInitListener listener)
The constructor for the TextToSpeech class.
Public Methods
int addEarcon(String earcon, String filename)
Adds a mapping between a string of text and a sound 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(String text, String packagename, int resourceId)
Adds a mapping between a string 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.
boolean areDefaultsEnforced()
Returns whether or not the user is forcing their defaults to override the Text-To-Speech settings set by applications.
String getDefaultEngine()
Gets the packagename of the default speech synthesis engine.
Locale getLanguage()
Returns a Locale instance describing the language currently being used by the TextToSpeech engine.
int isLanguageAvailable(Locale loc)
Checks if the specified language as represented by the Locale is available and supported.
boolean isSpeaking()
Returns whether or not the TextToSpeech engine is busy speaking.
int playEarcon(String earcon, int queueMode, HashMap<String, String> params)
Plays the earcon using the specified queueing mode and parameters.
int playSilence(long durationInMs, int queueMode, HashMap<String, String> params)
Plays silence for the specified amount of time using the specified queue mode.
int setEngineByPackageName(String enginePackageName)
Sets the speech synthesis engine to be used by its packagename.
int setLanguage(Locale loc)
Sets the language for the TextToSpeech engine.
int setOnUtteranceCompletedListener(TextToSpeech.OnUtteranceCompletedListener listener)
Sets the OnUtteranceCompletedListener that will fire when an utterance completes.
int setPitch(float pitch)
Sets the speech pitch for the TextToSpeech engine.
int setSpeechRate(float speechRate)
Sets the speech rate for the TextToSpeech engine.
void shutdown()
Releases the resources used by the TextToSpeech engine.
int speak(String text, int queueMode, HashMap<String, String> params)
Speaks the string using the specified queuing strategy and speech parameters.
int stop()
Interrupts the current utterance (whether played or rendered to file) and discards other utterances in the queue.
int synthesizeToFile(String text, HashMap<String, String> params, String filename)
Synthesizes the given text to a file using the specified parameters.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_TTS_QUEUE_PROCESSING_COMPLETED

Since: API Level 4

Broadcast Action: The TextToSpeech synthesizer has completed processing of all the text in the speech queue.

Constant Value: "android.speech.tts.TTS_QUEUE_PROCESSING_COMPLETED"

public static final int ERROR

Since: API Level 4

Denotes a generic operation failure.

Constant Value: -1 (0xffffffff)

public static final int LANG_AVAILABLE

Since: API Level 4

Denotes the language is available for the language by the locale, but not the country and variant.

Constant Value: 0 (0x00000000)

public static final int LANG_COUNTRY_AVAILABLE

Since: API Level 4

Denotes the language is available for the language and country specified by the locale, but not the variant.

Constant Value: 1 (0x00000001)

public static final int LANG_COUNTRY_VAR_AVAILABLE

Since: API Level 4

Denotes the language is available exactly as specified by the locale.

Constant Value: 2 (0x00000002)

public static final int LANG_MISSING_DATA

Since: API Level 4

Denotes the language data is missing.

Constant Value: -1 (0xffffffff)

public static final int LANG_NOT_SUPPORTED

Since: API Level 4

Denotes the language is not supported.

Constant Value: -2 (0xfffffffe)

public static final int QUEUE_ADD

Since: API Level 4

Queue mode where the new entry is added at the end of the playback queue.

Constant Value: 1 (0x00000001)

public static final int QUEUE_FLUSH

Since: API Level 4

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.

Constant Value: 0 (0x00000000)

public static final int SUCCESS

Since: API Level 4

Denotes a successful operation.

Constant Value: 0 (0x00000000)

Public Constructors

public TextToSpeech (Context context, TextToSpeech.OnInitListener listener)

Since: API Level 4

The constructor for the TextToSpeech class. This will also initialize the associated TextToSpeech engine if it isn't already running.

Parameters
context The context this instance is running in.
listener The TextToSpeech.OnInitListener that will be called when the TextToSpeech engine has initialized.

Public Methods

public int addEarcon (String earcon, String filename)

Since: API Level 4

Adds a mapping between a string of text and a sound file. Use this to add custom earcons.

Parameters
earcon The name of the earcon. Example: "[tick]"
filename The full path to the sound file (for example: "/sdcard/mysounds/tick.wav")
Returns
See Also

public int addEarcon (String earcon, String packagename, int resourceId)

Since: API Level 4

Adds a mapping between a string of text and a sound resource in a package. Use this to add custom earcons.

Parameters
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.

<manifest xmlns:android="..." package="com.google.marvin.compass">

resourceId Example: R.raw.tick_snd
Returns
See Also

public int addSpeech (String text, String packagename, int resourceId)

Since: API Level 4

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.

Parameters
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.

<manifest xmlns:android="..." package="com.google.marvin.compass">

resourceId Example: R.raw.south_south_east
Returns

public int addSpeech (String text, String filename)

Since: API Level 4

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.

Parameters
text The string of text. Example: "south_south_east"
filename The full path to the sound file (for example: "/sdcard/mysounds/hello.wav")
Returns

public boolean areDefaultsEnforced ()

Since: API Level 8

Returns whether or not the user is forcing their defaults to override the Text-To-Speech settings set by applications.

Returns
  • Whether or not defaults are enforced.

public String getDefaultEngine ()

Since: API Level 8

Gets the packagename of the default speech synthesis engine.

Returns
  • Packagename of the TTS engine that the user has chosen as their default.

public Locale getLanguage ()

Since: API Level 4

Returns a Locale instance describing the language currently being used by the TextToSpeech engine.

Returns
  • language, country (if any) and variant (if any) used by the engine stored in a Locale instance, or null is the TextToSpeech engine has failed.

public int isLanguageAvailable (Locale loc)

Since: API Level 4

Checks if the specified language as represented by the Locale is available and supported.

Parameters
loc The Locale describing the language to be used.
Returns

public boolean isSpeaking ()

Since: API Level 4

Returns whether or not the TextToSpeech engine is busy speaking.

Returns
  • Whether or not the TextToSpeech engine is busy speaking.

public int playEarcon (String earcon, int queueMode, HashMap<String, String> params)

Since: API Level 4

Plays the earcon using the specified queueing mode and parameters.

Parameters
earcon The earcon that should be played
queueMode QUEUE_ADD or QUEUE_FLUSH.
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 KEY_PARAM_STREAM or KEY_PARAM_UTTERANCE_ID.
Returns

public int playSilence (long durationInMs, int queueMode, HashMap<String, String> params)

Since: API Level 4

Plays silence for the specified amount of time using the specified queue mode.

Parameters
durationInMs A long that indicates how long the silence should last.
queueMode QUEUE_ADD or QUEUE_FLUSH.
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 KEY_PARAM_UTTERANCE_ID.
Returns

public int setEngineByPackageName (String enginePackageName)

Since: API Level 8

Sets the speech synthesis engine to be used by its packagename.

Parameters
enginePackageName The packagename for the synthesis engine (ie, "com.svox.pico")
Returns

public int setLanguage (Locale loc)

Since: API Level 4

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 isLanguageAvailable(Locale) to check the level of support before choosing the language to use for the next utterances.

Parameters
loc The locale describing the language to be used.
Returns

public int setOnUtteranceCompletedListener (TextToSpeech.OnUtteranceCompletedListener listener)

Since: API Level 4

Sets the OnUtteranceCompletedListener that will fire when an utterance completes.

Parameters
listener The OnUtteranceCompletedListener
Returns

public int setPitch (float pitch)

Since: API Level 4

Sets the speech pitch for the TextToSpeech engine. This has no effect on any pre-recorded speech.

Parameters
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.
Returns

public int setSpeechRate (float speechRate)

Since: API Level 4

Sets the speech rate for the TextToSpeech engine. This has no effect on any pre-recorded speech.

Parameters
speechRate 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).
Returns

public void shutdown ()

Since: API Level 4

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 int speak (String text, int queueMode, HashMap<String, String> params)

Since: API Level 4

Speaks the string using the specified queuing strategy and speech parameters.

Parameters
text The string of text to be spoken.
queueMode The queuing strategy to use. QUEUE_ADD or QUEUE_FLUSH.
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 KEY_PARAM_STREAM or KEY_PARAM_UTTERANCE_ID.
Returns

public int stop ()

Since: API Level 4

Interrupts the current utterance (whether played or rendered to file) and discards other utterances in the queue.

Returns

public int synthesizeToFile (String text, HashMap<String, String> params, String filename)

Since: API Level 4

Synthesizes the given text to a file using the specified parameters.

Parameters
text The String of text that should be synthesized
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 KEY_PARAM_UTTERANCE_ID.
filename The string that gives the full output filename; it should be something like "/sdcard/myappsounds/mysound.wav".
Returns