1 /* 2 * Copyright (C) 2009 Google Inc. 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 // This header defines the interface used by the Android platform 18 // to access Text-To-Speech functionality in shared libraries that implement 19 // speech synthesis and the management of resources associated with the 20 // synthesis. 21 // An example of the implementation of this interface can be found in 22 // FIXME: add path+name to implementation of default TTS engine 23 // Libraries implementing this interface are used in: 24 // frameworks/base/tts/jni/android_tts_SpeechSynthesis.cpp 25 26 namespace android { 27 28 #define ANDROID_TTS_ENGINE_PROPERTY_CONFIG "engineConfig" 29 #define ANDROID_TTS_ENGINE_PROPERTY_PITCH "pitch" 30 #define ANDROID_TTS_ENGINE_PROPERTY_RATE "rate" 31 #define ANDROID_TTS_ENGINE_PROPERTY_VOLUME "volume" 32 33 34 enum tts_synth_status { 35 TTS_SYNTH_DONE = 0, 36 TTS_SYNTH_PENDING = 1 37 }; 38 39 enum tts_callback_status { 40 TTS_CALLBACK_HALT = 0, 41 TTS_CALLBACK_CONTINUE = 1 42 }; 43 44 // NOTE: This is duplicated in compat/jni/tts.h. Please 45 // make changes there as well. 46 enum tts_audio_format { 47 TTS_AUDIO_FORMAT_INVALID = -1, 48 TTS_AUDIO_FORMAT_DEFAULT = 0, 49 TTS_AUDIO_FORMAT_PCM_16_BIT = 1, 50 TTS_AUDIO_FORMAT_PCM_8_BIT = 2, 51 }; 52 53 // The callback is used by the implementation of this interface to notify its 54 // client, the Android TTS service, that the last requested synthesis has been 55 // completed. // TODO reword 56 // The callback for synthesis completed takes: 57 // @param [inout] void *& - The userdata pointer set in the original 58 // synth call 59 // @param [in] uint32_t - Track sampling rate in Hz 60 // @param [in] tts_audio_format - The audio format 61 // @param [in] int - The number of channels 62 // @param [inout] int8_t *& - A buffer of audio data only valid during the 63 // execution of the callback 64 // @param [inout] size_t & - The size of the buffer 65 // @param [in] tts_synth_status - indicate whether the synthesis is done, or 66 // if more data is to be synthesized. 67 // @return TTS_CALLBACK_HALT to indicate the synthesis must stop, 68 // TTS_CALLBACK_CONTINUE to indicate the synthesis must continue if 69 // there is more data to produce. 70 typedef tts_callback_status (synthDoneCB_t)(void *&, uint32_t, 71 tts_audio_format, int, int8_t *&, size_t&, tts_synth_status); 72 73 class TtsEngine; 74 extern "C" TtsEngine* getTtsEngine(); 75 76 enum tts_result { 77 TTS_SUCCESS = 0, 78 TTS_FAILURE = -1, 79 TTS_FEATURE_UNSUPPORTED = -2, 80 TTS_VALUE_INVALID = -3, 81 TTS_PROPERTY_UNSUPPORTED = -4, 82 TTS_PROPERTY_SIZE_TOO_SMALL = -5, 83 TTS_MISSING_RESOURCES = -6 84 }; 85 86 enum tts_support_result { 87 TTS_LANG_COUNTRY_VAR_AVAILABLE = 2, 88 TTS_LANG_COUNTRY_AVAILABLE = 1, 89 TTS_LANG_AVAILABLE = 0, 90 TTS_LANG_MISSING_DATA = -1, 91 TTS_LANG_NOT_SUPPORTED = -2 92 }; 93 94 95 class TtsEngine 96 { 97 public: ~TtsEngine()98 virtual ~TtsEngine() {} 99 100 // Initialize the TTS engine and returns whether initialization succeeded. 101 // @param synthDoneCBPtr synthesis callback function pointer 102 // @return TTS_SUCCESS, or TTS_FAILURE 103 virtual tts_result init(synthDoneCB_t synthDoneCBPtr, const char *engineConfig); 104 105 // Shut down the TTS engine and releases all associated resources. 106 // @return TTS_SUCCESS, or TTS_FAILURE 107 virtual tts_result shutdown(); 108 109 // Interrupt synthesis and flushes any synthesized data that hasn't been 110 // output yet. This will block until callbacks underway are completed. 111 // @return TTS_SUCCESS, or TTS_FAILURE 112 virtual tts_result stop(); 113 114 // Returns the level of support for the language, country and variant. 115 // @return TTS_LANG_COUNTRY_VAR_AVAILABLE if the language, country and variant are supported, 116 // and the corresponding resources are correctly installed 117 // TTS_LANG_COUNTRY_AVAILABLE if the language and country are supported and the 118 // corresponding resources are correctly installed, but there is no match for 119 // the specified variant 120 // TTS_LANG_AVAILABLE if the language is supported and the 121 // corresponding resources are correctly installed, but there is no match for 122 // the specified country and variant 123 // TTS_LANG_MISSING_DATA if the required resources to provide any level of support 124 // for the language are not correctly installed 125 // TTS_LANG_NOT_SUPPORTED if the language is not supported by the TTS engine. 126 virtual tts_support_result isLanguageAvailable(const char *lang, const char *country, 127 const char *variant); 128 129 // Load the resources associated with the specified language. The loaded 130 // language will only be used once a call to setLanguage() with the same 131 // language value is issued. Language and country values are coded according to the ISO three 132 // letter codes for languages and countries, as can be retrieved from a java.util.Locale 133 // instance. The variant value is encoded as the variant string retrieved from a 134 // java.util.Locale instance built with that variant data. 135 // @param lang pointer to the ISO three letter code for the language 136 // @param country pointer to the ISO three letter code for the country 137 // @param variant pointer to the variant code 138 // @return TTS_SUCCESS, or TTS_FAILURE 139 virtual tts_result loadLanguage(const char *lang, const char *country, const char *variant); 140 141 // Load the resources associated with the specified language, country and Locale variant. 142 // The loaded language will only be used once a call to setLanguageFromLocale() with the same 143 // language value is issued. Language and country values are coded according to the ISO three 144 // letter codes for languages and countries, as can be retrieved from a java.util.Locale 145 // instance. The variant value is encoded as the variant string retrieved from a 146 // java.util.Locale instance built with that variant data. 147 // @param lang pointer to the ISO three letter code for the language 148 // @param country pointer to the ISO three letter code for the country 149 // @param variant pointer to the variant code 150 // @return TTS_SUCCESS, or TTS_FAILURE 151 virtual tts_result setLanguage(const char *lang, const char *country, const char *variant); 152 153 // Retrieve the currently set language, country and variant, or empty strings if none of 154 // parameters have been set. Language and country are represented by their 3-letter ISO code 155 // @param[out] pointer to the retrieved 3-letter code language value 156 // @param[out] pointer to the retrieved 3-letter code country value 157 // @param[out] pointer to the retrieved variant value 158 // @return TTS_SUCCESS, or TTS_FAILURE 159 virtual tts_result getLanguage(char *language, char *country, char *variant); 160 161 // Notifies the engine what audio parameters should be used for the synthesis. 162 // This is meant to be used as a hint, the engine implementation will set the output values 163 // to those of the synthesis format, based on a given hint. 164 // @param[inout] encoding in: the desired audio sample format 165 // out: the format used by the TTS engine 166 // @param[inout] rate in: the desired audio sample rate 167 // out: the sample rate used by the TTS engine 168 // @param[inout] channels in: the desired number of audio channels 169 // out: the number of channels used by the TTS engine 170 // @return TTS_SUCCESS, or TTS_FAILURE 171 virtual tts_result setAudioFormat(tts_audio_format& encoding, uint32_t& rate, 172 int& channels); 173 174 // Set a property for the the TTS engine 175 // "size" is the maximum size of "value" for properties "property" 176 // @param property pointer to the property name 177 // @param value pointer to the property value 178 // @param size maximum size required to store this type of property 179 // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE, 180 // or TTS_VALUE_INVALID 181 virtual tts_result setProperty(const char *property, const char *value, 182 const size_t size); 183 184 // Retrieve a property from the TTS engine 185 // @param property pointer to the property name 186 // @param[out] value pointer to the retrieved language value 187 // @param[inout] iosize in: stores the size available to store the 188 // property value. 189 // out: stores the size required to hold the language 190 // value if getLanguage() returned 191 // TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise 192 // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, 193 // or TTS_PROPERTY_SIZE_TOO_SMALL 194 virtual tts_result getProperty(const char *property, char *value, 195 size_t *iosize); 196 197 // Synthesize the text. 198 // As the synthesis is performed, the engine invokes the callback to notify 199 // the TTS framework that it has filled the given buffer, and indicates how 200 // many bytes it wrote. The callback is called repeatedly until the engine 201 // has generated all the audio data corresponding to the text. 202 // Note about the format of the input: the text parameter may use the 203 // following elements 204 // and their respective attributes as defined in the SSML 1.0 specification: 205 // * lang 206 // * say-as: 207 // o interpret-as 208 // * phoneme 209 // * voice: 210 // o gender, 211 // o age, 212 // o variant, 213 // o name 214 // * emphasis 215 // * break: 216 // o strength, 217 // o time 218 // * prosody: 219 // o pitch, 220 // o contour, 221 // o range, 222 // o rate, 223 // o duration, 224 // o volume 225 // * mark 226 // Differences between this text format and SSML are: 227 // * full SSML documents are not supported 228 // * namespaces are not supported 229 // Text is coded in UTF-8. 230 // @param text the UTF-8 text to synthesize 231 // @param userdata pointer to be returned when the call is invoked 232 // @param buffer the location where the synthesized data must be written 233 // @param bufferSize the number of bytes that can be written in buffer 234 // @return TTS_SUCCESS or TTS_FAILURE 235 virtual tts_result synthesizeText(const char *text, int8_t *buffer, 236 size_t bufferSize, void *userdata); 237 238 }; 239 240 } // namespace android 241