include/tts.h

   1 /*
   2  * Copyright (c) 2011 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 __TIZEN_UIX_TTS_H__
  19 #define __TIZEN_UIX_TTS_H__
  20
  21 #include <tizen.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @addtogroup CAPI_UIX_TTS_MODULE
  29  * @{
  30  */
  31
  32 /**
  33 * @brief Enumerations of error codes.
  34 */
  35 typedef enum {
  36         TTS_ERROR_NONE                  = TIZEN_ERROR_NONE,             /**< Successful */
  37         TTS_ERROR_OUT_OF_MEMORY         = TIZEN_ERROR_OUT_OF_MEMORY,    /**< Out of memory */
  38         TTS_ERROR_IO_ERROR              = TIZEN_ERROR_IO_ERROR,         /**< I/O error */
  39         TTS_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
  40         TTS_ERROR_OUT_OF_NETWORK        = TIZEN_ERROR_NETWORK_DOWN,     /**< Out of network */
  41         TTS_ERROR_INVALID_STATE         = TIZEN_ERROR_UIX_CLASS | 0x21, /**< Invalid state */
  42         TTS_ERROR_INVALID_VOICE         = TIZEN_ERROR_UIX_CLASS | 0x22, /**< Invalid voice */
  43         TTS_ERROR_ENGINE_NOT_FOUND      = TIZEN_ERROR_UIX_CLASS | 0x23, /**< No available TTS-engine  */
  44         TTS_ERROR_TIMED_OUT             = TIZEN_ERROR_UIX_CLASS | 0x24, /**< No answer from TTS daemon */
  45         TTS_ERROR_OPERATION_FAILED      = TIZEN_ERROR_UIX_CLASS | 0x25, /**< TTS daemon failed  */
  46 } tts_error_e;
  47
  48 /**
  49 * @brief Enumerations of speaking speed.
  50 */
  51 typedef enum {
  52         TTS_SPEED_AUTO,                 /**< Speed from settings */
  53         TTS_SPEED_VERY_SLOW,            /**< Very slow */
  54         TTS_SPEED_SLOW,                 /**< Slow */
  55         TTS_SPEED_NORMAL,               /**< Normal */
  56         TTS_SPEED_FAST,                 /**< Fast */
  57         TTS_SPEED_VERY_FAST             /**< Very fast */
  58 } tts_speed_e;
  59
  60 /**
  61 * @brief Enumerations of voice type.
  62 */
  63 typedef enum {
  64         TTS_VOICE_TYPE_AUTO,            /**< Voice type from settings or auto selection based language */
  65         TTS_VOICE_TYPE_MALE,            /**< Male */
  66         TTS_VOICE_TYPE_FEMALE,          /**< Female */
  67         TTS_VOICE_TYPE_CHILD,           /**< Child */
  68         TTS_VOICE_TYPE_USER1,           /**< Engine defined */
  69         TTS_VOICE_TYPE_USER2,           /**< Engine defined */
  70         TTS_VOICE_TYPE_USER3            /**< Engine defined */
  71 } tts_voice_type_e;
  72
  73 /**
  74 * @brief Enumerations of state.
  75 */
  76 typedef enum {
  77         TTS_STATE_CREATED = 0,          /**< 'CREATED' state */
  78         TTS_STATE_READY,                /**< 'READY' state */
  79         TTS_STATE_PLAYING,              /**< 'PLAYING' state */
  80         TTS_STATE_PAUSED                /**< 'PAUSED' state*/
  81 }tts_state_e;
  82
  83 /**
  84 * @brief A structure of handle for identification
  85 */
  86 typedef struct tts_s *tts_h;
  87
  88 /**
  89 * @brief Called when the state of TTS is changed.
  90 *
  91 * @details If the daemon must stop player because of changing engine and
  92 *       the daemon must pause player because of other requests, this callback function is called.
  93 *
  94 * @param[in] tts The handle for TTS
  95 * @param[in] previous A previous state
  96 * @param[in] current A current state
  97 * @param[in] user_data The user data passed from the callback registration function.
  98 *
  99 * @pre An application registers this callback using tts_set_state_changed_cb() to detect changing state.
 100 *
 101 * @see tts_set_state_changed_cb()
 102 * @see tts_unset_state_changed_cb()
 103 */
 104 typedef void (*tts_state_changed_cb)(tts_h tts, tts_state_e previous, tts_state_e current, void* user_data);
 105
 106 /**
 107 * @brief Called when utterance has started.
 108 *
 109 * @param[in] tts The handle for TTS
 110 * @param[in] utt_id The utterance ID passed from the add text function
 111 * @param[in] user_data The user data passed from the callback registration function
 112 *
 113 * @pre An application registers this callback using tts_set_utterance_started_cb() to detect utterance started.
 114 *
 115 * @see tts_add_text()
 116 * @see tts_set_utterance_started_cb()
 117 * @see tts_unset_utterance_started_cb()
 118 */
 119 typedef void (*tts_utterance_started_cb)(tts_h tts, int utt_id, void* user_data);
 120
 121 /**
 122 * @brief Called when utterance is finished.
 123 *
 124 * @param[in] tts The handle for TTS
 125 * @param[in] utt_id The utterance ID passed from the add text function
 126 * @param[in] user_data The user data passed from from the callback registration function
 127 *
 128 * @pre An application registers this callback using tts_set_utterance_completed_cb() to detect utterance completed.
 129 *
 130 * @see tts_add_text()
 131 * @see tts_set_utterance_completed_cb()
 132 * @see tts_unset_utterance_completed_cb()
 133 */
 134 typedef void (*tts_utterance_completed_cb)(tts_h tts, int utt_id, void *user_data);
 135
 136 /**
 137 * @brief Called when error occurred.
 138 *
 139 * @param[in] tts The handle for TTS
 140 * @param[in] utt_id The utterance ID passed from the add text function
 141 * @param[in] reason The error code
 142 * @param[in] user_data The user data passed from the callback registration function
 143 *
 144 * @pre An application registers this callback using tts_set_error_cb() to detect error.
 145 *
 146 * @see tts_play()
 147 * @see tts_pause()
 148 * @see tts_stop()
 149 * @see tts_set_error_cb()
 150 * @see tts_unset_error_cb()
 151 */
 152 typedef void (*tts_error_cb)(tts_h tts, int utt_id, tts_error_e reason, void* user_data);
 153
 154 /**
 155 * @brief Called to retrieve the supported voice.
 156 *
 157 * @param[in] tts The handle for TTS
 158 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 159 *                       followed by ISO 639-1 for the two-letter language code. \n
 160 *                       For example, "ko_KR" for Korean, "en_US" for American English
 161 * @param[in] voice_type A voice type
 162 * @param[in] user_data The user data passed from the foreach function
 163 *
 164 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 165 * @pre tts_foreach_supported_voices() will invoke this callback.
 166 *
 167 * @see tts_foreach_supported_voices()
 168 */
 169 typedef bool(*tts_supported_voice_cb)(tts_h tts, const char* language, tts_voice_type_e voice_type, void* user_data);
 170
 171
 172 /**
 173 * @brief Creates a handle for TTS.
 174 *
 175 * @param[out] tts The handle for TTS
 176 *
 177 * @return 0 on success, otherwise a negative error value
 178 * @retval #TTS_ERROR_NONE Successful
 179 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 180 *
 181 * @see tts_destroy()
 182 */
 183 int tts_create(tts_h* tts);
 184
 185 /**
 186 * @brief Destroys the handle and disconnects the daemon.
 187 *
 188 * @param[in] tts The handle for TTS
 189 *
 190 * @return 0 on success, otherwise a negative error value
 191 * @retval #TTS_ERROR_NONE Successful
 192 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 193 *
 194 * @see tts_create()
 195 */
 196 int tts_destroy(tts_h tts);
 197
 198 /**
 199 * @brief Connects the daemon asynchronously.
 200 *
 201 * @param[in] tts The handle for TTS
 202 *
 203 * @return 0 on success, otherwise a negative error value
 204 * @retval #TTS_ERROR_NONE Successful
 205 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 206 * @retval #TTS_ERROR_INVALID_STATE Invalid state
 207 *
 208 * @pre The state should be #TTS_STATE_CREATED.
 209 * @post If this function is called, the TTS state will be #TTS_STATE_READY.
 210 *
 211 * @see tts_unprepare()
 212 */
 213 int tts_prepare(tts_h tts);
 214
 215 /**
 216 * @brief Disconnects the daemon.
 217 *
 218 * @param[in] tts The handle for TTS
 219 *
 220 * @return 0 on success, otherwise a negative error value
 221 * @retval #TTS_ERROR_NONE Successful
 222 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 223 * @retval #STT_ERROR_INVALID_STATE Invalid state
 224 *
 225 * @pre The state should be #TTS_STATE_READY.
 226 * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
 227 *
 228 * @see tts_prepare()
 229 */
 230 int tts_unprepare(tts_h tts);
 231
 232 /**
 233 * @brief Retrieves all supported voices of the current engine using callback function.
 234 *
 235 * @param[in] tts The handle for TTS
 236 * @param[in] callback The callback function to invoke
 237 * @param[in] user_data The user data to be passed to the callback function
 238 *
 239 * @return 0 on success, otherwise a negative error value
 240 * @retval #TTS_ERROR_NONE Successful
 241 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 242 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 243 *
 244 * @pre The state should be #TTS_STATE_READY.
 245 * @post This function invokes tts_supported_voice_cb() repeatedly for getting voices.
 246 *
 247 * @see tts_get_default_voice()
 248 */
 249 int tts_foreach_supported_voices(tts_h tts, tts_supported_voice_cb callback, void* user_data);
 250
 251 /**
 252 * @brief Gets the default voice set by user.
 253 *
 254 * @remark If the function succeeds, @a language must be released with free() by you.
 255 *
 256 * @param[in] tts The handle for TTS
 257 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 258 *                       followed by ISO 639-1 for the two-letter language code. \n
 259 *                       For example, "ko_KR" for Korean, "en_US" for American English.
 260 * @param[out] voice_type The voice type
 261 *
 262 * @return 0 on success, otherwise a negative error value.
 263 * @retval #TTS_ERROR_NONE Successful
 264 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 265 * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
 266 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 267 *
 268 * @pre The state should be #TTS_STATE_READY.
 269 *
 270 * @see tts_foreach_supported_voices()
 271 */
 272 int tts_get_default_voice(tts_h tts, char** language, tts_voice_type_e* voice_type);
 273
 274 /**
 275 * @brief Gets the maximum text count of a current engine.
 276 *
 277 * @param[in] tts The handle for TTS
 278 * @param[out] count The maximum text count of the current engine
 279 *
 280 * @return 0 on success, otherwise a negative error value
 281 * @retval #TTS_ERROR_NONE Successful
 282 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 283 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 284 *
 285 * @pre The state should be #TTS_STATE_READY.
 286 *
 287 * @see tts_add_text()
 288 */
 289 int tts_get_max_text_count(tts_h tts, int* count);
 290
 291 /**
 292 * @brief Gets the current state of tts.
 293 *
 294 * @param[in] tts The handle for TTS
 295 * @param[out] state The current state of TTS
 296 *
 297 * @return 0 on success, otherwise a negative error value
 298 * @retval #TTS_ERROR_NONE Successful
 299 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 300 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 301 *
 302 * @see tts_play()
 303 * @see tts_stop()
 304 * @see tts_pause()
 305 */
 306 int tts_get_state(tts_h tts, tts_state_e* state);
 307
 308 /**
 309 * @brief Adds a text to the queue.
 310 *
 311 * @param[in] tts The handle for TTS
 312 * @param[in] text A input text
 313 * @param[in] language The language selected from the foreach function
 314 * @param[in] voice_type The voice type selected from the foreach function
 315 * @param[in] speed A speaking speed
 316 * @param[out] utt_id The utterance ID passed to the callback function
 317 *
 318 * @return 0 on success, otherwise a negative error value
 319 * @retval #TTS_ERROR_NONE Successful
 320 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 321 * @retval #TTS_ERROR_INVALID_VOICE Invalid voice about language, voice type
 322 * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
 323 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 324 *
 325 * @pre The state should be #TTS_STATE_READY, #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
 326 * @see tts_get_max_text_count()
 327 */
 328 int tts_add_text(tts_h tts, const char* text, const char* language, tts_voice_type_e voice_type, tts_speed_e speed, int* utt_id);
 329
 330 /**
 331 * @brief Starts synthesizing voice from text and plays synthesized audio data.
 332 *
 333 * @param[in] tts The handle for TTS
 334 *
 335 * @return 0 on success, otherwise a negative error value
 336 * @retval #TTS_ERROR_NONE Successful
 337 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 338 * @retval #TTS_ERROR_INVALID_STATE Invalid state
 339 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 340 *
 341 * @pre The current state should be #TTS_STATE_READY or #TTS_STATE_PAUSED.
 342 * @post If this function succeeds, the TTS state will be #TTS_STATE_PLAYING.
 343 *
 344 * @see tts_add_text()
 345 * @see tts_pause()
 346 * @see tts_stop()
 347 * @see tts_utterance_started_cb()
 348 * @see tts_utterance_completed_cb()
 349 * @see tts_error_cb()
 350 * @see tts_interrupted_cb()
 351 */
 352 int tts_play(tts_h tts);
 353
 354 /**
 355 * @brief Stops playing utterance and clears queue.
 356 *
 357 * @param[in] tts The handle for TTS
 358 *
 359 * @return 0 on success, otherwise a negative error value
 360 * @retval #TTS_ERROR_NONE Successful
 361 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 362 * @retval #TTS_ERROR_INVALID_STATE Invalid state
 363 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 364 *
 365 * @pre The TTS state should be #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
 366 * @post If this function succeeds, the TTS state will be #TTS_STATE_READY.
 367 *       This function will remove all text via tts_add_text() and synthesized sound data.
 368 *
 369 * @see tts_play()
 370 * @see tts_pause()
 371 */
 372 int tts_stop(tts_h tts);
 373
 374 /**
 375 * @brief Pauses currently playing utterance.
 376 *
 377 * @param[in] tts The handle for TTS
 378 *
 379 * @return 0 on success, otherwise a negative error value
 380 * @retval #TTS_ERROR_NONE Successful
 381 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 382 * @retval #TTS_ERROR_INVALID_STATE Invalid state
 383 * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
 384 *
 385 * @pre The TTS state should be #TTS_STATE_PLAYING.
 386 * @post If this function succeeds, the TTS state will be #TTS_STATE_PAUSED.
 387 *
 388 * @see tts_play()
 389 * @see tts_stop()
 390 * @see tts_error_cb()
 391 * @see tts_interrupted_cb()
 392 */
 393 int tts_pause(tts_h tts);
 394
 395 /**
 396 * @brief Registers a callback function to be called when TTS state changes.
 397 *
 398 * @param[in] tts The handle for TTS
 399 * @param[in] callback The callback function to register
 400 * @param[in] user_data The user data to be passed to the callback function
 401 *
 402 * @return 0 on success, otherwise a negative error value
 403 * @retval #TTS_ERROR_NONE Successful
 404 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 405 *
 406 * @pre The state should be #TTS_STATE_CREATED.
 407 *
 408 * @see tts_state_changed_cb()
 409 * @see tts_unset_state_changed_cb()
 410 */
 411 int tts_set_state_changed_cb(tts_h tts, tts_state_changed_cb callback, void* user_data);
 412
 413 /**
 414 * @brief Unregisters the callback function.
 415 *
 416 * @param[in] tts The handle for TTS
 417 *
 418 * @return 0 on success, otherwise a negative error value
 419 * @retval #TTS_ERROR_NONE Successful
 420 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 421 *
 422 * @pre The state should be #TTS_STATE_CREATED.
 423 *
 424 * @see tts_set_state_changed_cb()
 425 */
 426 int tts_unset_state_changed_cb(tts_h tts);
 427
 428 /**
 429 * @brief Registers a callback function for detecting utterance started.
 430 *
 431 * @param[in] tts The handle for TTS
 432 * @param[in] callback The callback function to register
 433 * @param[in] user_data The user data to be passed to the callback function
 434 *
 435 * @return 0 on success, otherwise a negative error value
 436 * @retval #TTS_ERROR_NONE Successful
 437 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 438 *
 439 * @pre The state should be #TTS_STATE_CREATED.
 440 *
 441 * @see tts_utterance_started_cb()
 442 * @see tts_unset_utterance_started_cb()
 443 */
 444 int tts_set_utterance_started_cb(tts_h tts, tts_utterance_started_cb callback, void* user_data);
 445
 446 /**
 447 * @brief Unregisters the callback function.
 448 *
 449 * @param[in] tts The handle for TTS
 450 *
 451 * @return 0 on success, otherwise a negative error value
 452 * @retval #TTS_ERROR_NONE Successful
 453 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 454 *
 455 * @pre The state should be #TTS_STATE_CREATED.
 456 *
 457 * @see tts_set_utterance_started_cb()
 458 */
 459 int tts_unset_utterance_started_cb(tts_h tts);
 460
 461 /**
 462 * @brief Registers a callback function for detecting utterance completed.
 463 *
 464 * @param[in] tts The handle for TTS
 465 * @param[in] callback The callback function to register
 466 * @param[in] user_data The user data to be passed to the callback function
 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 *
 472 * @pre The state should be #TTS_STATE_CREATED.
 473 *
 474 * @see tts_utterance_completed_cb()
 475 * @see tts_unset_utterance_completed_cb()
 476 */
 477 int tts_set_utterance_completed_cb(tts_h tts, tts_utterance_completed_cb callback, void* user_data);
 478
 479 /**
 480 * @brief Unregisters the callback function.
 481 *
 482 * @param[in] tts The handle for TTS
 483 *
 484 * @return 0 on success, otherwise a negative error value
 485 * @retval #TTS_ERROR_NONE Successful
 486 * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
 487 *
 488 * @pre The state should be #TTS_STATE_CREATED.
 489 *
 490 * @see tts_set_utterance_completed_cb()
 491 */
 492 int tts_unset_utterance_completed_cb(tts_h tts);
 493
 494 /**
 495 * @brief Registers a callback function for detecting error.
 496 *
 497 * @param[in] tts The handle for TTS
 498 * @param[in] callback The callback function to register
 499 * @param[in] user_data The user data to be passed to the callback function
 500 *
 501 * @return 0 on success, otherwise a negative error value
 502 * @retval #TTS_ERROR_NONE Successful
 503 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 504 *
 505 * @pre The state should be #TTS_STATE_CREATED.
 506 *
 507 * @see tts_error_cb()
 508 * @see tts_unset_error_cb()
 509 */
 510 int tts_set_error_cb(tts_h tts, tts_error_cb callback, void* user_data);
 511
 512 /**
 513 * @brief Unregisters the callback function.
 514 *
 515 * @param[in] tts The handle for TTS
 516 *
 517 * @return 0 on success, otherwise a negative error value
 518 * @retval #TTS_ERROR_NONE Successful
 519 * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
 520 *
 521 * @pre The state should be #TTS_STATE_CREATED.
 522 *
 523 * @see tts_set_error_cb()
 524 */
 525 int tts_unset_error_cb(tts_h tts);
 526
 527
 528 #ifdef __cplusplus
 529 }
 530 #endif
 531
 532 /**
 533 * @}
 534 */
 535 #endif  /* __TIZEN_UIX_TTS_H__ */