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
26namespace 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
34enum tts_synth_status {
35    TTS_SYNTH_DONE              = 0,
36    TTS_SYNTH_PENDING           = 1
37};
38
39enum 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.
46enum 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.
70typedef tts_callback_status (synthDoneCB_t)(void *&, uint32_t,
71        tts_audio_format, int, int8_t *&, size_t&, tts_synth_status);
72
73class TtsEngine;
74extern "C" TtsEngine* getTtsEngine();
75
76enum 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
86enum 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
95class TtsEngine
96{
97public:
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