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 @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  55         TTS_ERROR_SERVICE_RESET         = TIZEN_ERROR_TTS | 0x07        /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  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  * @brief Called when the engine is changed.
 219  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 220  *
 221  * @param[in] tts The TTS handle
 222  * @param[in] engine_id Engine id
 223  * @param[in] language The default language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
 224  * @param[in] voice_type The default voice type
 225  * @param[in] need_credential The necessity of credential
 226  * @param[in] user_data The user data passed from the callback registration function
 227  *
 228  * @see tts_set_engine_changed_cb()
 229 */
 230 typedef void (*tts_engine_changed_cb)(tts_h tts, const char* engine_id, const char* language, int voice_type, bool need_credential, void* user_data);
 231
 232
 233 /**
 234  * @brief Creates a handle for TTS.
 235  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 236  *
 237  * @remarks If the function succeeds, @a tts handle must be released with tts_destroy().
 238  *
 239  * @param[out] tts The TTS handle
 240  *
 241  * @return 0 on success, otherwise a negative error value
 242  * @retval #TTS_ERROR_NONE Successful
 243  * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
 244  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 246  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 247  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 248  *
 249  * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
 250  *
 251  * @see tts_destroy()
 252 */
 253 int tts_create(tts_h* tts);
 254
 255 /**
 256  * @brief Destroys the handle and disconnects the daemon.
 257  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 258  *
 259  * @param[in] tts The TTS handle
 260  *
 261  * @return 0 on success, otherwise a negative error value
 262  * @retval #TTS_ERROR_NONE Successful
 263  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 265  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 266  *
 267  * @see tts_create()
 268 */
 269 int tts_destroy(tts_h tts);
 270
 271 /**
 272  * @brief Sets the TTS mode.
 273  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 274  *
 275  * @param[in] tts The TTS handle
 276  * @param[in] mode The mode
 277  *
 278  * @return 0 on success, otherwise a negative error value
 279  * @retval #TTS_ERROR_NONE Successful
 280  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 281  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 282  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 283  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 284  *
 285  * @pre The state should be #TTS_STATE_CREATED.
 286  *
 287  * @see tts_get_mode()
 288 */
 289 int tts_set_mode(tts_h tts, tts_mode_e mode);
 290
 291 /**
 292  * @brief Gets the TTS mode.
 293  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 294  *
 295  * @param[in] tts The TTS handle
 296  * @param[out] mode The mode
 297  *
 298  * @return 0 on success, otherwise a negative error value
 299  * @retval #TTS_ERROR_NONE Successful
 300  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 301  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 302  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 303  *
 304  * @pre The state should be #TTS_STATE_CREATED.
 305  *
 306  * @see tts_set_mode()
 307 */
 308 int tts_get_mode(tts_h tts, tts_mode_e* mode);
 309
 310 /**
 311  * @brief Sets the app credential.
 312  * @details Using this API, the application can set a credential.
 313  *  The credential is a key to verify the authorization about using the engine.
 314  *  If the application sets the credential, it will be able to use functions of the engine entirely.
 315  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 316  *
 317  * @remarks The necessity of the credential depends on the engine. In case of the engine which is basically embedded in Tizen, the credential is not necessary so far.
 318  *  However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
 319  *
 320  * @param[in] tts The TTS handle
 321  * @param[in] credential The app credential
 322  *
 323  * @return 0 on success, otherwise a negative error value
 324  * @retval #TTS_ERROR_NONE Success
 325  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 326  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 327  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 328  *
 329  * @pre The state should be #TTS_STATE_CREATED or #TTS_STATE_READY.
 330  *
 331  * @see tts_play()
 332 */
 333 int tts_set_credential(tts_h tts, const char* credential);
 334
 335 /**
 336  * @brief Connects the daemon asynchronously.
 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_CREATED.
 348  * @post If this function is successful, the TTS state will be #TTS_STATE_READY. \n
 349  *      If this function is failed, the error callback is called. (e.g. #TTS_ERROR_ENGINE_NOT_FOUND)
 350  *
 351  * @see tts_unprepare()
 352 */
 353 int tts_prepare(tts_h tts);
 354
 355 /**
 356  * @brief Disconnects the daemon.
 357  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 358  *
 359  * @param[in] tts The TTS handle
 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_INVALID_STATE Invalid state
 365  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 366  *
 367  * @pre The state should be #TTS_STATE_READY.
 368  * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
 369  *
 370  * @see tts_prepare()
 371 */
 372 int tts_unprepare(tts_h tts);
 373
 374 /**
 375  * @brief Retrieves all supported voices of the current engine using callback function.
 376  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 377  *
 378  * @param[in] tts The TTS handle
 379  * @param[in] callback The callback function to invoke
 380  * @param[in] user_data The user data to be passed to the callback function
 381  *
 382  * @return 0 on success, otherwise a negative error value
 383  * @retval #TTS_ERROR_NONE Successful
 384  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 385  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 386  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 387  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 388  *
 389  * @post This function invokes tts_supported_voice_cb() repeatedly for getting voices.
 390  *
 391  * @see tts_get_default_voice()
 392 */
 393 int tts_foreach_supported_voices(tts_h tts, tts_supported_voice_cb callback, void* user_data);
 394
 395 /**
 396  * @brief Gets the default voice set by the user.
 397  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 398  *
 399  * @remarks If the function succeeds, @a language must be released with free().
 400  *
 401  * @param[in] tts The TTS handle
 402  * @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)
 403  * @param[out] voice_type The voice type
 404  *
 405  * @return 0 on success, otherwise a negative error value
 406  * @retval #TTS_ERROR_NONE Successful
 407  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 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  * @see tts_foreach_supported_voices()
 413 */
 414 int tts_get_default_voice(tts_h tts, char** language, int* voice_type);
 415
 416 /**
 417  * @brief Sets the private data to tts engine.
 418  * @details The private data is the setting parameter for applying keys provided by the engine.
 419  *      Using this API, the application can set the private data and use the corresponding key of the engine.
 420  *      For example, if the engine provides 'girl's voice' as a voice type, the application can set the private data as the following. \n
 421  *      int ret = tts_set_private_data(tts_h, "voice_type", "GIRL");
 422  *
 423  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 424  *
 425  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 426  *
 427  * @param[in] tts The TTS handle
 428  * @param[in] key The field name of private data
 429  * @param[in] data The data for set
 430  *
 431  * @return 0 on success, otherwise a negative error value
 432  * @retval #TTS_ERROR_NONE Successful
 433  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 434  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 435  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 436  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 437  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 438  *
 439  * @pre The state should be #TTS_STATE_READY.
 440  *
 441  * @see tts_get_private_data()
 442 */
 443 int tts_set_private_data(tts_h tts, const char* key, const char* data);
 444
 445 /**
 446  * @brief Gets the private data from tts engine.
 447  * @details The private data is the information provided by the engine.
 448  *      Using this API, the application can get the private data which corresponds to the key from the engine.
 449  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 450  *
 451  * @remarks The @a data must be released using free() when it is no longer required.
 452  *      If the engine is replaced with the other engine, the key may be ignored.
 453  *
 454  * @param[in] tts The TTS handle
 455  * @param[in] key The field name of private data
 456  * @param[out] data The data field of private data
 457  *
 458  * @return 0 on success, otherwise a negative error value
 459  * @retval #TTS_ERROR_NONE Successful
 460  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 461  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 462  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
 463  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 464  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 465  *
 466  * @pre The state should be #TTS_STATE_READY.
 467  *
 468  * @see tts_set_private_data()
 469 */
 470 int tts_get_private_data(tts_h tts, const char* key, char** data);
 471
 472 /**
 473  * @brief Gets the maximum byte size for text.
 474  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 475  *
 476  * @param[in] tts The TTS handle
 477  * @param[out] size The maximum byte size for text
 478  *
 479  * @return 0 on success, otherwise a negative error value
 480  * @retval #TTS_ERROR_NONE Successful
 481  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 482  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 483  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 484  *
 485  * @pre The state should be #TTS_STATE_READY.
 486  *
 487  * @see tts_add_text()
 488 */
 489 int tts_get_max_text_size(tts_h tts, unsigned int* size);
 490
 491 /**
 492  * @brief Gets the current state of TTS.
 493  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 494  *
 495  * @param[in] tts The TTS handle
 496  * @param[out] state The current state of TTS
 497  *
 498  * @return 0 on success, otherwise a negative error value
 499  * @retval #TTS_ERROR_NONE Successful
 500  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 501  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 502  *
 503  * @see tts_play()
 504  * @see tts_stop()
 505  * @see tts_pause()
 506 */
 507 int tts_get_state(tts_h tts, tts_state_e* state);
 508
 509 /**
 510  * @brief Gets the speed range.
 511  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 512  *
 513  * @param[in] tts The TTS handle
 514  * @param[out] min The minimun speed value
 515  * @param[out] normal The normal speed value
 516  * @param[out] max The maximum speed value
 517  *
 518  * @return 0 on success, otherwise a negative error value
 519  * @retval #TTS_ERROR_NONE Successful
 520  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 521  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 522  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 523  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 524  *
 525  * @pre The state should be #TTS_STATE_CREATED.
 526  *
 527  * @see tts_add_text()
 528 */
 529 int tts_get_speed_range(tts_h tts, int* min, int* normal, int* max);
 530
 531 /**
 532  * @brief Gets the current error message.
 533  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 534  *
 535  * @remarks This function should be called from a tts error callback. Calling in any other context will result in an Operation failed error. \n
 536  *      A successful call will allocate @a err_msg, which must be released by calling free() when it is no longer required.
 537  *
 538  * @param[in] tts The TTS handle
 539  * @param[out] err_msg The current error message
 540  *
 541  * @return 0 on success, otherwise a negative error value
 542  * @retval #TTS_ERROR_NONE Successful
 543  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 544  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 545  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 546  *
 547  * @see tts_set_error_cb()
 548  * @see tts_unset_error_cb()
 549 */
 550 int tts_get_error_message(tts_h tts, char** err_msg);
 551
 552 /**
 553  * @brief Adds a text to the queue.
 554  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 555  *
 556  * @remarks Locale(e.g. setlocale()) MUST be set for utf8 text validation check.
 557  *
 558  * @param[in] tts The TTS handle
 559  * @param[in] text An input text based utf8
 560  * @param[in] language The language selected from the tts_foreach_supported_voices() (e.g. 'NULL'(Automatic), 'en_US')
 561  * @param[in] voice_type The voice type selected from the tts_foreach_supported_voices() (e.g. #TTS_VOICE_TYPE_AUTO, #TTS_VOICE_TYPE_FEMALE)
 562  * @param[in] speed A speaking speed (e.g. #TTS_SPEED_AUTO or the value from tts_get_speed_range())
 563  * @param[out] utt_id The utterance ID passed to the callback function
 564  *
 565  * @return 0 on success, otherwise a negative error value
 566  * @retval #TTS_ERROR_NONE Successful
 567  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 568  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 569  * @retval #TTS_ERROR_INVALID_VOICE Invalid voice about language, voice type
 570  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 571  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 572  * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
 573  *
 574  * @pre The state should be #TTS_STATE_READY, #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
 575  * @see tts_get_max_text_size()
 576  * @see tts_set_credential()
 577 */
 578 int tts_add_text(tts_h tts, const char* text, const char* language, int voice_type, int speed, int* utt_id);
 579
 580 /**
 581  * @brief Starts synthesizing voice from the text and plays the synthesized audio data.
 582  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 583  *
 584  * @param[in] tts The TTS handle
 585  *
 586  * @return 0 on success, otherwise a negative error value
 587  * @retval #TTS_ERROR_NONE Successful
 588  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 589  * @retval #TTS_ERROR_OUT_OF_NETWORK Out of network
 590  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 591  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 592  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 593  * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
 594  *
 595  * @pre The current state should be #TTS_STATE_READY or #TTS_STATE_PAUSED.
 596  * @post If this function succeeds, the TTS state will be #TTS_STATE_PLAYING.
 597  *
 598  * @see tts_add_text()
 599  * @see tts_pause()
 600  * @see tts_stop()
 601  * @see tts_utterance_started_cb()
 602  * @see tts_utterance_completed_cb()
 603  * @see tts_error_cb()
 604  * @see tts_set_credential()
 605 */
 606 int tts_play(tts_h tts);
 607
 608 /**
 609  * @brief Stops playing the utterance and clears the queue.
 610  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 611  *
 612  * @param[in] tts The TTS handle
 613  *
 614  * @return 0 on success, otherwise a negative error value
 615  * @retval #TTS_ERROR_NONE Successful
 616  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 617  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 618  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 619  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 620  *
 621  * @pre The TTS state should be #TTS_STATE_READY or #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
 622  * @post If this function succeeds, the TTS state will be #TTS_STATE_READY.
 623  *      This function will remove all text via tts_add_text() and synthesized sound data.
 624  *
 625  * @see tts_play()
 626  * @see tts_pause()
 627 */
 628 int tts_stop(tts_h tts);
 629
 630 /**
 631  * @brief Pauses the currently playing utterance.
 632  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 633  *
 634  * @param[in] tts The TTS handle
 635  *
 636  * @return 0 on success, otherwise a negative error value
 637  * @retval #TTS_ERROR_NONE Successful
 638  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 639  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 640  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 641  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 642  *
 643  * @pre The TTS state should be #TTS_STATE_PLAYING.
 644  * @post If this function succeeds, the TTS state will be #TTS_STATE_PAUSED.
 645  *
 646  * @see tts_play()
 647  * @see tts_stop()
 648  * @see tts_error_cb()
 649  * @see tts_interrupted_cb()
 650 */
 651 int tts_pause(tts_h tts);
 652
 653 /**
 654  * @brief Registers a callback function to be called when the TTS state changes.
 655  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 656  *
 657  * @param[in] tts The TTS handle
 658  * @param[in] callback The callback function to register
 659  * @param[in] user_data The user data to be passed to the callback function
 660  *
 661  * @return 0 on success, otherwise a negative error value
 662  * @retval #TTS_ERROR_NONE Successful
 663  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 664  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 665  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 666  *
 667  * @pre The state should be #TTS_STATE_CREATED.
 668  *
 669  * @see tts_state_changed_cb()
 670  * @see tts_unset_state_changed_cb()
 671 */
 672 int tts_set_state_changed_cb(tts_h tts, tts_state_changed_cb callback, void* user_data);
 673
 674 /**
 675  * @brief Unregisters the callback function.
 676  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 677  *
 678  * @param[in] tts The TTS handle
 679  *
 680  * @return 0 on success, otherwise a negative error value
 681  * @retval #TTS_ERROR_NONE Successful
 682  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 683  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 684  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 685  *
 686  * @pre The state should be #TTS_STATE_CREATED.
 687  *
 688  * @see tts_set_state_changed_cb()
 689 */
 690 int tts_unset_state_changed_cb(tts_h tts);
 691
 692 /**
 693  * @brief Registers a callback function to detect utterance start.
 694  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 695  *
 696  * @param[in] tts The TTS handle
 697  * @param[in] callback The callback function to register
 698  * @param[in] user_data The user data to be passed to the callback function
 699  *
 700  * @return 0 on success, otherwise a negative error value
 701  * @retval #TTS_ERROR_NONE Successful
 702  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 703  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 704  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 705  *
 706  * @pre The state should be #TTS_STATE_CREATED.
 707  *
 708  * @see tts_utterance_started_cb()
 709  * @see tts_unset_utterance_started_cb()
 710 */
 711 int tts_set_utterance_started_cb(tts_h tts, tts_utterance_started_cb callback, void* user_data);
 712
 713 /**
 714  * @brief Unregisters the callback function.
 715  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 716  *
 717  * @param[in] tts The TTS handle
 718  *
 719  * @return 0 on success, otherwise a negative error value
 720  * @retval #TTS_ERROR_NONE Successful
 721  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 722  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 723  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 724  *
 725  * @pre The state should be #TTS_STATE_CREATED.
 726  *
 727  * @see tts_set_utterance_started_cb()
 728 */
 729 int tts_unset_utterance_started_cb(tts_h tts);
 730
 731 /**
 732  * @brief Registers a callback function to detect utterance completion.
 733  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 734  *
 735  * @param[in] tts The TTS handle
 736  * @param[in] callback The callback function to register
 737  * @param[in] user_data The user data to be passed to the callback function
 738  *
 739  * @return 0 on success, otherwise a negative error value
 740  * @retval #TTS_ERROR_NONE Successful
 741  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 742  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 743  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 744  *
 745  * @pre The state should be #TTS_STATE_CREATED.
 746  *
 747  * @see tts_utterance_completed_cb()
 748  * @see tts_unset_utterance_completed_cb()
 749 */
 750 int tts_set_utterance_completed_cb(tts_h tts, tts_utterance_completed_cb callback, void* user_data);
 751
 752 /**
 753  * @brief Unregisters the callback function.
 754  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 755  *
 756  * @param[in] tts The TTS handle
 757  *
 758  * @return 0 on success, otherwise a negative error value
 759  * @retval #TTS_ERROR_NONE Successful
 760  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 761  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 762  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 763  *
 764  * @pre The state should be #TTS_STATE_CREATED.
 765  *
 766  * @see tts_set_utterance_completed_cb()
 767 */
 768 int tts_unset_utterance_completed_cb(tts_h tts);
 769
 770 /**
 771  * @brief Registers a callback function to detect errors.
 772  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 773  *
 774  * @param[in] tts The TTS handle
 775  * @param[in] callback The callback function to register
 776  * @param[in] user_data The user data to be passed to the callback function
 777  *
 778  * @return 0 on success, otherwise a negative error value
 779  * @retval #TTS_ERROR_NONE Successful
 780  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 781  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 782  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 783  *
 784  * @pre The state should be #TTS_STATE_CREATED.
 785  *
 786  * @see tts_error_cb()
 787  * @see tts_unset_error_cb()
 788 */
 789 int tts_set_error_cb(tts_h tts, tts_error_cb callback, void* user_data);
 790
 791 /**
 792  * @brief Unregisters the callback function.
 793  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 794  *
 795  * @param[in] tts The TTS handle
 796  *
 797  * @return 0 on success, otherwise a negative error value
 798  * @retval #TTS_ERROR_NONE Successful
 799  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 800  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 801  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 802  *
 803  * @pre The state should be #TTS_STATE_CREATED.
 804  *
 805  * @see tts_set_error_cb()
 806 */
 807 int tts_unset_error_cb(tts_h tts);
 808
 809 /**
 810  * @brief Registers a callback function to detect default voice change.
 811  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 812  *
 813  * @param[in] tts The TTS handle
 814  * @param[in] callback The callback function to register
 815  * @param[in] user_data The user data to be passed to the callback function
 816  *
 817  * @return 0 on success, otherwise a negative error value
 818  * @retval #TTS_ERROR_NONE Successful
 819  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 820  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 821  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 822  *
 823  * @pre The state should be #TTS_STATE_CREATED.
 824  *
 825  * @see tts_default_voice_changed_cb()
 826  * @see tts_unset_default_voice_changed_cb()
 827 */
 828 int tts_set_default_voice_changed_cb(tts_h tts, tts_default_voice_changed_cb callback, void* user_data);
 829
 830 /**
 831  * @brief Unregisters the callback function.
 832  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 833  *
 834  * @param[in] tts The TTS handle
 835  *
 836  * @return 0 on success, otherwise a negative error value
 837  * @retval #TTS_ERROR_NONE Successful
 838  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 839  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 840  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 841  *
 842  * @pre The state should be #TTS_STATE_CREATED.
 843  *
 844  * @see tts_set_default_voice_changed_cb()
 845 */
 846 int tts_unset_default_voice_changed_cb(tts_h tts);
 847
 848  /**
 849  * @brief Registers a callback function to detect the engine change.
 850  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 851  *
 852  * @param[in] tts The TTS handle
 853  * @param[in] callback The callback function to register
 854  * @param[in] user_data The user data to be passed to the callback function
 855  *
 856  * @return 0 on success, otherwise a negative error value
 857  * @retval #TTS_ERROR_NONE Successful
 858  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 859  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 860  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 861  *
 862  * @pre The state should be #TTS_STATE_CREATED.
 863  *
 864  * @see tts_engine_changed_cb()
 865  * @see tts_unset_engine_changed_cb()
 866 */
 867 int tts_set_engine_changed_cb(tts_h tts, tts_engine_changed_cb callback, void* user_data);
 868
 869 /**
 870  * @brief Unregisters the callback function.
 871  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 872  *
 873  * @param[in] tts The TTS handle
 874  *
 875  * @return 0 on success, otherwise a negative error value
 876  * @retval #TTS_ERROR_NONE Successful
 877  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 878  * @retval #TTS_ERROR_INVALID_STATE Invalid state
 879  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
 880  *
 881  * @pre The state should be #TTS_STATE_CREATED.
 882  *
 883  * @see tts_set_engine_changed_cb()
 884 */
 885 int tts_unset_engine_changed_cb(tts_h tts);
 886
 887
 888 #ifdef __cplusplus
 889 }
 890 #endif
 891
 892 /**
 893  * @}@}
 894  */
 895
 896 #endif  /* __TTS_H__ */