Speak to Me

A very useful feature of the Android API (available in Android 1.6 and later) is a rich and easy to use set of text to speech (TTS) resources that allow conversion of text strings to spoken voice. These capabilites are implemented primarily through the TextToSpeech class and are discussed in the Using Text-To-Speech Android document. By employing methods and class constants of the Locale class, it is generally possible to customize both the language and dialect of the spoken voice (subject to availability of language data on the device). Since the device can be self-aware of position if it has access to Location services, it is even possible to automatically switch the default language to correspond to the present location of the device. In this project we give a concise introduction to the basics of text to speech conversion.

Creating the Project

Open Eclipse and create a project with the following specifications

• Project name: SpeakToMe


• Build Target: Android 2.1


• Application name: Speak To Me


• Package name: com.lightcone.speaktome


• Create Activity: SpeakToMe


• Min SDK Version: 4

where we note that the minimum SDK version has been set to 4 (corresponding to Android 1.6). Now we modify this skeleton project to accomplish the following.

1. Query the device to see whether it has adequate language data installed. If it doesn't, send the device to try to get the required data. If it does have the language data, launch a new instance of TextToSpeech.


2. Put an editable text field on the screen to accept input text strings, a Speak button to initiate text to speech conversion on the input string, and a Clear button to clear the field, but disable input until the text to speech (TTS) instance is initialized.


3. Once the TextToSpeech instance is initialized, enable the input text fields and buttons, set language and properties of the TTS instance, and speak introductory instructions.


4. Use the methods of the TextToSpeech class to speak input text strings entered by the user when the Speak button is pressed.

Strings and Layout

We begin by defining the main layout and some strings that we will need. Open res/values/strings.xml and edit it to read

    <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <string name="hello">SpeakToMe</string>
        <string name="app_name">Speak To Me</string>
        <string name="goLabel">Speak</string>
        <string name="clearLabel">Clear Text</string>
    </resources>

Then open res/layout/main.xml and implement the layout for an EditText field and two Buttons:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent" >

    <EditText
        android:id="@+id/speak_input"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"

        android:hint="(Enter text)"
        android:inputType="text" />
	 
    <LinearLayout 
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal">
        <Button 
            android:id="@+id/speak_button"
            android:layout_width="fill_parent"
            android:layout_height="wrap_content"
            android:layout_weight="1.0"
            android:text="@string/goLabel" />
        <Button 
            android:id="@+id/clear_button"
            android:layout_width="fill_parent"
            android:layout_height="wrap_content"
            android:layout_weight="1.0"
            android:text="@string/clearLabel" />
    </LinearLayout>
	 
</LinearLayout>

Now we implement the Java code that will allow text entered in the text field to be converted to speech when the Speak button is pressed.

Implementing Text to Speech

Open the file SpeakToMe.java and edit it to read

package com.lightcone.speaktome;

import java.util.Locale;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.speech.tts.TextToSpeech;
import android.speech.tts.TextToSpeech.OnInitListener;
import android.util.Log;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.EditText;

// Class to test text-to-speech capabilities

public class SpeakToMe extends Activity implements OnInitListener, OnClickListener {
	
    private static final int CHECK_DATA = 0;
    private static final Locale defaultLocale = Locale.UK;   // Set language to British English
    private static final String logLabel = "TTS ++++++++++++++++++++";
    private TextToSpeech tts;
    private boolean isInit = false;
    private View speakButton;
    private View clearButton;
    private EditText speakText;
    
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        
        // Identify buttons and add click listeners
        speakButton = findViewById(R.id.speak_button);
        speakButton.setOnClickListener(this);
        clearButton = findViewById(R.id.clear_button);
        clearButton.setOnClickListener(this);
        
        // Identify EditText field
        speakText = (EditText) findViewById(R.id.speak_input);
        
        // Disable text field and speak button until text to speech initialization is done
        // (See method onInit() below)
        
        speakButton.setEnabled(false);
        speakText.setEnabled(false);
        
        // Use an Intent and startActivityForResult to check whether TTS data installed on the
        // device. Result returned and acted on in method onActivityResult(int, int, Intent) below.
        
        Intent checkIntent = new Intent();
        checkIntent.setAction(TextToSpeech.Engine.ACTION_CHECK_TTS_DATA);
        startActivityForResult(checkIntent, CHECK_DATA);
    }
    

    // Create the TTS instance if TextToSpeech language data are installed on device.  If not
    // installed, attempt to install it on the device.
    
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == CHECK_DATA) {
            if (resultCode == TextToSpeech.Engine.CHECK_VOICE_DATA_PASS) {
            	
                // Success, so create the TTS instance.  But can't use it to speak until
            	// the onInit(status) callback defined below runs, indicating initialization.
            	
            	Log.i(logLabel, "Success, let's talk");
                tts = new TextToSpeech(this,  this);
                
                // Use static Locales method to list available locales on device
    	        Locale locales [] = Locale.getAvailableLocales();
    	        Log.i(logLabel,"Locales Available on Device:");
    	        for(int i=0; i<locales.length; i++){
                    String temp = "Locale "+i+": "+locales[i]+" Language="
                        +locales[i].getDisplayLanguage();
                    if(locales[i].getDisplayCountry() != "") {
                        temp += " Country="+locales[i].getDisplayCountry();
                    }
                    Log.i(logLabel, temp);
    	        }
    	        
            } else {
                // missing data, so install it on the device
            	Log.i(logLabel, "Missing Data; Install it");
                Intent installIntent = new Intent();
                installIntent.setAction(TextToSpeech.Engine.ACTION_INSTALL_TTS_DATA);
                startActivity(installIntent);
            }
        }
    }
    
    // Must wait for initialization before any speech can be synthesized.  The class
    // implements OnInitListener and the following callback has been overridden to
    // implement actions that will be executed once initialized.
    
    @Override
    public void onInit(int status) {
        if(status == TextToSpeech.SUCCESS){
            isInit = true;

            // Enable input text field and speak button now that we are initialized
            speakButton.setEnabled(true);
            speakText.setEnabled(true);
            
            // Set to a language locale after checking availability
            Log.i(logLabel, "available="+tts.isLanguageAvailable(Locale.UK));
            tts.setLanguage(defaultLocale);
            // Examples of voice controls.  Set to defaults of 1.0.
            tts.setPitch(1.0F);
            tts.setSpeechRate(1.0F);
            // Issue a greeting and instructions in the default language
            speakGreeting(defaultLocale.getDisplayLanguage());
        } else {
            isInit = false;
            Log.i(logLabel, "Failure: TextToSpeech instance tts was not properly initialized");
        }
    }
    
    // Method to issue greeting and instructions
    
    public void speakGreeting(String currentLanguage){
        String text1 = "Let's test text to speech in "+currentLanguage+". ";
        text1 += "Enter some "+currentLanguage+" text and press the speak button.";
        sayIt(text1, true);
    }
    
    // Implement text to speech for an arbitrary string entered in the EditText field
    // for the Speak button and text clear for the Clear button.
	
    @Override
    public void onClick(View v) {
    	switch(v.getId()){
            case R.id.speak_button:
                String speakString = speakText.getText().toString();
                sayIt(speakString,true);
                break;
            case R.id.clear_button:
                speakText.setText("");
                break;
    	}
    }
	
    // Method to speak a string.  The boolean flushQ determines whether the text is
    // appended to the queue (if false), or if the queue is flushed first (if true).
    
    public void sayIt(String text, boolean flushQ){
        if(isInit){
            if(flushQ){
                tts.speak(text, TextToSpeech.QUEUE_FLUSH, null);
            } else {
                tts.speak(text, TextToSpeech.QUEUE_ADD, null);
            }
        } else {
            Log.i(logLabel, "Failure: TextToSpeech instance tts was not properly initialized");
        }
    }
	
    // Release TTS resources when finished
    @Override
    protected void onDestroy(){
    	super.onDestroy();
    	Log.i(logLabel,"Destroy");
    	tts.shutdown();
    }
}

If you now execute in a emulator or on a phone with TTS capability, you should see the following display

and the TTS syntesizer should speak brief instructions. If you enter some text and click Speak, the synthesizer should voice the text that you have entered.

How It Works

Let's summarize how SpeakToMe.java implements this functionality.

• The class implements the OnClickListener interface to listen to button clicks as in a number of previous examples. It also implements the OnInitListener interface because we cannot use TextToSpeech objects until they have been initialized and execution of the method onInit(int status) of OnInitListener signals that the TTS engine has completed initialization.


• We use setContentView to set the display to the layout specified by main.xml, findViewById to identify and name the screen widgets, and setOnClickListener to attach event handlers to the buttons (with the button events handled in the method onClick(View v), all in a manner that should be familiar from earlier examples.


• We then disable the textfield and the Speak button in onCreate because we must wait for the TTS object to be initialized before we try to use it. We will re-enable them in the method onInit(int status) that will be executed by Android as soon as the TTS object has initialized.


• The TTS engine must know which language to speak, which requires that language-specific resources be loaded before it can start work. All Android devices that support TTS ship with this engine, but some devices have limited storage and may not have language-specific resource files installed by default. Thus, we first check whether the device has the required data installed, and if not use the TTS API to offer the option of installing the missing data.


1. We first instantiate in onCreate() the Intent checkIntent. (Recall that an Intent is an abstract description of an operation to be performed.) In this case we use the setAction(String action) method that checkIntent inherits from Intent to specify the operation

   
       checkIntent.setAction(TextToSpeech.Engine.ACTION_CHECK_TTS_DATA);
   

   where ACTION_CHECK_TTS_DATA is a constant of the TextToSpeech.Engine class that starts an activity to verify proper installation and availability of language resource files on the system. We then use the Intent in the

   
       startActivityForResult(checkIntent, CHECK_DATA);
   

   statement, where the startActivityForResult(Intent intent, int requestCode) method of Activity is like the startActivity (Intent) method except that it returns a result: when the activity that was started exits, our onActivityResult() method (discussed below) will be called with the requestCode specified above as one argument and a resultCode as another argument.


2. We have overridden the Activity method onActivityResult(), which will be called when the activity that we launched exits, giving us the requestCode we started it with, the resultCode it returned, and any additional data from it. We first ensure that the requestCode returned is equal to the one passed to checkIntent and then check for the value of the resultCode.
   
   
   • A resultCode equal to the constant CHECK_VOICE_DATA_PASS of the class TextToSpeech.Engine implies that the device has the language data files installed. In that case we instantiate the TextToSpeech object tts (and will use the onInit(status) method to tell us when it has finished initializing). For information purposes we also use methods of the Locale class to query the device and send a list of its available countries and languages to the logcat output stream.
     
     

     The language options may be device dependent, and may depend on where the device is deployed. They may also be overridden by current phone settings. For example, the present example speaks with a British voice (as requested) when run on an Android 2.1 emulator, but when run on an AT&T Captivate (Samsung Galaxy S) phone in the United States it defaults to U.S. English, even though the checks output to logcat indicate that Locale.UK is installed. This is because for the Captivate the option Settings > Text-to-speech > Always use my settings is checked by default. This causes the Captivate to override app Locale commands and always use the language specified in Settings > Text-to-speech > Language. If this option is unchecked, the Captivate will then respond to app commands to reset the Locale and the current app will begin speaking in a British voice. In this example the listing of available Locales has about 80 entries for the emulator versus only a little more than half of that for the Captivate phone. Also, if you run on a device, you may be presented with a choice for TTS engines when you run the app. For the specific Captivate mentioned above, one can choose either Pico TTS or TTS Service Extended, for example.

     
     
   
   
   • A resultCode not equal to the constant CHECK_VOICE_DATA_PASS implies that the device does not have the language data files installed. In that case we use

     
         Intent installIntent = new Intent();
         installIntent.setAction(TextToSpeech.Engine.ACTION_INSTALL_TTS_DATA);
         startActivity(installIntent);
     

     to create an Intent called installIntent, set its action to install TTS data through the TextToSpeech.Engine class constant ACTION_INSTALL_TTS_DATA, and launch a new Activity using startActivity(installIntent) with this Intent as argument. This should trigger the platform TextToSpeech engine to start the activity that installs the resource files on the device that are required for TTS to be operational.
   
   

Because the user could interrupt this process at any point, we should not generally assume that this step will always be carried out. We won't worry about that here, but in a realistic application one should use the constant CHECK_VOICE_DATA_PASS as above to confirm that the data have been installed on the device before proceeding.



• Assuming success with the language data and instantiation of the TextToSpeech object tts in the preceding step, we must wait for tts to initialize before proceeding. This is easy, because we have implemented the OnInitListener interface, which will fire its onInit(int status) method when the initialization is complete. Thus we override the onInit(int status) method and add to it statements that we want to execute only after the tts object is initialized. Basically if we confirm success for the initialization we set the boolean isInit to true, enable the input textfield and Speak button, set a language locale for the TTS engine (in this example, British English is specified by the constant UK of the Locale class), illustrate setting a few parameters controlling the voice, and use the method sayIt(String text, boolean flushQ) defined below to have the TTS synthesizer speak some instructional phrases.


• Now that we are initialized, any text entered by the user in the input text field will be converted to speech when the Speak button is pressed, through the sayIt(String text, boolean flushQ) method, which uses the TextToSpeech method speak (String text, int queueMode, HashMap params). The first argument of speak is the string to be spoken, the second is an integer controlling whether the queue is flushed first, or whether the string is added to the current queue. The last argument permits a hashmap of parameters to be passed; we are not using that functionality so it has been set to null.


• Finally, we follow the recommendation of the Using Text-To-Speech Android document and override onDestroy() to implement the shutdown() method and release the resources being used by the TTS engine when we are done.

This simple exercise illustrates many of the basic features of TextToSpeech and should serve as a starting template for more ambitious applications. Two possibilities are suggested below in the Exercises. A project implementing a Spinner permitting the user to choose a language (Exercise 1) may be found at this Exercise solution.