2 * Copyright (c) 2011-2016 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
31 * @addtogroup CAPI_UIX_TTS_MODULE
42 * @brief Enumeration for error code.
43 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
46 TTS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
47 TTS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
48 TTS_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
49 TTS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
50 TTS_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Network is down */
51 TTS_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from the daemon */
52 TTS_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
53 TTS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< TTS NOT supported */
54 TTS_ERROR_INVALID_STATE = TIZEN_ERROR_TTS | 0x01, /**< Invalid state */
55 TTS_ERROR_INVALID_VOICE = TIZEN_ERROR_TTS | 0x02, /**< Invalid voice */
56 TTS_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_TTS | 0x03, /**< No available engine */
57 TTS_ERROR_OPERATION_FAILED = TIZEN_ERROR_TTS | 0x04, /**< Operation failed */
58 TTS_ERROR_AUDIO_POLICY_BLOCKED = TIZEN_ERROR_TTS | 0x05, /**< Audio policy blocked */
59 TTS_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_TTS | 0x06, /**< Not supported feature of current engine @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
60 TTS_ERROR_SERVICE_RESET = TIZEN_ERROR_TTS | 0x07 /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
65 * @brief Enumeration for TTS mode.
66 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
69 TTS_MODE_DEFAULT = 0, /**< Default mode for normal application */
70 TTS_MODE_NOTIFICATION = 1, /**< Notification mode */
71 TTS_MODE_SCREEN_READER = 2 /**< Accessibility mode */
76 * @brief Enumeration for state.
77 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
80 TTS_STATE_CREATED = 0, /**< 'CREATED' state */
81 TTS_STATE_READY = 1, /**< 'READY' state */
82 TTS_STATE_PLAYING = 2, /**< 'PLAYING' state */
83 TTS_STATE_PAUSED = 3 /**< 'PAUSED' state*/
88 * @brief Definition for automatic speaking speed.
89 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
91 #define TTS_SPEED_AUTO 0
95 * @brief Definition for automatic voice type.
96 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
98 #define TTS_VOICE_TYPE_AUTO 0
102 * @brief Definition for male voice type.
103 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
105 #define TTS_VOICE_TYPE_MALE 1
109 * @brief Definition for female voice type.
110 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
112 #define TTS_VOICE_TYPE_FEMALE 2
116 * @brief Definition for child voice type.
117 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
119 #define TTS_VOICE_TYPE_CHILD 3
123 * @brief The TTS handle.
124 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
126 typedef struct tts_s *tts_h;
130 * @brief Called when the state of TTS is changed.
131 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132 * @details If the daemon must stop player because of changing engine and
133 * the daemon must pause player because of other requests, this callback function is called.
134 * @param[in] tts The TTS handle
135 * @param[in] previous The previous state
136 * @param[in] current The current state
137 * @param[in] user_data The user data passed from the callback registration function
138 * @pre An application registers this callback using tts_set_state_changed_cb() to detect changing state.
139 * @see tts_set_state_changed_cb()
140 * @see tts_unset_state_changed_cb()
142 typedef void (*tts_state_changed_cb)(tts_h tts, tts_state_e previous, tts_state_e current, void* user_data);
146 * @brief Called when utterance has started.
147 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
148 * @param[in] tts The TTS handle
149 * @param[in] utt_id The utterance ID passed from the add text function
150 * @param[in] user_data The user data passed from the callback registration function
151 * @pre An application registers this callback using tts_set_utterance_started_cb() to detect utterance started.
152 * @see tts_add_text()
153 * @see tts_set_utterance_started_cb()
154 * @see tts_unset_utterance_started_cb()
156 typedef void (*tts_utterance_started_cb)(tts_h tts, int utt_id, void* user_data);
160 * @brief Called when utterance is finished.
161 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
162 * @param[in] tts The TTS handle
163 * @param[in] utt_id The utterance ID passed from the add text function
164 * @param[in] user_data The user data passed from the callback registration function
165 * @pre An application registers this callback using tts_set_utterance_completed_cb() to detect utterance completed.
166 * @see tts_add_text()
167 * @see tts_set_utterance_completed_cb()
168 * @see tts_unset_utterance_completed_cb()
170 typedef void (*tts_utterance_completed_cb)(tts_h tts, int utt_id, void *user_data);
174 * @brief Called when an error occurs.
175 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
176 * @param[in] tts The TTS handle
177 * @param[in] utt_id The utterance ID passed from the add text function
178 * @param[in] reason The error code
179 * @param[in] user_data The user data passed from the callback registration function
180 * @pre An application registers this callback using tts_set_error_cb() to detect error.
184 * @see tts_set_error_cb()
185 * @see tts_unset_error_cb()
187 typedef void (*tts_error_cb)(tts_h tts, int utt_id, tts_error_e reason, void* user_data);
191 * @brief Called to retrieve the supported voice.
192 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
193 * @param[in] tts The TTS handle
194 * @param[in] language Language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
195 * @param[in] voice_type A voice type (e.g. #TTS_VOICE_TYPE_MALE, #TTS_VOICE_TYPE_FEMALE)
196 * @param[in] user_data The user data passed from the foreach function
197 * @return @c true to continue with the next iteration of the loop,
198 * @c false to break out of the loop
199 * @pre tts_foreach_supported_voices() will invoke this callback function.
200 * @see tts_foreach_supported_voices()
202 typedef bool(*tts_supported_voice_cb)(tts_h tts, const char* language, int voice_type, void* user_data);
206 * @brief Called when the default voice is changed.
207 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
208 * @param[in] tts The TTS handle
209 * @param[in] previous_language The previous language
210 * @param[in] previous_voice_type The previous voice type
211 * @param[in] current_language The current language
212 * @param[in] current_voice_type The current voice type
213 * @param[in] user_data The user data passed from the callback registration function
214 * @see tts_set_default_voice_changed_cb()
216 typedef void (*tts_default_voice_changed_cb)(tts_h tts, const char* previous_language, int previous_voice_type,
217 const char* current_language, int current_voice_type, void* user_data);
221 * @brief Called when the engine is changed.
222 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
223 * @param[in] tts The TTS handle
224 * @param[in] engine_id Engine ID
225 * @param[in] language The default language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
226 * @param[in] voice_type The default voice type
227 * @param[in] need_credential The necessity of credential
228 * @param[in] user_data The user data passed from the callback registration function
229 * @see tts_set_engine_changed_cb()
231 typedef void (*tts_engine_changed_cb)(tts_h tts, const char* engine_id, const char* language, int voice_type, bool need_credential, void* user_data);
235 * @brief Creates a handle for TTS.
236 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
237 * @remarks If the function succeeds, @a tts handle must be released with tts_destroy().
238 * @param[out] tts The TTS handle
239 * @return @c 0 on success,
240 * otherwise a negative error value
241 * @retval #TTS_ERROR_NONE Successful
242 * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
243 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
244 * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
245 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
246 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
247 * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
250 int tts_create(tts_h* tts);
254 * @brief Destroys the handle and disconnects the daemon.
255 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
256 * @param[in] tts The TTS handle
257 * @return @c 0 on success,
258 * otherwise a negative error value
259 * @retval #TTS_ERROR_NONE Successful
260 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
261 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
262 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
265 int tts_destroy(tts_h tts);
269 * @brief Sets the TTS mode.
270 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
271 * @param[in] tts The TTS handle
272 * @param[in] mode The mode
273 * @return @c 0 on success,
274 * otherwise a negative error value
275 * @retval #TTS_ERROR_NONE Successful
276 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
277 * @retval #TTS_ERROR_INVALID_STATE Invalid state
278 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
279 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
280 * @pre The state should be #TTS_STATE_CREATED.
281 * @see tts_get_mode()
283 int tts_set_mode(tts_h tts, tts_mode_e mode);
287 * @brief Gets the TTS mode.
288 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
289 * @param[in] tts The TTS handle
290 * @param[out] mode The mode
291 * @return @c 0 on success,
292 * otherwise a negative error value
293 * @retval #TTS_ERROR_NONE Successful
294 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
295 * @retval #TTS_ERROR_INVALID_STATE Invalid state
296 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
297 * @pre The state should be #TTS_STATE_CREATED.
298 * @see tts_set_mode()
300 int tts_get_mode(tts_h tts, tts_mode_e* mode);
304 * @brief Sets the app credential.
305 * @details Using this API, the application can set a credential.
306 * The credential is a key to verify the authorization about using the engine.
307 * If the application sets the credential, it will be able to use functions of the engine entirely.
308 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
309 * @remarks The necessity of the credential depends on the engine. In case of the engine which is basically embedded in Tizen, the credential is not necessary so far.
310 * However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
311 * @param[in] tts The TTS handle
312 * @param[in] credential The app credential
313 * @return @c 0 on success,
314 * otherwise a negative error value
315 * @retval #TTS_ERROR_NONE Success
316 * @retval #TTS_ERROR_INVALID_STATE Invalid state
317 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
318 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
319 * @pre The state should be #TTS_STATE_CREATED or #TTS_STATE_READY.
322 int tts_set_credential(tts_h tts, const char* credential);
326 * @brief Connects the daemon asynchronously.
327 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
328 * @param[in] tts The TTS handle
329 * @return @c 0 on success,
330 * otherwise a negative error value
331 * @retval #TTS_ERROR_NONE Successful
332 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
333 * @retval #TTS_ERROR_INVALID_STATE Invalid state
334 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
335 * @pre The state should be #TTS_STATE_CREATED.
336 * @post If this function is successful, the TTS state will be #TTS_STATE_READY.
337 * If this function is failed, the error callback is called. (e.g. #TTS_ERROR_ENGINE_NOT_FOUND)
338 * @see tts_unprepare()
340 int tts_prepare(tts_h tts);
344 * @brief Disconnects the daemon.
345 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
346 * @param[in] tts The TTS handle
347 * @return @c 0 on success,
348 * otherwise a negative error value
349 * @retval #TTS_ERROR_NONE Successful
350 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
351 * @retval #TTS_ERROR_INVALID_STATE Invalid state
352 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
353 * @pre The state should be #TTS_STATE_READY.
354 * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
357 int tts_unprepare(tts_h tts);
361 * @brief Retrieves all supported voices of the current engine using callback function.
362 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
363 * @param[in] tts The TTS handle
364 * @param[in] callback The callback function to invoke
365 * @param[in] user_data The user data to be passed to the callback function
366 * @return @c 0 on success,
367 * otherwise a negative error value
368 * @retval #TTS_ERROR_NONE Successful
369 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
371 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
372 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
373 * @post This function invokes tts_supported_voice_cb() repeatedly for getting voices.
374 * @see tts_get_default_voice()
376 int tts_foreach_supported_voices(tts_h tts, tts_supported_voice_cb callback, void* user_data);
380 * @brief Gets the default voice set by the user.
381 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
382 * @remarks If the function succeeds, @a language must be released with free().
383 * @param[in] tts The TTS handle
384 * @param[out] language Language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
385 * @param[out] voice_type The voice type
386 * @return @c 0 on success,
387 * otherwise a negative error value
388 * @retval #TTS_ERROR_NONE Successful
389 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
390 * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
391 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
392 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
393 * @see tts_foreach_supported_voices()
395 int tts_get_default_voice(tts_h tts, char** language, int* voice_type);
399 * @brief Sets the private data to tts engine.
400 * @details The private data is the setting parameter for applying keys provided by the engine.
401 * Using this API, the application can set the private data and use the corresponding key of the engine.
402 * For example, if the engine provides 'girl's voice' as a voice type, the application can set the private data as the following.
403 * int ret = tts_set_private_data(tts_h, "voice_type", "GIRL");
404 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
405 * @remarks If the engine is replaced with the other engine, the key may be ignored.
406 * @param[in] tts The TTS handle
407 * @param[in] key The field name of private data
408 * @param[in] data The data for set
409 * @return @c 0 on success,
410 * otherwise a negative error value
411 * @retval #TTS_ERROR_NONE Successful
412 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
413 * @retval #TTS_ERROR_INVALID_STATE Invalid state
414 * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
415 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
416 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
417 * @pre The state should be #TTS_STATE_READY.
418 * @see tts_get_private_data()
420 int tts_set_private_data(tts_h tts, const char* key, const char* data);
424 * @brief Gets the private data from tts engine.
425 * @details The private data is the information provided by the engine.
426 * Using this API, the application can get the private data which corresponds to the key from the engine.
427 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
428 * @remarks The @a data must be released using free() when it is no longer required.
429 * If the engine is replaced with the other engine, the key may be ignored.
430 * @param[in] tts The TTS handle
431 * @param[in] key The field name of private data
432 * @param[out] data The data field of private data
433 * @return @c 0 on success,
434 * otherwise a negative error value
435 * @retval #TTS_ERROR_NONE Successful
436 * @retval #TTS_ERROR_INVALID_STATE Invalid state
437 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
438 * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
439 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
440 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
441 * @pre The state should be #TTS_STATE_READY.
442 * @see tts_set_private_data()
444 int tts_get_private_data(tts_h tts, const char* key, char** data);
448 * @brief Gets the maximum byte size for text.
449 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
450 * @param[in] tts The TTS handle
451 * @param[out] size The maximum byte size for text
452 * @return @c 0 on success,
453 * otherwise a negative error value
454 * @retval #TTS_ERROR_NONE Successful
455 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
456 * @retval #TTS_ERROR_INVALID_STATE Invalid state
457 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
458 * @pre The state should be #TTS_STATE_READY.
459 * @see tts_add_text()
461 int tts_get_max_text_size(tts_h tts, unsigned int* size);
465 * @brief Gets the current state of TTS.
466 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
467 * @param[in] tts The TTS handle
468 * @param[out] state The current state of TTS
469 * @return @c 0 on success,
470 * otherwise a negative error value
471 * @retval #TTS_ERROR_NONE Successful
472 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
473 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
478 int tts_get_state(tts_h tts, tts_state_e* state);
482 * @brief Gets the speed range.
483 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
484 * @param[in] tts The TTS handle
485 * @param[out] min The minimum speed value
486 * @param[out] normal The normal speed value
487 * @param[out] max The maximum speed value
488 * @return @c 0 on success,
489 * otherwise a negative error value
490 * @retval #TTS_ERROR_NONE Successful
491 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
492 * @retval #TTS_ERROR_INVALID_STATE Invalid state
493 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
494 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
495 * @pre The state should be #TTS_STATE_CREATED.
496 * @see tts_add_text()
498 int tts_get_speed_range(tts_h tts, int* min, int* normal, int* max);
502 * @brief Gets the current error message.
503 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
504 * @remarks This function should be called from a tts error callback. Calling in any other context will result in an Operation failed error.
505 * A successful call will allocate @a err_msg, which must be released by calling free() when it is no longer required.
506 * @param[in] tts The TTS handle
507 * @param[out] err_msg The current error message
508 * @return @c 0 on success,
509 * otherwise a negative error value
510 * @retval #TTS_ERROR_NONE Successful
511 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
512 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
513 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
514 * @see tts_set_error_cb()
515 * @see tts_unset_error_cb()
517 int tts_get_error_message(tts_h tts, char** err_msg);
521 * @brief Adds a text to the queue.
522 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
523 * @remarks Locale(e.g. setlocale()) MUST be set for utf8 text validation check.
524 * @param[in] tts The TTS handle
525 * @param[in] text An input text based utf8
526 * @param[in] language The language selected from the tts_foreach_supported_voices() (e.g. 'NULL'(Automatic), 'en_US')
527 * @param[in] voice_type The voice type selected from the tts_foreach_supported_voices() (e.g. #TTS_VOICE_TYPE_AUTO, #TTS_VOICE_TYPE_FEMALE)
528 * @param[in] speed A speaking speed (e.g. #TTS_SPEED_AUTO or the value from tts_get_speed_range())
529 * @param[out] utt_id The utterance ID passed to the callback function
530 * @return @c 0 on success,
531 * otherwise a negative error value
532 * @retval #TTS_ERROR_NONE Successful
533 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
534 * @retval #TTS_ERROR_INVALID_STATE Invalid state
535 * @retval #TTS_ERROR_INVALID_VOICE Invalid voice about language, voice type
536 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
537 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
538 * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
539 * @pre The state should be #TTS_STATE_READY, #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
540 * @see tts_get_max_text_size()
541 * @see tts_set_credential()
543 int tts_add_text(tts_h tts, const char* text, const char* language, int voice_type, int speed, int* utt_id);
547 * @brief Starts synthesizing voice from the text and plays the synthesized audio data.
548 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
549 * @param[in] tts The TTS handle
550 * @return @c 0 on success,
551 * otherwise a negative error value
552 * @retval #TTS_ERROR_NONE Successful
553 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
554 * @retval #TTS_ERROR_OUT_OF_NETWORK Out of network
555 * @retval #TTS_ERROR_INVALID_STATE Invalid state
556 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
557 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
558 * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
559 * @pre The current state should be #TTS_STATE_READY or #TTS_STATE_PAUSED.
560 * @post If this function succeeds, the TTS state will be #TTS_STATE_PLAYING.
561 * @see tts_add_text()
564 * @see tts_utterance_started_cb()
565 * @see tts_utterance_completed_cb()
566 * @see tts_error_cb()
567 * @see tts_set_credential()
569 int tts_play(tts_h tts);
573 * @brief Stops playing the utterance and clears the queue.
574 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
575 * @param[in] tts The TTS handle
576 * @return @c 0 on success,
577 * otherwise a negative error value
578 * @retval #TTS_ERROR_NONE Successful
579 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
580 * @retval #TTS_ERROR_INVALID_STATE Invalid state
581 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
582 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
583 * @pre The TTS state should be #TTS_STATE_READY or #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
584 * @post If this function succeeds, the TTS state will be #TTS_STATE_READY.
585 * This function will remove all text via tts_add_text() and synthesized sound data.
589 int tts_stop(tts_h tts);
593 * @brief Pauses the currently playing utterance.
594 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
595 * @param[in] tts The TTS handle
596 * @return @c 0 on success,
597 * otherwise a negative error value
598 * @retval #TTS_ERROR_NONE Successful
599 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
600 * @retval #TTS_ERROR_INVALID_STATE Invalid state
601 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
602 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
603 * @pre The TTS state should be #TTS_STATE_PLAYING.
604 * @post If this function succeeds, the TTS state will be #TTS_STATE_PAUSED.
607 * @see tts_error_cb()
608 * @see tts_interrupted_cb()
610 int tts_pause(tts_h tts);
613 * @brief Repeats the last played text.
615 * @remarks This function repeats the last played text once. If there is no previous text, this function will not work.
616 * If the language is changed, the last played text is removed.
617 * Before calling this function, please call 'tts_stop()' in order to stop playing the previous one.
618 * If this function succeeds, @a text_repeat must be released with free().
619 * @param[in] tts The TTS handle
620 * @param[out] text_repeat Texts to be played repeatedly
621 * @param[out] utt_id The utterance ID passed to the callback function
623 * @return @c 0 on success,
624 * otherwise a negative error value
625 * @retval #TTS_ERROR_NONE Successful
626 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
627 * @retval #TTS_ERROR_INVALID_STATE Invalid state
628 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
629 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
630 * @pre The state should be #TTS_STATE_READY.
631 * @post If this function succeeds, the TTS state will be #TTS_STATE_PLAYING.
632 * @see tts_add_text()
635 int tts_repeat(tts_h tts, char** text_repeat, int* utt_id);
638 * @brief Registers a callback function to be called when the TTS state changes.
639 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
640 * @param[in] tts The TTS handle
641 * @param[in] callback The callback function to register
642 * @param[in] user_data The user data to be passed to the callback function
643 * @return @c 0 on success,
644 * otherwise a negative error value
645 * @retval #TTS_ERROR_NONE Successful
646 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
647 * @retval #TTS_ERROR_INVALID_STATE Invalid state
648 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
649 * @pre The state should be #TTS_STATE_CREATED.
650 * @see tts_state_changed_cb()
651 * @see tts_unset_state_changed_cb()
653 int tts_set_state_changed_cb(tts_h tts, tts_state_changed_cb callback, void* user_data);
657 * @brief Unregisters the callback function.
658 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
659 * @param[in] tts The TTS handle
660 * @return @c 0 on success,
661 * otherwise a negative error value
662 * @retval #TTS_ERROR_NONE Successful
663 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
664 * @retval #TTS_ERROR_INVALID_STATE Invalid state
665 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
666 * @pre The state should be #TTS_STATE_CREATED.
667 * @see tts_set_state_changed_cb()
669 int tts_unset_state_changed_cb(tts_h tts);
673 * @brief Registers a callback function to detect utterance start.
674 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
675 * @param[in] tts The TTS handle
676 * @param[in] callback The callback function to register
677 * @param[in] user_data The user data to be passed to the callback function
678 * @return @c 0 on success,
679 * otherwise a negative error value
680 * @retval #TTS_ERROR_NONE Successful
681 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
682 * @retval #TTS_ERROR_INVALID_STATE Invalid state
683 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
684 * @pre The state should be #TTS_STATE_CREATED.
685 * @see tts_utterance_started_cb()
686 * @see tts_unset_utterance_started_cb()
688 int tts_set_utterance_started_cb(tts_h tts, tts_utterance_started_cb callback, void* user_data);
692 * @brief Unregisters the callback function.
693 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
694 * @param[in] tts The TTS handle
695 * @return @c 0 on success,
696 * otherwise a negative error value
697 * @retval #TTS_ERROR_NONE Successful
698 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
699 * @retval #TTS_ERROR_INVALID_STATE Invalid state
700 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
701 * @pre The state should be #TTS_STATE_CREATED.
702 * @see tts_set_utterance_started_cb()
704 int tts_unset_utterance_started_cb(tts_h tts);
708 * @brief Registers a callback function to detect utterance completion.
709 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
710 * @param[in] tts The TTS handle
711 * @param[in] callback The callback function to register
712 * @param[in] user_data The user data to be passed to the callback function
713 * @return @c 0 on success,
714 * otherwise a negative error value
715 * @retval #TTS_ERROR_NONE Successful
716 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
717 * @retval #TTS_ERROR_INVALID_STATE Invalid state
718 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
719 * @pre The state should be #TTS_STATE_CREATED.
720 * @see tts_utterance_completed_cb()
721 * @see tts_unset_utterance_completed_cb()
723 int tts_set_utterance_completed_cb(tts_h tts, tts_utterance_completed_cb callback, void* user_data);
727 * @brief Unregisters the callback function.
728 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
729 * @param[in] tts The TTS handle
730 * @return @c 0 on success,
731 * otherwise a negative error value
732 * @retval #TTS_ERROR_NONE Successful
733 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
734 * @retval #TTS_ERROR_INVALID_STATE Invalid state
735 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
736 * @pre The state should be #TTS_STATE_CREATED.
737 * @see tts_set_utterance_completed_cb()
739 int tts_unset_utterance_completed_cb(tts_h tts);
743 * @brief Registers a callback function to detect errors.
744 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
745 * @param[in] tts The TTS handle
746 * @param[in] callback The callback function to register
747 * @param[in] user_data The user data to be passed to the callback function
748 * @return @c 0 on success,
749 * otherwise a negative error value
750 * @retval #TTS_ERROR_NONE Successful
751 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
752 * @retval #TTS_ERROR_INVALID_STATE Invalid state
753 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
754 * @pre The state should be #TTS_STATE_CREATED.
755 * @see tts_error_cb()
756 * @see tts_unset_error_cb()
758 int tts_set_error_cb(tts_h tts, tts_error_cb callback, void* user_data);
762 * @brief Unregisters the callback function.
763 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
764 * @param[in] tts The TTS handle
765 * @return @c 0 on success,
766 * otherwise a negative error value
767 * @retval #TTS_ERROR_NONE Successful
768 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
769 * @retval #TTS_ERROR_INVALID_STATE Invalid state
770 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
771 * @pre The state should be #TTS_STATE_CREATED.
772 * @see tts_set_error_cb()
774 int tts_unset_error_cb(tts_h tts);
778 * @brief Registers a callback function to detect default voice change.
779 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
780 * @param[in] tts The TTS handle
781 * @param[in] callback The callback function to register
782 * @param[in] user_data The user data to be passed to the callback function
783 * @return @c 0 on success,
784 * otherwise a negative error value
785 * @retval #TTS_ERROR_NONE Successful
786 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
787 * @retval #TTS_ERROR_INVALID_STATE Invalid state
788 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
789 * @pre The state should be #TTS_STATE_CREATED.
790 * @see tts_default_voice_changed_cb()
791 * @see tts_unset_default_voice_changed_cb()
793 int tts_set_default_voice_changed_cb(tts_h tts, tts_default_voice_changed_cb callback, void* user_data);
797 * @brief Unregisters the callback function.
798 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
799 * @param[in] tts The TTS handle
800 * @return @c 0 on success,
801 * otherwise a negative error value
802 * @retval #TTS_ERROR_NONE Successful
803 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
804 * @retval #TTS_ERROR_INVALID_STATE Invalid state
805 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
806 * @pre The state should be #TTS_STATE_CREATED.
807 * @see tts_set_default_voice_changed_cb()
809 int tts_unset_default_voice_changed_cb(tts_h tts);
813 * @brief Registers a callback function to detect the engine change.
814 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
815 * @param[in] tts The TTS handle
816 * @param[in] callback The callback function to register
817 * @param[in] user_data The user data to be passed to the callback function
818 * @return @c 0 on success,
819 * otherwise a negative error value
820 * @retval #TTS_ERROR_NONE Successful
821 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
822 * @retval #TTS_ERROR_INVALID_STATE Invalid state
823 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
824 * @pre The state should be #TTS_STATE_CREATED.
825 * @see tts_engine_changed_cb()
826 * @see tts_unset_engine_changed_cb()
828 int tts_set_engine_changed_cb(tts_h tts, tts_engine_changed_cb callback, void* user_data);
832 * @brief Unregisters the callback function.
833 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
834 * @param[in] tts The TTS handle
835 * @return @c 0 on success,
836 * otherwise a negative error value
837 * @retval #TTS_ERROR_NONE Successful
838 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
839 * @retval #TTS_ERROR_INVALID_STATE Invalid state
840 * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
841 * @pre The state should be #TTS_STATE_CREATED.
842 * @see tts_set_engine_changed_cb()
844 int tts_unset_engine_changed_cb(tts_h tts);
857 #endif /* __TTS_H__ */