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