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