2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 * http://www.apache.org/licenses/LICENSE-2.0
7 * Unless required by applicable law or agreed to in writing, software
8 * distributed under the License is distributed on an "AS IS" BASIS,
9 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10 * See the License for the specific language governing permissions and
11 * limitations under the License.
22 * @addtogroup TTS_ENGINE_MODULE
31 * @brief Enumerations of error codes.
34 TTSP_ERROR_NONE = 0, /**< Successful */
35 TTSP_ERROR_OUT_OF_MEMORY = -ENOMEM, /**< Out of Memory */
36 TTSP_ERROR_IO_ERROR = -EIO, /**< I/O error */
37 TTSP_ERROR_INVALID_PARAMETER = -EINVAL, /**< Invalid parameter */
38 TTSP_ERROR_OUT_OF_NETWORK = -ENETDOWN, /**< Out of network */
39 TTSP_ERROR_INVALID_STATE = -0x0100021, /**< Invalid state */
40 TTSP_ERROR_INVALID_VOICE = -0x0100022, /**< Invalid voice */
41 TTSP_ERROR_OPERATION_FAILED = -0x0100025 /**< Operation failed */
45 * @brief Enumerations of speaking speed.
48 TTSP_SPEED_VERY_SLOW = 1, /**< Very slow */
49 TTSP_SPEED_SLOW, /**< Slow */
50 TTSP_SPEED_NORMAL, /**< Normal */
51 TTSP_SPEED_FAST, /**< Fast */
52 TTSP_SPEED_VERY_FAST /**< Very fast */
56 * @brief Enumerations of voice type.
59 TTSP_VOICE_TYPE_MALE = 1, /**< Male */
60 TTSP_VOICE_TYPE_FEMALE, /**< Female */
61 TTSP_VOICE_TYPE_CHILD, /**< Child */
62 TTSP_VOICE_TYPE_USER1, /**< Engine defined */
63 TTSP_VOICE_TYPE_USER2, /**< Engine defined */
64 TTSP_VOICE_TYPE_USER3 /**< Engine defined */
68 * @brief Enumerations of audio type.
71 TTSP_AUDIO_TYPE_RAW = 0, /**< PCM audio type */
72 TTSP_AUDIO_TYPE_WAV, /**< Wave audio type */
73 TTSP_AUDIO_TYPE_MP3, /**< MP3 audio type */
74 TTSP_AUDIO_TYPE_AMR /**< AMR audio type */
78 * @brief Enumerations of result event type.
81 TTSP_RESULT_EVENT_FAIL = -1, /**< event when the voice synthesis is failed */
82 TTSP_RESULT_EVENT_START = 1, /**< event when the sound data is first data by callback function */
83 TTSP_RESULT_EVENT_CONTINUE = 2, /**< event when the next sound data exist, not first and not last */
84 TTSP_RESULT_EVENT_FINISH = 3, /**< event when the sound data is last data or sound data is only one result */
85 TTSP_RESULT_EVENT_CANCEL = 4, /**< event when the voice synthesis has been canceled */
89 * @brief Called when the daemon gets synthesized result.
91 * @param[in] event A result event
92 * @param[in] data Result data
93 * @param[in] data_size Result data size
94 * @param[in] user_data The user data passed from the start synthesis function
96 * @return @c true to continue with the next iteration of synthesis \n @c false to stop
98 * @pre ttspe_start_synthesis() will invoke this callback.
100 * @see ttspe_start_synthesis()
102 typedef bool (*ttspe_result_cb)(ttsp_result_event_e event, const void* data, unsigned int data_size, void *user_data);
105 * @brief Called when the daemon gets a language and a voice type.
107 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
108 * followed by ISO 639-1 for the two-letter language code. \n
109 * For example, "ko_KR" for Korean, "en_US" for American English.
110 * @param[in] type A voice type
111 * @param[in] user_data The user data passed from the the foreach function
113 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
115 * @pre ttspe_foreach_supported_voices() will invoke this callback.
117 * @see ttspe_foreach_supported_voices()
119 typedef bool (*ttspe_supported_voice_cb)(const char* language, ttsp_voice_type_e type, void* user_data);
122 * @brief Called when the daemon gets a engine setting.
124 * @param[in] key A key
125 * @param[in] value A value
126 * @param[in] user_data The user data passed from the foreach function
128 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
130 * @pre ttspe_foreach_engine_settings() will invoke this callback.
132 * @see ttspe_foreach_engine_settings()
134 typedef bool (*ttspe_engine_setting_cb)(const char* key, const char* value, void* user_data);
137 * @brief Initializes the engine.
139 * @param[in] callbacks A callback function
141 * @return 0 on success, otherwise a negative error value
142 * @retval #TTSP_ERROR_NONE Successful
143 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
144 * @retval #TTSP_ERROR_INVALID_STATE Already initialized
145 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
147 * @see ttspe_deinitialize()
149 typedef int (* ttspe_initialize)(ttspe_result_cb callback);
152 * @brief Deinitializes the engine.
154 * @return 0 on success, otherwise a negative error value
155 * @retval #TTSP_ERROR_NONE Successful
156 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
158 * @see ttspe_initialize()
160 typedef int (* ttspe_deinitialize)(void);
163 * @brief Retrieves all supported voices of the engine using callback function.
165 * @param[in] callback A callback function
166 * @param[in] user_data The user data to be passed to the callback function
168 * @return 0 on success, otherwise a negative error value
169 * @retval #TTSP_ERROR_NONE Successful
170 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
171 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
173 * @post This function invokes ttspe_supported_voice_cb() repeatedly for getting all supported languages.
175 * @see ttspe_supported_voice_cb()
177 typedef int (* ttspe_foreach_supported_voices)(ttspe_supported_voice_cb callback, void* user_data);
180 * @brief Checks whether the voice is valid or not.
182 * @param[in] language A language
183 * @param[in] type A voice type
185 * @return @c true to be valid \n @c false not to be valid
187 * @see ttspe_foreach_supported_voices()
189 typedef bool (* ttspe_is_valid_voice)(const char* language, ttsp_voice_type_e type);
192 * @brief Gets audio format of the engine.
194 * @param[out] types A audio type
195 * @param[out] rate A sample rate
196 * @param[out] channels Channels
198 * @return 0 on success, otherwise a negative error value
199 * @retval #TTSP_ERROR_NONE Successful
200 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
201 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
203 typedef int (* ttspe_get_audio_format)(ttsp_audio_type_e* audio_type, int* rate, int* channel);
206 * @brief Starts voice synthesis, asynchronously.
208 * @param[in] language A language
209 * @param[in] type A voice type
210 * @param[in] text Texts
211 * @param[in] speed A speaking speed
212 * @param[in] user_data The user data to be passed to the callback function
214 * @return 0 on success, otherwise a negative error value
215 * @retval #TTSP_ERROR_NONE Successful
216 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
217 * @retval #TTSP_ERROR_INVALID_STATE Not initialized or already started synthesis
218 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
219 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
220 * @retval #TTSP_ERROR_OUT_OF_NETWORK Out of network
222 * @post This function invokes ttspe_result_cb().
224 * @see ttspe_result_cb()
225 * @see ttspe_cancel_synthesis()
227 typedef int (* ttspe_start_synthesis)(const char* language, ttsp_voice_type_e type, const char* text, ttsp_speed_e speed, void* user_data);
230 * @brief Cancels voice synthesis.
232 * @return 0 on success, otherwise a negative error value
233 * @retval #TTSP_ERROR_NONE Successful
234 * @retval #TTSP_ERROR_INVALID_STATE Not initialized or not started synthesis
236 * @pre The ttspe_start_synthesis() should be performed
238 * @see ttspe_start_synthesis()
240 typedef int (* ttspe_cancel_synthesis)(void);
243 * @brief Gets setting information of the engine.
245 * @param[in] callback A callback function.
246 * @param[in] user_data The user data to be passed to the callback function.
248 * @return 0 on success, otherwise a negative error value
249 * @retval #TTSP_ERROR_NONE Successful
250 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
251 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
252 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
254 * @post This function invokes ttspe_engine_setting_cb() repeatedly for getting all engine settings.
256 * @see ttspe_engine_setting_cb()
258 typedef int (* ttspe_foreach_engine_settings)(ttspe_engine_setting_cb callback, void* user_data);
261 * @brief Sets setting information of the engine.
263 * @param[in] key A key.
264 * @param[in] value A value.
266 * @return 0 on success, otherwise a negative error value
267 * @retval #TTSP_ERROR_NONE Successful
268 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
269 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
270 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
272 * @see ttspe_foreach_engine_settings()
274 typedef int (* ttspe_set_engine_setting)(const char* key, const char* value);
277 * @brief A structure of the engine functions
280 int size; /**< Size of structure */
281 int version; /**< Version */
283 ttspe_initialize initialize; /**< Initialize engine */
284 ttspe_deinitialize deinitialize; /**< Shutdown engine */
286 /* Get / Set engine information */
287 ttspe_foreach_supported_voices foreach_voices; /**< Get voice list */
288 ttspe_is_valid_voice is_valid_voice; /**< Check voice */
289 ttspe_get_audio_format get_audio_format; /**< Get audio format function */
291 /* Control synthesis */
292 ttspe_start_synthesis start_synth; /**< Start synthesis */
293 ttspe_cancel_synthesis cancel_synth; /**< Cancel synthesis */
296 ttspe_foreach_engine_settings foreach_engine_setting; /**< Foreach engine setting */
297 ttspe_set_engine_setting set_engine_setting; /**< Set engine setting */
301 * @brief A structure of the daemon functions
304 int size; /**< size */
305 int version; /**< version */
310 * @brief Loads the engine by the daemon.
312 * @param[in] pdfuncs The daemon functions
313 * @param[out] pefuncs The engine functions
315 * @return 0 on success, otherwise a negative error value
316 * @retval #TTSP_ERROR_NONE Successful
317 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
318 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
320 * @pre The ttsp_get_engine_info() should be successful.
321 * @post The daemon calls the engine functions of ttspe_funcs_s.
323 * @see ttsp_get_engine_info()
324 * @see ttsp_unload_engine()
326 int ttsp_load_engine(ttspd_funcs_s* pdfuncs, ttspe_funcs_s* pefuncs);
329 * @brief Unloads the engine by the daemon.
331 * @pre The ttsp_load_engine() should be performed.
333 * @see ttsp_load_engine()
335 void ttsp_unload_engine(void);
338 * @brief Called to get this engine base information.
340 * @param[in] engine_uuid The engine id
341 * @param[in] engine_name The engine name
342 * @param[in] setting_ug_name The setting ug name
343 * @param[in] use_network @c true to need network \n @c false not to need network
344 * @param[in] user_data The user data passed from the engine info function
346 * @pre ttsp_get_engine_info() will invoke this callback.
348 * @see ttsp_get_engine_info()
350 typedef void (*ttsp_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* setting_ug_name,
351 bool use_network, void* user_data);
354 * @brief Gets base information of the engine by the daemon.
356 * @param[in] callback A callback function
357 * @param[in] user_data The user data to be passed to the callback function
359 * @return 0 on success, otherwise a negative error value
360 * @retval #TTSP_ERROR_NONE Successful
361 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
362 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
364 * @post This function invokes ttsp_engine_info_cb() for getting engine information.
366 * @see ttsp_engine_info_cb()
367 * @see ttsp_load_engine()
369 int ttsp_get_engine_info(ttsp_engine_info_cb callback, void* user_data);
379 #endif /* __TTSP_H__ */