include/tts.h

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