include/tts.h

   1 /*
   2  * Copyright (c) 2011-2014 Samsung Electronics Co., Ltd All Rights Reserved
   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
  18 #ifndef __TTS_H__
  19 #define __TTS_H__
  20
  21 #include <tizen.h>
  22
  23 /**
  24 * @file tts.h
  25 */
  26
  27 /**
  28 * @addtogroup CAPI_UIX_TTS_MODULE
  29 * @{
  30 */
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @brief Enumeration for error code.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39 */
  40 typedef enum {
  41         TTS_ERROR_NONE                  = TIZEN_ERROR_NONE,             /**< Successful */
  42         TTS_ERROR_OUT_OF_MEMORY         = TIZEN_ERROR_OUT_OF_MEMORY,    /**< Out of Memory */
  43         TTS_ERROR_IO_ERROR              = TIZEN_ERROR_IO_ERROR,         /**< I/O error */
  44         TTS_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
  45         TTS_ERROR_OUT_OF_NETWORK        = TIZEN_ERROR_NETWORK_DOWN,     /**< Network is down */
  46         TTS_ERROR_TIMED_OUT             = TIZEN_ERROR_TIMED_OUT,        /**< No answer from the daemon */
  47         TTS_ERROR_PERMISSION_DENIED     = TIZEN_ERROR_PERMISSION_DENIED,/**< Permission denied */
  48         TTS_ERROR_NOT_SUPPORTED         = TIZEN_ERROR_NOT_SUPPORTED,    /**< TTS NOT supported */
  49         TTS_ERROR_INVALID_STATE         = TIZEN_ERROR_TTS | 0x01,       /**< Invalid state */
  50         TTS_ERROR_INVALID_VOICE         = TIZEN_ERROR_TTS | 0x02,       /**< Invalid voice */
  51         TTS_ERROR_ENGINE_NOT_FOUND      = TIZEN_ERROR_TTS | 0x03,       /**< No available engine */
  52         TTS_ERROR_OPERATION_FAILED      = TIZEN_ERROR_TTS | 0x04,       /**< Operation failed */
  53         TTS_ERROR_AUDIO_POLICY_BLOCKED  = TIZEN_ERROR_TTS | 0x05        /**< Audio policy blocked */
  54 } tts_error_e;
  55
  56 /**
  57  * @brief Enumeration for TTS mode.
  58  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  59 */
  60 typedef enum {
  61         TTS_MODE_DEFAULT        = 0,    /**< Default mode for normal application */
  62         TTS_MODE_NOTIFICATION   = 1,    /**< Notification mode */
  63         TTS_MODE_SCREEN_READER  = 2     /**< Accessibiliity mode */
  64 } tts_mode_e;
  65
  66 /**
  67  * @brief Enumerations for state.
  68  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  69 */
  70 typedef enum {
  71         TTS_STATE_CREATED       = 0,    /**< 'CREATED' state */
  72         TTS_STATE_READY         = 1,    /**< 'READY' state */
  73         TTS_STATE_PLAYING       = 2,    /**< 'PLAYING' state */
  74         TTS_STATE_PAUSED        = 3     /**< 'PAUSED' state*/
  75 } tts_state_e;
  76
  77 /**
  78  * @brief Definitions for automatic speaking speed.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80 */
  81 #define TTS_SPEED_AUTO          0
  82
  83 /**
  84  * @brief Definitions for automatic voice type.
  85  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  86 */
  87 #define TTS_VOICE_TYPE_AUTO     0
  88
  89 /**
  90  * @brief Definitions for male voice type.
  91  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  92 */
  93 #define TTS_VOICE_TYPE_MALE     1
  94
  95 /**
  96  * @brief Definitions for female voice type.
  97  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  98 */
  99 #define TTS_VOICE_TYPE_FEMALE   2
 100
 101 /**
 102  * @brief Definitions for child voice type.
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 104 */
 105 #define TTS_VOICE_TYPE_CHILD    3
 106
 107 /**
 108  * @brief The TTS handle.
 109  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 110 */
 111 typedef struct tts_s *tts_h;
 112
 113
 114 /**
 115  * @brief Called when the state of TTS is changed.
 116  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 117  *
 118  * @details If the daemon must stop player because of changing engine and
 119  *      the daemon must pause player because of other requests, this callback function is called.
 120  *
 121  * @param[in] tts The TTS handle
 122  * @param[in] previous The previous state
 123  * @param[in] current The current state
 124  * @param[in] user_data The user data passed from the callback registration function
 125  *
 126  * @pre An application registers this callback using tts_set_state_changed_cb() to detect changing state.
 127  *
 128  * @see tts_set_state_changed_cb()
 129  * @see tts_unset_state_changed_cb()
 130 */
 131 typedef void (*tts_state_changed_cb)(tts_h tts, tts_state_e previous, tts_state_e current, void* user_data);
 132
 133 /**
 134  * @brief Called when utterance has started.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136  *
 137  * @param[in] tts The TTS handle
 138  * @param[in] utt_id The utterance ID passed from the add text function
 139  * @param[in] user_data The user data passed from the callback registration function
 140  *
 141  * @pre An application registers this callback using tts_set_utterance_started_cb() to detect utterance started.
 142  *
 143  * @see tts_add_text()
 144  * @see tts_set_utterance_started_cb()
 145  * @see tts_unset_utterance_started_cb()
 146 */
 147 typedef void (*tts_utterance_started_cb)(tts_h tts, int utt_id, void* user_data);
 148
 149 /**
 150  * @brief Called when utterance is finished.
 151  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 152  *
 153  * @param[in] tts The TTS handle
 154  * @param[in] utt_id The utterance ID passed from the add text function
 155  * @param[in] user_data The user data passed from the callback registration function
 156  *
 157  * @pre An application registers this callback using tts_set_utterance_completed_cb() to detect utterance completed.
 158  *
 159  * @see tts_add_text()
 160  * @see tts_set_utterance_completed_cb()
 161  * @see tts_unset_utterance_completed_cb()
 162 */
 163 typedef void (*tts_utterance_completed_cb)(tts_h tts, int utt_id, void *user_data);
 164
 165 /**
 166  * @brief Called when an error occurs.
 167  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 168  *
 169  * @param[in] tts The TTS handle
 170  * @param[in] utt_id The utterance ID passed from the add text function
 171  * @param[in] reason The error code
 172  * @param[in] user_data The user data passed from the callback registration function
 173  *
 174  * @pre An application registers this callback using tts_set_error_cb() to detect error.
 175  *
 176  * @see tts_play()
 177  * @see tts_pause()
 178  * @see tts_stop()
 179  * @see tts_set_error_cb()
 180  * @see tts_unset_error_cb()
 181 */
 182 typedef void (*tts_error_cb)(tts_h tts, int utt_id, tts_error_e reason, void* user_data);
 183
 184 /**
 185  * @brief Called to retrieve the supported voice.
 186  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 187  *
 188  * @param[in] tts The TTS handle
 189  * @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)
 190  * @param[in] voice_type A voice type (e.g. #TTS_VOICE_TYPE_MALE, #TTS_VOICE_TYPE_FEMALE)
 191  * @param[in] user_data The user data passed from the foreach function
 192  *
 193  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
 194  * @pre tts_foreach_supported_voices() will invoke this callback function.
 195  *
 196  * @see tts_foreach_supported_voices()
 197 */
 198 typedef bool(*tts_supported_voice_cb)(tts_h tts, const char* language, int voice_type, void* user_data);
 199
 200 /**
 201  * @brief Called when the default voice is changed.
 202  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 203  *
 204  * @param[in] tts The TTS handle
 205  * @param[in] previous_language The previous language
 206  * @param[in] previous_voice_type The previous voice type
 207  * @param[in] current_language The current language
 208  * @param[in] current_voice_type The current voice type
 209  * @param[in] user_data The user data passed from the callback registration function
 210  *
 211  * @see tts_set_default_voice_changed_cb()
 212 */
 213 typedef void (*tts_default_voice_changed_cb)(tts_h tts, const char* previous_language, int previous_voice_type,
 214                                 const char* current_language, int current_voice_type, void* user_data);
 215
 216
 217 /**
 218  * @brief Creates a handle for TTS.
 219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 220  *
 221  * @remarks If the function succeeds, @a tts handle must be released with tts_destroy().
 222  *
 223  * @param[out] tts The TTS handle
 224  *
 225  * @return 0 on success, otherwise a negative error value
 226  * @retval #TTS_ERROR_NONE Successful
 227  * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
 228  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 230  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 231  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 232  *
 233  * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
 234  *
 235  * @see tts_destroy()
 236 */
 237 int tts_create(tts_h* tts);
 238
 239 /**
 240  * @brief Destroys the handle and disconnects the daemon.
 241  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 242  *
 243  * @param[in] tts The TTS handle
 244  *
 245  * @return 0 on success, otherwise a negative error value
 246  * @retval #TTS_ERROR_NONE Successful
 247  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 248  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 249  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 250  *
 251  * @see tts_create()
 252 */
 253 int tts_destroy(tts_h tts);
 254
 255 /**
 256  * @brief Sets the TTS mode.
 257  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 258  *
 259  * @param[in] tts The TTS handle
 260  * @param[in] mode The mode
 261  *
 262  * @return 0 on success, otherwise a negative error value
 263  * @retval #TTS_ERROR_NONE Successful
 264  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 265  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 266  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 267  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 268  *
 269  * @pre The state should be #TTS_STATE_CREATED.
 270  *
 271  * @see tts_get_mode()
 272 */
 273 int tts_set_mode(tts_h tts, tts_mode_e mode);
 274
 275 /**
 276  * @brief Gets the TTS mode.
 277  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 278  *
 279  * @param[in] tts The TTS handle
 280  * @param[out] mode The mode
 281  *
 282  * @return 0 on success, otherwise a negative error value
 283  * @retval #TTS_ERROR_NONE Successful
 284  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 285  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 286  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 287  *
 288  * @pre The state should be #TTS_STATE_CREATED.
 289  *
 290  * @see tts_set_mode()
 291 */
 292 int tts_get_mode(tts_h tts, tts_mode_e* mode);
 293
 294 /**
 295  * @brief Sets the app credential.
 296  * @since_tizen 3.0
 297  * @privlevel public
 298  *
 299  * @param[in] tts The TTS handle
 300  * @param[in] credential The app credential
 301  *
 302  * @return 0 on success, otherwise a negative error value
 303  * @retval #TTS_ERROR_NONE Success
 304  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 305  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 306  *
 307  * @pre The state should be #TTS_STATE_CREATED or #TTS_STATE_READY.
 308  *
 309  * @see tts_play()
 310 */
 311 int tts_set_credential(tts_h tts, const char* credential);
 312
 313 /**
 314  * @brief Connects the daemon asynchronously.
 315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 316  *
 317  * @param[in] tts The TTS handle
 318  *
 319  * @return 0 on success, otherwise a negative error value
 320  * @retval #TTS_ERROR_NONE Successful
 321  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 322  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 323  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 324  *
 325  * @pre The state should be #TTS_STATE_CREATED.
 326  * @post If this function is successful, the TTS state will be #TTS_STATE_READY. \n
 327  *      If this function is failed, the error callback is called. (e.g. #TTS_ERROR_ENGINE_NOT_FOUND)
 328  *
 329  * @see tts_unprepare()
 330 */
 331 int tts_prepare(tts_h tts);
 332
 333 /**
 334  * @brief Disconnects the daemon.
 335  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 336  *
 337  * @param[in] tts The TTS handle
 338  *
 339  * @return 0 on success, otherwise a negative error value
 340  * @retval #TTS_ERROR_NONE Successful
 341  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 343  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 344  *
 345  * @pre The state should be #TTS_STATE_READY.
 346  * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
 347  *
 348  * @see tts_prepare()
 349 */
 350 int tts_unprepare(tts_h tts);
 351
 352 /**
 353  * @brief Retrieves all supported voices of the current engine using callback function.
 354  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 355  *
 356  * @param[in] tts The TTS handle
 357  * @param[in] callback The callback function to invoke
 358  * @param[in] user_data The user data to be passed to the callback function
 359  *
 360  * @return 0 on success, otherwise a negative error value
 361  * @retval #TTS_ERROR_NONE Successful
 362  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 363  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 364  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 365  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 366  *
 367  * @post This function invokes tts_supported_voice_cb() repeatedly for getting voices.
 368  *
 369  * @see tts_get_default_voice()
 370 */
 371 int tts_foreach_supported_voices(tts_h tts, tts_supported_voice_cb callback, void* user_data);
 372
 373 /**
 374  * @brief Gets the default voice set by the user.
 375  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 376  *
 377  * @remarks If the function succeeds, @a language must be released with free().
 378  *
 379  * @param[in] tts The TTS handle
 380  * @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)
 381  * @param[out] voice_type The voice type
 382  *
 383  * @return 0 on success, otherwise a negative error value
 384  * @retval #TTS_ERROR_NONE Successful
 385  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 386  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 387  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 388  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 389  *
 390  * @see tts_foreach_supported_voices()
 391 */
 392 int tts_get_default_voice(tts_h tts, char** language, int* voice_type);
 393
 394 /**
 395  * @brief Sets the private data to tts engine.
 396  * @since_tizen 3.0
 397  *
 398  * @param[in] tts The TTS handle
 399  * @param[in] key The field name of private data
 400  * @param[in] data The data for set
 401  *
 402  * @return 0 on success, otherwise a negative error value
 403  * @retval #TTS_ERROR_NONE Successful
 404  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 405  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 406  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 407  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 408  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 409  *
 410  * @pre The state should be #TTS_STATE_READY.
 411  *
 412  * @see tts_get_private_data()
 413 */
 414 int tts_set_private_data(tts_h tts, const char* key, const char* data);
 415
 416 /**
 417  * @brief Gets the private data from tts engine.
 418  * @since_tizen 3.0
 419  *
 420  * @remarks data must be released using free() when it is no longer required.
 421  *
 422  * @param[in] tts The TTS handle
 423  * @param[in] key The field name of private data
 424  * @param[out] data The data
 425  *
 426  * @return 0 on success, otherwise a negative error value
 427  * @retval #TTS_ERROR_NONE Successful
 428  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 429  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 430  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 431  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 432  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 433  *
 434  * @pre The state should be #TTS_STATE_READY.
 435  *
 436  * @see tts_set_private_data()
 437 */
 438 int tts_get_private_data(tts_h tts, const char* key, char** data);
 439
 440 /**
 441  * @brief Gets the maximum byte size for text.
 442  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 443  *
 444  * @param[in] tts The TTS handle
 445  * @param[out] size The maximum byte size for text
 446  *
 447  * @return 0 on success, otherwise a negative error value
 448  * @retval #TTS_ERROR_NONE Successful
 449  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 450  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 451  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 452  *
 453  * @pre The state should be #TTS_STATE_READY.
 454  *
 455  * @see tts_add_text()
 456 */
 457 int tts_get_max_text_size(tts_h tts, unsigned int* size);
 458
 459 /**
 460  * @brief Gets the current state of TTS.
 461  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 462  *
 463  * @param[in] tts The TTS handle
 464  * @param[out] state The current state of TTS
 465  *
 466  * @return 0 on success, otherwise a negative error value
 467  * @retval #TTS_ERROR_NONE Successful
 468  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 469  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 470  *
 471  * @see tts_play()
 472  * @see tts_stop()
 473  * @see tts_pause()
 474 */
 475 int tts_get_state(tts_h tts, tts_state_e* state);
 476
 477 /**
 478  * @brief Gets the speed range.
 479  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 480  *
 481  * @param[in] tts The TTS handle
 482  * @param[out] min The minimun speed value
 483  * @param[out] normal The normal speed value
 484  * @param[out] max The maximum speed value
 485  *
 486  * @return 0 on success, otherwise a negative error value
 487  * @retval #TTS_ERROR_NONE Successful
 488  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 489  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 490  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 491  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 492  *
 493  * @pre The state should be #TTS_STATE_CREATED.
 494  *
 495  * @see tts_add_text()
 496 */
 497 int tts_get_speed_range(tts_h tts, int* min, int* normal, int* max);
 498
 499 /**
 500  * @brief Gets the current error message.
 501  * @since_tizen 3.0
 502  * @privlevel public
 503  * @remarks This function should be called during an tts error callback. If not, the error as operation failure will be returned. \n
 504  * If the function succeeds, @a err_msg must be released using free() when it is no longer required.
 505  *
 506  * @param[in] tts The TTS handle
 507  * @param[out] err_msg The current error message
 508  *
 509  * @return 0 on success, 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  *
 515  * @see tts_set_error_cb()
 516  * @see tts_unset_error_cb()
 517 */
 518 int tts_get_error_message(tts_h tts, char** err_msg);
 519
 520 /**
 521  * @brief Adds a text to the queue.
 522  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 523  *
 524  * @remarks Locale(e.g. setlocale()) MUST be set for utf8 text validation check.
 525  *
 526  * @param[in] tts The TTS handle
 527  * @param[in] text An input text based utf8
 528  * @param[in] language The language selected from the tts_foreach_supported_voices() (e.g. 'NULL'(Automatic), 'en_US')
 529  * @param[in] voice_type The voice type selected from the tts_foreach_supported_voices() (e.g. #TTS_VOICE_TYPE_AUTO, #TTS_VOICE_TYPE_FEMALE)
 530  * @param[in] speed A speaking speed (e.g. #TTS_SPEED_AUTO or the value from tts_get_speed_range())
 531  * @param[out] utt_id The utterance ID passed to the callback function
 532  *
 533  * @return 0 on success, otherwise a negative error value
 534  * @retval #TTS_ERROR_NONE Successful
 535  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 536  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 537  * @retval #TTS_ERROR_INVALID_VOICE Invalid voice about language, voice type
 538  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 539  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 540  * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
 541  *
 542  * @pre The state should be #TTS_STATE_READY, #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
 543  * @see tts_get_max_text_size()
 544  * @see tts_set_credential()
 545 */
 546 int tts_add_text(tts_h tts, const char* text, const char* language, int voice_type, int speed, int* utt_id);
 547
 548 /**
 549  * @brief Starts synthesizing voice from the text and plays the synthesized audio data.
 550  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 551  *
 552  * @param[in] tts The TTS handle
 553  *
 554  * @return 0 on success, otherwise a negative error value
 555  * @retval #TTS_ERROR_NONE Successful
 556  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 557  * @retval #TTS_ERROR_OUT_OF_NETWORK Out of network
 558  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 559  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 560  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 561  * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
 562  *
 563  * @pre The current state should be #TTS_STATE_READY or #TTS_STATE_PAUSED.
 564  * @post If this function succeeds, the TTS state will be #TTS_STATE_PLAYING.
 565  *
 566  * @see tts_add_text()
 567  * @see tts_pause()
 568  * @see tts_stop()
 569  * @see tts_utterance_started_cb()
 570  * @see tts_utterance_completed_cb()
 571  * @see tts_error_cb()
 572  * @see tts_set_credential()
 573 */
 574 int tts_play(tts_h tts);
 575
 576 /**
 577  * @brief Stops playing the utterance and clears the queue.
 578  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 579  *
 580  * @param[in] tts The TTS handle
 581  *
 582  * @return 0 on success, otherwise a negative error value
 583  * @retval #TTS_ERROR_NONE Successful
 584  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 585  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 586  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 587  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 588  *
 589  * @pre The TTS state should be #TTS_STATE_READY or #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
 590  * @post If this function succeeds, the TTS state will be #TTS_STATE_READY.
 591  *      This function will remove all text via tts_add_text() and synthesized sound data.
 592  *
 593  * @see tts_play()
 594  * @see tts_pause()
 595 */
 596 int tts_stop(tts_h tts);
 597
 598 /**
 599  * @brief Pauses the currently playing utterance.
 600  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 601  *
 602  * @param[in] tts The TTS handle
 603  *
 604  * @return 0 on success, otherwise a negative error value
 605  * @retval #TTS_ERROR_NONE Successful
 606  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 607  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 608  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 609  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 610  *
 611  * @pre The TTS state should be #TTS_STATE_PLAYING.
 612  * @post If this function succeeds, the TTS state will be #TTS_STATE_PAUSED.
 613  *
 614  * @see tts_play()
 615  * @see tts_stop()
 616  * @see tts_error_cb()
 617  * @see tts_interrupted_cb()
 618 */
 619 int tts_pause(tts_h tts);
 620
 621 /**
 622  * @brief Registers a callback function to be called when the TTS state changes.
 623  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 624  *
 625  * @param[in] tts The TTS handle
 626  * @param[in] callback The callback function to register
 627  * @param[in] user_data The user data to be passed to the callback function
 628  *
 629  * @return 0 on success, otherwise a negative error value
 630  * @retval #TTS_ERROR_NONE Successful
 631  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 632  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 633  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 634  *
 635  * @pre The state should be #TTS_STATE_CREATED.
 636  *
 637  * @see tts_state_changed_cb()
 638  * @see tts_unset_state_changed_cb()
 639 */
 640 int tts_set_state_changed_cb(tts_h tts, tts_state_changed_cb callback, void* user_data);
 641
 642 /**
 643  * @brief Unregisters the callback function.
 644  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 645  *
 646  * @param[in] tts The TTS handle
 647  *
 648  * @return 0 on success, otherwise a negative error value
 649  * @retval #TTS_ERROR_NONE Successful
 650  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 651  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 652  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 653  *
 654  * @pre The state should be #TTS_STATE_CREATED.
 655  *
 656  * @see tts_set_state_changed_cb()
 657 */
 658 int tts_unset_state_changed_cb(tts_h tts);
 659
 660 /**
 661  * @brief Registers a callback function to detect utterance start.
 662  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 663  *
 664  * @param[in] tts The TTS handle
 665  * @param[in] callback The callback function to register
 666  * @param[in] user_data The user data to be passed to the callback function
 667  *
 668  * @return 0 on success, otherwise a negative error value
 669  * @retval #TTS_ERROR_NONE Successful
 670  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 671  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 672  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 673  *
 674  * @pre The state should be #TTS_STATE_CREATED.
 675  *
 676  * @see tts_utterance_started_cb()
 677  * @see tts_unset_utterance_started_cb()
 678 */
 679 int tts_set_utterance_started_cb(tts_h tts, tts_utterance_started_cb callback, void* user_data);
 680
 681 /**
 682  * @brief Unregisters the callback function.
 683  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 684  *
 685  * @param[in] tts The TTS handle
 686  *
 687  * @return 0 on success, otherwise a negative error value
 688  * @retval #TTS_ERROR_NONE Successful
 689  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 690  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 691  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 692  *
 693  * @pre The state should be #TTS_STATE_CREATED.
 694  *
 695  * @see tts_set_utterance_started_cb()
 696 */
 697 int tts_unset_utterance_started_cb(tts_h tts);
 698
 699 /**
 700  * @brief Registers a callback function to detect utterance completion.
 701  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 702  *
 703  * @param[in] tts The TTS handle
 704  * @param[in] callback The callback function to register
 705  * @param[in] user_data The user data to be passed to the callback function
 706  *
 707  * @return 0 on success, otherwise a negative error value
 708  * @retval #TTS_ERROR_NONE Successful
 709  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 710  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 711  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 712  *
 713  * @pre The state should be #TTS_STATE_CREATED.
 714  *
 715  * @see tts_utterance_completed_cb()
 716  * @see tts_unset_utterance_completed_cb()
 717 */
 718 int tts_set_utterance_completed_cb(tts_h tts, tts_utterance_completed_cb callback, void* user_data);
 719
 720 /**
 721  * @brief Unregisters the callback function.
 722  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 723  *
 724  * @param[in] tts The TTS handle
 725  *
 726  * @return 0 on success, otherwise a negative error value
 727  * @retval #TTS_ERROR_NONE Successful
 728  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 729  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 730  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 731  *
 732  * @pre The state should be #TTS_STATE_CREATED.
 733  *
 734  * @see tts_set_utterance_completed_cb()
 735 */
 736 int tts_unset_utterance_completed_cb(tts_h tts);
 737
 738 /**
 739  * @brief Registers a callback function to detect errors.
 740  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 741  *
 742  * @param[in] tts The TTS handle
 743  * @param[in] callback The callback function to register
 744  * @param[in] user_data The user data to be passed to the callback function
 745  *
 746  * @return 0 on success, otherwise a negative error value
 747  * @retval #TTS_ERROR_NONE Successful
 748  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 749  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 750  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 751  *
 752  * @pre The state should be #TTS_STATE_CREATED.
 753  *
 754  * @see tts_error_cb()
 755  * @see tts_unset_error_cb()
 756 */
 757 int tts_set_error_cb(tts_h tts, tts_error_cb callback, void* user_data);
 758
 759 /**
 760  * @brief Unregisters the callback function.
 761  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 762  *
 763  * @param[in] tts The TTS handle
 764  *
 765  * @return 0 on success, otherwise a negative error value
 766  * @retval #TTS_ERROR_NONE Successful
 767  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 768  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 769  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 770  *
 771  * @pre The state should be #TTS_STATE_CREATED.
 772  *
 773  * @see tts_set_error_cb()
 774 */
 775 int tts_unset_error_cb(tts_h tts);
 776
 777 /**
 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  *
 781  * @param[in] tts The TTS handle
 782  * @param[in] callback The callback function to register
 783  * @param[in] user_data The user data to be passed to the callback function
 784  *
 785  * @return 0 on success, otherwise a negative error value
 786  * @retval #TTS_ERROR_NONE Successful
 787  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 788  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 789  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 790  *
 791  * @pre The state should be #TTS_STATE_CREATED.
 792  *
 793  * @see tts_default_voice_changed_cb()
 794  * @see tts_unset_default_voice_changed_cb()
 795 */
 796 int tts_set_default_voice_changed_cb(tts_h tts, tts_default_voice_changed_cb callback, void* user_data);
 797
 798 /**
 799  * @brief Unregisters the callback function.
 800  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 801  *
 802  * @param[in] tts The TTS handle
 803  *
 804  * @return 0 on success, otherwise a negative error value
 805  * @retval #TTS_ERROR_NONE Successful
 806  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 807  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 808  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 809  *
 810  * @pre The state should be #TTS_STATE_CREATED.
 811  *
 812  * @see tts_set_default_voice_changed_cb()
 813 */
 814 int tts_unset_default_voice_changed_cb(tts_h tts);
 815
 816
 817 #ifdef __cplusplus
 818 }
 819 #endif
 820
 821 /**
 822 * @}
 823 */
 824
 825 #endif  /* __TTS_H__ */