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.

Summary

Nested Classes
class TextToSpeech.Engine Internal constants for the TTS functionality  
interface TextToSpeech.OnInitListener Called when the TTS has initialized. 
interface TextToSpeech.OnUtteranceCompletedListener Called when the TTS has completed saying something that has 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 by the current TTS engine.
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 TTS.
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 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.
Locale getLanguage()
Returns a Locale instance describing the language currently being used by the TTS engine.
int isLanguageAvailable(Locale loc)
Checks if the specified language as represented by the Locale is available.
boolean isSpeaking()
Returns whether or not the TTS 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 setLanguage(Locale loc)
Sets the language for the TTS 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 TTS engine.
int setSpeechRate(float speechRate)
Sets the speech rate for the TTS engine.
void shutdown()
Shuts down the TTS.
int speak(String text, int queueMode, HashMap<String, String> params)
Speaks the string using the specified queuing strategy and speech parameters.
int stop()
Stops speech from the TTS.
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 by the current TTS engine.

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

Parameters
context The context
listener The InitListener that will be called when the TTS has initialized successfully.

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. Using this, it is possible to add custom earcons.

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

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.

Parameters
earcon The name of the earcon Example: "[tick]"
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.tick_snd
Returns
See Also

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

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

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.

Parameters
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
See Also

public Locale getLanguage ()

Since: API Level 4

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

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

public int isLanguageAvailable (Locale loc)

Since: API Level 4

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

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

public boolean isSpeaking ()

Since: API Level 4

Returns whether or not the TTS is busy speaking.

Returns
  • Whether or not the TTS 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 See QUEUE_ADD and QUEUE_FLUSH.
params The hashmap of parameters to be used.
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 See QUEUE_ADD and QUEUE_FLUSH.
Returns

public int setLanguage (Locale loc)

Since: API Level 4

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.

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

Parameters
pitch The pitch for the TTS 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 TTS 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.

Parameters
speechRate The speech rate for the TTS 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

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.

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. 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
text The string of text to be spoken.
queueMode The queuing strategy to use. See QUEUE_ADD and QUEUE_FLUSH.
params The hashmap of speech parameters to be used.
Returns

public int stop ()

Since: API Level 4

Stops speech from the TTS.

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 A hashmap of parameters.
filename The string that gives the full output filename; it should be something like "/sdcard/myappsounds/mysound.wav".
Returns