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 #ifndef ANDROID_TTS_H 17 #define ANDROID_TTS_H 18 19 // This header defines the interface used by the Android platform 20 // to access Text-To-Speech functionality in shared libraries that implement 21 // speech synthesis and the management of resources associated with the 22 // synthesis. 23 24 // The shared library must contain a function named "android_getTtsEngine" 25 // that returns an 'android_tts_engine_t' instance. 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 #define ANDROID_TTS_ENGINE_PROPERTY_CONFIG "engineConfig" 32 #define ANDROID_TTS_ENGINE_PROPERTY_PITCH "pitch" 33 #define ANDROID_TTS_ENGINE_PROPERTY_RATE "rate" 34 #define ANDROID_TTS_ENGINE_PROPERTY_VOLUME "volume" 35 36 typedef enum { 37 ANDROID_TTS_SUCCESS = 0, 38 ANDROID_TTS_FAILURE = -1, 39 ANDROID_TTS_FEATURE_UNSUPPORTED = -2, 40 ANDROID_TTS_VALUE_INVALID = -3, 41 ANDROID_TTS_PROPERTY_UNSUPPORTED = -4, 42 ANDROID_TTS_PROPERTY_SIZE_TOO_SMALL = -5, 43 ANDROID_TTS_MISSING_RESOURCES = -6 44 } android_tts_result_t; 45 46 typedef enum { 47 ANDROID_TTS_LANG_COUNTRY_VAR_AVAILABLE = 2, 48 ANDROID_TTS_LANG_COUNTRY_AVAILABLE = 1, 49 ANDROID_TTS_LANG_AVAILABLE = 0, 50 ANDROID_TTS_LANG_MISSING_DATA = -1, 51 ANDROID_TTS_LANG_NOT_SUPPORTED = -2 52 } android_tts_support_result_t; 53 54 typedef enum { 55 ANDROID_TTS_SYNTH_DONE = 0, 56 ANDROID_TTS_SYNTH_PENDING = 1 57 } android_tts_synth_status_t; 58 59 typedef enum { 60 ANDROID_TTS_CALLBACK_HALT = 0, 61 ANDROID_TTS_CALLBACK_CONTINUE = 1 62 } android_tts_callback_status_t; 63 64 // Supported audio formats 65 // 66 // NOTE: This is duplicated in compat/include/TtsEngine.h 67 // Please make changes there as well. 68 typedef enum { 69 ANDROID_TTS_AUDIO_FORMAT_INVALID = -1, 70 ANDROID_TTS_AUDIO_FORMAT_DEFAULT = 0, 71 ANDROID_TTS_AUDIO_FORMAT_PCM_16_BIT = 1, 72 ANDROID_TTS_AUDIO_FORMAT_PCM_8_BIT = 2, 73 } android_tts_audio_format_t; 74 75 76 /* An android_tts_engine_t object can be anything, but must have, 77 * as its first field, a pointer to a table of functions. 78 * 79 * See the full definition of struct android_tts_engine_t_funcs_t 80 * below for details. 81 */ 82 typedef struct android_tts_engine_funcs_t android_tts_engine_funcs_t; 83 84 typedef struct { 85 android_tts_engine_funcs_t *funcs; 86 } android_tts_engine_t; 87 88 /* This function must be located in the TTS Engine shared library 89 * and must return the address of an android_tts_engine_t library. 90 */ 91 extern android_tts_engine_t *android_getTtsEngine(); 92 93 /* Including the old version for legacy support (Froyo compatibility). 94 * This should return the same thing as android_getTtsEngine. 95 */ 96 extern "C" android_tts_engine_t *getTtsEngine(); 97 98 // A callback type used to notify the framework of new synthetized 99 // audio samples, status will be SYNTH_DONE for the last sample of 100 // the last request, of SYNTH_PENDING otherwise. 101 // 102 // This is passed by the framework to the engine through the 103 // 'engine_init' function (see below). 104 // 105 // The callback for synthesis completed takes: 106 // @param [inout] void *& - The userdata pointer set in the original 107 // synth call 108 // @param [in] uint32_t - Track sampling rate in Hz 109 // @param [in] uint32_t - The audio format 110 // @param [in] int - The number of channels 111 // @param [inout] int8_t *& - A buffer of audio data only valid during the 112 // execution of the callback 113 // @param [inout] size_t & - The size of the buffer 114 // @param [in] tts_synth_status - indicate whether the synthesis is done, or 115 // if more data is to be synthesized. 116 // @return TTS_CALLBACK_HALT to indicate the synthesis must stop, 117 // TTS_CALLBACK_CONTINUE to indicate the synthesis must continue if 118 // there is more data to produce. 119 typedef android_tts_callback_status_t (*android_tts_synth_cb_t) 120 (void **pUserData, 121 uint32_t trackSamplingHz, 122 android_tts_audio_format_t audioFormat, 123 int channelCount, 124 int8_t **pAudioBuffer, 125 size_t *pBufferSize, 126 android_tts_synth_status_t status); 127 128 129 // The table of function pointers that the android_tts_engine_t must point to. 130 // Note that each of these functions will take a handle to the engine itself 131 // as their first parameter. 132 // 133 134 struct android_tts_engine_funcs_t { 135 // reserved fields, ignored by the framework 136 // they must be placed here to ensure binary compatibility 137 // of legacy binary plugins. 138 void *reserved[2]; 139 140 // Initialize the TTS engine and returns whether initialization succeeded. 141 // @param synthDoneCBPtr synthesis callback function pointer 142 // @return TTS_SUCCESS, or TTS_FAILURE 143 android_tts_result_t (*init) 144 (void *engine, 145 android_tts_synth_cb_t synthDonePtr, 146 const char *engineConfig); 147 148 // Shut down the TTS engine and releases all associated resources. 149 // @return TTS_SUCCESS, or TTS_FAILURE 150 android_tts_result_t (*shutdown) 151 (void *engine); 152 153 // Interrupt synthesis and flushes any synthesized data that hasn't been 154 // output yet. This will block until callbacks underway are completed. 155 // @return TTS_SUCCESS, or TTS_FAILURE 156 android_tts_result_t (*stop) 157 (void *engine); 158 159 // Returns the level of support for the language, country and variant. 160 // @return TTS_LANG_COUNTRY_VAR_AVAILABLE if the language, country and variant are supported, 161 // and the corresponding resources are correctly installed 162 // TTS_LANG_COUNTRY_AVAILABLE if the language and country are supported and the 163 // corresponding resources are correctly installed, but there is no match for 164 // the specified variant 165 // TTS_LANG_AVAILABLE if the language is supported and the 166 // corresponding resources are correctly installed, but there is no match for 167 // the specified country and variant 168 // TTS_LANG_MISSING_DATA if the required resources to provide any level of support 169 // for the language are not correctly installed 170 // TTS_LANG_NOT_SUPPORTED if the language is not supported by the TTS engine. 171 android_tts_support_result_t (*isLanguageAvailable) 172 (void *engine, 173 const char *lang, 174 const char *country, 175 const char *variant); 176 177 // Load the resources associated with the specified language. The loaded 178 // language will only be used once a call to setLanguage() with the same 179 // language value is issued. Language and country values are coded according to the ISO three 180 // letter codes for languages and countries, as can be retrieved from a java.util.Locale 181 // instance. The variant value is encoded as the variant string retrieved from a 182 // java.util.Locale instance built with that variant data. 183 // @param lang pointer to the ISO three letter code for the language 184 // @param country pointer to the ISO three letter code for the country 185 // @param variant pointer to the variant code 186 // @return TTS_SUCCESS, or TTS_FAILURE 187 android_tts_result_t (*loadLanguage) 188 (void *engine, 189 const char *lang, 190 const char *country, 191 const char *variant); 192 193 // Load the resources associated with the specified language, country and Locale variant. 194 // The loaded language will only be used once a call to setLanguageFromLocale() with the same 195 // language value is issued. Language and country values are coded according to the ISO three 196 // letter codes for languages and countries, as can be retrieved from a java.util.Locale 197 // instance. The variant value is encoded as the variant string retrieved from a 198 // java.util.Locale instance built with that variant data. 199 // @param lang pointer to the ISO three letter code for the language 200 // @param country pointer to the ISO three letter code for the country 201 // @param variant pointer to the variant code 202 // @return TTS_SUCCESS, or TTS_FAILURE 203 android_tts_result_t (*setLanguage) 204 (void *engine, 205 const char *lang, 206 const char *country, 207 const char *variant); 208 209 // Retrieve the currently set language, country and variant, or empty strings if none of 210 // parameters have been set. Language and country are represented by their 3-letter ISO code 211 // @param[out] pointer to the retrieved 3-letter code language value 212 // @param[out] pointer to the retrieved 3-letter code country value 213 // @param[out] pointer to the retrieved variant value 214 // @return TTS_SUCCESS, or TTS_FAILURE 215 android_tts_result_t (*getLanguage) 216 (void *engine, 217 char *language, 218 char *country, 219 char *variant); 220 221 // Notifies the engine what audio parameters should be used for the synthesis. 222 // This is meant to be used as a hint, the engine implementation will set the output values 223 // to those of the synthesis format, based on a given hint. 224 // @param[inout] encoding in: the desired audio sample format 225 // out: the format used by the TTS engine 226 // @param[inout] rate in: the desired audio sample rate 227 // out: the sample rate used by the TTS engine 228 // @param[inout] channels in: the desired number of audio channels 229 // out: the number of channels used by the TTS engine 230 // @return TTS_SUCCESS, or TTS_FAILURE 231 android_tts_result_t (*setAudioFormat) 232 (void *engine, 233 android_tts_audio_format_t* pEncoding, 234 uint32_t* pRate, 235 int* pChannels); 236 237 // Set a property for the the TTS engine 238 // "size" is the maximum size of "value" for properties "property" 239 // @param property pointer to the property name 240 // @param value pointer to the property value 241 // @param size maximum size required to store this type of property 242 // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE, 243 // or TTS_VALUE_INVALID 244 android_tts_result_t (*setProperty) 245 (void *engine, 246 const char *property, 247 const char *value, 248 const size_t size); 249 250 // Retrieve a property from the TTS engine 251 // @param property pointer to the property name 252 // @param[out] value pointer to the retrieved language value 253 // @param[inout] iosize in: stores the size available to store the 254 // property value. 255 // out: stores the size required to hold the language 256 // value if getLanguage() returned 257 // TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise 258 // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, 259 // or TTS_PROPERTY_SIZE_TOO_SMALL 260 android_tts_result_t (*getProperty) 261 (void *engine, 262 const char *property, 263 char *value, 264 size_t *iosize); 265 266 // Synthesize the text. 267 // As the synthesis is performed, the engine invokes the callback to notify 268 // the TTS framework that it has filled the given buffer, and indicates how 269 // many bytes it wrote. The callback is called repeatedly until the engine 270 // has generated all the audio data corresponding to the text. 271 // Note about the format of the input: the text parameter may use the 272 // following elements 273 // and their respective attributes as defined in the SSML 1.0 specification: 274 // * lang 275 // * say-as: 276 // o interpret-as 277 // * phoneme 278 // * voice: 279 // o gender, 280 // o age, 281 // o variant, 282 // o name 283 // * emphasis 284 // * break: 285 // o strength, 286 // o time 287 // * prosody: 288 // o pitch, 289 // o contour, 290 // o range, 291 // o rate, 292 // o duration, 293 // o volume 294 // * mark 295 // Differences between this text format and SSML are: 296 // * full SSML documents are not supported 297 // * namespaces are not supported 298 // Text is coded in UTF-8. 299 // @param text the UTF-8 text to synthesize 300 // @param userdata pointer to be returned when the call is invoked 301 // @param buffer the location where the synthesized data must be written 302 // @param bufferSize the number of bytes that can be written in buffer 303 // @return TTS_SUCCESS or TTS_FAILURE 304 android_tts_result_t (*synthesizeText) 305 (void *engine, 306 const char *text, 307 int8_t *buffer, 308 size_t bufferSize, 309 void *userdata); 310 }; 311 312 #ifdef __cplusplus 313 } 314 #endif 315 316 #endif /* ANDROID_TTS_H */ 317
