1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.speech.tts; 18 19 import android.net.Uri; 20 import android.os.Bundle; 21 import android.os.ParcelFileDescriptor; 22 import android.speech.tts.ITextToSpeechCallback; 23 import android.speech.tts.Voice; 24 25 /** 26 * Interface for TextToSpeech to talk to TextToSpeechService. 27 * 28 * {@hide} 29 */ 30 interface ITextToSpeechService { 31 32 /** 33 * Tells the engine to synthesize some speech and play it back. 34 * 35 * @param callingInstance a binder representing the identity of the calling 36 * TextToSpeech object. 37 * @param text The text to synthesize. 38 * @param queueMode Determines what to do to requests already in the queue. 39 * @param param Request parameters. 40 * @param utteranceId Unique identifier of synthesized utterance. 41 */ speak(in IBinder callingInstance, in CharSequence text, in int queueMode, in Bundle params, String utteranceId)42 int speak(in IBinder callingInstance, in CharSequence text, in int queueMode, in Bundle params, 43 String utteranceId); 44 45 /** 46 * Tells the engine to synthesize some speech and write it to a file. 47 * 48 * @param callingInstance a binder representing the identity of the calling 49 * TextToSpeech object. 50 * @param text The text to synthesize. 51 * @param fileDescriptor The file descriptor to write the synthesized audio to. Has to be 52 writable. 53 * @param utteranceId Unique identifier of synthesized utterance. 54 * @param param Request parameters. 55 */ synthesizeToFileDescriptor(in IBinder callingInstance, in CharSequence text, in ParcelFileDescriptor fileDescriptor, in Bundle params, String utteranceId)56 int synthesizeToFileDescriptor(in IBinder callingInstance, in CharSequence text, 57 in ParcelFileDescriptor fileDescriptor, in Bundle params, String utteranceId); 58 59 /** 60 * Plays an existing audio resource. 61 * 62 * @param callingInstance a binder representing the identity of the calling 63 * TextToSpeech object. 64 * @param audioUri URI for the audio resource (a file or android.resource URI) 65 * @param queueMode Determines what to do to requests already in the queue. 66 * @param utteranceId Unique identifier of synthesized utterance. 67 * @param param Request parameters. 68 */ playAudio(in IBinder callingInstance, in Uri audioUri, in int queueMode, in Bundle params, String utteranceId)69 int playAudio(in IBinder callingInstance, in Uri audioUri, in int queueMode, in Bundle params, 70 String utteranceId); 71 72 /** 73 * Plays silence. 74 * 75 * @param callingInstance a binder representing the identity of the calling 76 * TextToSpeech object. 77 * @param duration Number of milliseconds of silence to play. 78 * @param queueMode Determines what to do to requests already in the queue. 79 * @param utteranceId Unique id used to identify this request in callbacks. 80 */ playSilence(in IBinder callingInstance, in long duration, in int queueMode, in String utteranceId)81 int playSilence(in IBinder callingInstance, in long duration, in int queueMode, 82 in String utteranceId); 83 84 /** 85 * Checks whether the service is currently playing some audio. 86 */ isSpeaking()87 boolean isSpeaking(); 88 89 /** 90 * Interrupts the current utterance (if from the given app) and removes any utterances 91 * in the queue that are from the given app. 92 * 93 * @param callingInstance a binder representing the identity of the calling 94 * TextToSpeech object. 95 */ stop(in IBinder callingInstance)96 int stop(in IBinder callingInstance); 97 98 /** 99 * Returns the language, country and variant currently being used by the TTS engine. 100 * Can be called from multiple threads. 101 * 102 * @return A 3-element array, containing language (ISO 3-letter code), 103 * country (ISO 3-letter code) and variant used by the engine. 104 * The country and variant may be {@code ""}. If country is empty, then variant must 105 * be empty too. 106 */ getLanguage()107 String[] getLanguage(); 108 109 /** 110 * Returns a default TTS language, country and variant as set by the user. 111 * 112 * Can be called from multiple threads. 113 * 114 * @return A 3-element array, containing language (ISO 3-letter code), 115 * country (ISO 3-letter code) and variant used by the engine. 116 * The country and variant may be {@code ""}. If country is empty, then variant must 117 * be empty too. 118 */ getClientDefaultLanguage()119 String[] getClientDefaultLanguage(); 120 121 /** 122 * Checks whether the engine supports a given language. 123 * 124 * @param lang ISO-3 language code. 125 * @param country ISO-3 country code. May be empty or null. 126 * @param variant Language variant. May be empty or null. 127 * @return Code indicating the support status for the locale. 128 * One of {@link TextToSpeech#LANG_AVAILABLE}, 129 * {@link TextToSpeech#LANG_COUNTRY_AVAILABLE}, 130 * {@link TextToSpeech#LANG_COUNTRY_VAR_AVAILABLE}, 131 * {@link TextToSpeech#LANG_MISSING_DATA} 132 * {@link TextToSpeech#LANG_NOT_SUPPORTED}. 133 */ isLanguageAvailable(in String lang, in String country, in String variant)134 int isLanguageAvailable(in String lang, in String country, in String variant); 135 136 /** 137 * Returns a list of features available for a given language. Elements of the returned 138 * string array can be passed in as keys to {@link TextToSpeech#speak} and 139 * {@link TextToSpeech#synthesizeToFile} to select a given feature or features to be 140 * used during synthesis. 141 * 142 * @param lang ISO-3 language code. 143 * @param country ISO-3 country code. May be empty or null. 144 * @param variant Language variant. May be empty or null. 145 * @return An array of strings containing the set of features supported for 146 * the supplied locale. The array of strings must not contain 147 * duplicates. 148 */ getFeaturesForLanguage(in String lang, in String country, in String variant)149 String[] getFeaturesForLanguage(in String lang, in String country, in String variant); 150 151 /** 152 * Notifies the engine that it should load a speech synthesis language. 153 * 154 * @param caller a binder representing the identity of the calling 155 * TextToSpeech object. 156 * @param lang ISO-3 language code. 157 * @param country ISO-3 country code. May be empty or null. 158 * @param variant Language variant. May be empty or null. 159 * @return Code indicating the support status for the locale. 160 * One of {@link TextToSpeech#LANG_AVAILABLE}, 161 * {@link TextToSpeech#LANG_COUNTRY_AVAILABLE}, 162 * {@link TextToSpeech#LANG_COUNTRY_VAR_AVAILABLE}, 163 * {@link TextToSpeech#LANG_MISSING_DATA} 164 * {@link TextToSpeech#LANG_NOT_SUPPORTED}. 165 */ loadLanguage(in IBinder caller, in String lang, in String country, in String variant)166 int loadLanguage(in IBinder caller, in String lang, in String country, in String variant); 167 168 /** 169 * Sets the callback that will be notified when playback of utterance from the 170 * given app are completed. 171 * 172 * @param caller Instance a binder representing the identity of the calling 173 * TextToSpeech object. 174 * @param cb The callback. 175 */ setCallback(in IBinder caller, ITextToSpeechCallback cb)176 void setCallback(in IBinder caller, ITextToSpeechCallback cb); 177 178 /** 179 * Get the array of available voices. 180 */ getVoices()181 List<Voice> getVoices(); 182 183 /** 184 * Notifies the engine that it should load a speech synthesis voice. 185 * 186 * @param caller a binder representing the identity of the calling 187 * TextToSpeech object. 188 * @param voiceName Unique voice of the name. 189 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 190 */ loadVoice(in IBinder caller, in String voiceName)191 int loadVoice(in IBinder caller, in String voiceName); 192 193 /** 194 * Return a name of the default voice for a given locale. 195 * 196 * This allows {@link TextToSpeech#getVoice} to return a sensible value after a client calls 197 * {@link TextToSpeech#setLanguage}. 198 * 199 * @param lang ISO 3-character language code. 200 * @param country ISO 3-character country code. May be empty or null. 201 * @param variant Language variant. May be empty or null. 202 * @return Code indicating the support status for the locale. 203 * One of {@link TextToSpeech#LANG_AVAILABLE}, 204 * {@link TextToSpeech#LANG_COUNTRY_AVAILABLE}, 205 * {@link TextToSpeech#LANG_COUNTRY_VAR_AVAILABLE}, 206 * {@link TextToSpeech#LANG_MISSING_DATA} 207 * {@link TextToSpeech#LANG_NOT_SUPPORTED}. 208 */ getDefaultVoiceNameFor(in String lang, in String country, in String variant)209 String getDefaultVoiceNameFor(in String lang, in String country, in String variant); 210 } 211