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