/PlaceHolderTTSEngine/native/project/jni/tts/TtsEngine.h

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