PageRenderTime 21ms CodeModel.GetById 13ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/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
 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