server/ttsp.h

   1 /*
   2 *  Copyright (c) 2011-2014 Samsung Electronics Co., Ltd All Rights Reserved
   3 *  Licensed under the Apache License, Version 2.0 (the "License");
   4 *  you may not use this file except in compliance with the License.
   5 *  You may obtain a copy of the License at
   6 *  http://www.apache.org/licenses/LICENSE-2.0
   7 *  Unless required by applicable law or agreed to in writing, software
   8 *  distributed under the License is distributed on an "AS IS" BASIS,
   9 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  10 *  See the License for the specific language governing permissions and
  11 *  limitations under the License.
  12 */
  13
  14
  15 #ifndef __TTSP_H__
  16 #define __TTSP_H__
  17
  18 #include <errno.h>
  19 #include <stdbool.h>
  20
  21 /**
  22 * @addtogroup TTS_ENGINE_MODULE
  23 * @{
  24 */
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31 * @brief Enumerations of error codes.
  32 */
  33 typedef enum {
  34         TTSP_ERROR_NONE                 = 0,            /**< Successful */
  35         TTSP_ERROR_OUT_OF_MEMORY        = -ENOMEM,      /**< Out of Memory */
  36         TTSP_ERROR_IO_ERROR             = -EIO,         /**< I/O error */
  37         TTSP_ERROR_INVALID_PARAMETER    = -EINVAL,      /**< Invalid parameter */
  38         TTSP_ERROR_OUT_OF_NETWORK       = -ENETDOWN,    /**< Out of network */
  39         TTSP_ERROR_INVALID_STATE        = -0x0100021,   /**< Invalid state */
  40         TTSP_ERROR_INVALID_VOICE        = -0x0100022,   /**< Invalid voice */
  41         TTSP_ERROR_OPERATION_FAILED     = -0x0100025    /**< Operation failed */
  42 } ttsp_error_e;
  43
  44 /**
  45 * @brief Enumerations of audio type.
  46 */
  47 typedef enum {
  48         TTSP_AUDIO_TYPE_RAW_S16 = 0,    /**< Signed 16-bit audio sample */
  49         TTSP_AUDIO_TYPE_RAW_U8,         /**< Unsigned 8-bit audio sample */
  50         TTSP_AUDIO_TYPE_MAX
  51 } ttsp_audio_type_e;
  52
  53 /**
  54 * @brief Enumerations of result event type.
  55 */
  56 typedef enum {
  57         TTSP_RESULT_EVENT_FAIL          = -1, /**< event when the voice synthesis is failed */
  58         TTSP_RESULT_EVENT_START         = 1,  /**< event when the sound data is first data by callback function */
  59         TTSP_RESULT_EVENT_CONTINUE      = 2,  /**< event when the next sound data exist, not first and not last */
  60         TTSP_RESULT_EVENT_FINISH        = 3   /**< event when the sound data is last data or sound data is only one result */
  61 } ttsp_result_event_e;
  62
  63 /**
  64 * @brief Enumerations of TTS mode.
  65 */
  66 typedef enum {
  67         TTSP_MODE_DEFAULT       = 0,    /**< Default mode for normal application */
  68         TTSP_MODE_NOTIFICATION  = 1,    /**< Notification mode */
  69         TTSP_MODE_SCREEN_READER = 2     /**< Accessibiliity mode */
  70 } ttsp_mode_e;
  71
  72 /**
  73 * @brief Defines of voice type.
  74 */
  75 #define TTSP_VOICE_TYPE_MALE    1
  76 #define TTSP_VOICE_TYPE_FEMALE  2
  77 #define TTSP_VOICE_TYPE_CHILD   3
  78
  79 /**
  80 * @brief Called when the daemon gets synthesized result.
  81 *
  82 * @param[in] event A result event
  83 * @param[in] data Result data
  84 * @param[in] data_size Result data size
  85 * @param[in] audio_type A audio type
  86 * @param[in] rate A sample rate
  87 * @param[in] user_data The user data passed from the start synthesis function
  88 *
  89 * @return @c true to continue with the next iteration of synthesis \n @c false to stop
  90 *
  91 * @pre ttspe_start_synthesis() will invoke this callback.
  92 *
  93 * @see ttspe_start_synthesis()
  94 */
  95 typedef bool (*ttspe_result_cb)(ttsp_result_event_e event, const void* data, unsigned int data_size,
  96                         ttsp_audio_type_e audio_type, int rate, void *user_data);
  97
  98 /**
  99 * @brief Called when the daemon gets a language and a voice type.
 100 *
 101 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 102 *               followed by ISO 639-1 for the two-letter language code. \n
 103 *               For example, "ko_KR" for Korean, "en_US" for American English.
 104 * @param[in] type A voice type
 105 * @param[in] user_data The user data passed from the the foreach function
 106 *
 107 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 108 *
 109 * @pre ttspe_foreach_supported_voices() will invoke this callback.
 110 *
 111 * @see ttspe_foreach_supported_voices()
 112 */
 113 typedef bool (*ttspe_supported_voice_cb)(const char* language, int type, void* user_data);
 114
 115 /**
 116 * @brief Initializes the engine.
 117 *
 118 * @param[in] callbacks A callback function
 119 *
 120 * @return 0 on success, otherwise a negative error value
 121 * @retval #TTSP_ERROR_NONE Successful
 122 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 123 * @retval #TTSP_ERROR_INVALID_STATE Already initialized
 124 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 125 *
 126 * @see ttspe_deinitialize()
 127 */
 128 typedef int (*ttspe_initialize)(ttspe_result_cb callback);
 129
 130 /**
 131 * @brief Deinitializes the engine.
 132 *
 133 * @return 0 on success, otherwise a negative error value
 134 * @retval #TTSP_ERROR_NONE Successful
 135 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 136 *
 137 * @see ttspe_initialize()
 138 */
 139 typedef int (*ttspe_deinitialize)(void);
 140
 141 /**
 142 * @brief Retrieves all supported voices of the engine using callback function.
 143 *
 144 * @param[in] callback A callback function
 145 * @param[in] user_data The user data to be passed to the callback function
 146 *
 147 * @return 0 on success, otherwise a negative error value
 148 * @retval #TTSP_ERROR_NONE Successful
 149 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 150 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 151 *
 152 * @post This function invokes ttspe_supported_voice_cb() repeatedly for getting all supported languages.
 153 *
 154 * @see ttspe_supported_voice_cb()
 155 */
 156 typedef int (*ttspe_foreach_supported_voices)(ttspe_supported_voice_cb callback, void* user_data);
 157
 158 /**
 159 * @brief Checks whether the voice is valid or not.
 160 *
 161 * @param[in] language A language
 162 * @param[in] type A voice type
 163 *
 164 * @return @c true to be valid \n @c false not to be valid
 165 *
 166 * @see ttspe_foreach_supported_voices()
 167 */
 168 typedef bool (*ttspe_is_valid_voice)(const char* language, int type);
 169
 170 /**
 171 * @brief Sets default pitch.
 172 *
 173 * @param[in] pitch default pitch
 174 *
 175 * @return 0 on success, otherwise a negative error value
 176 * @retval #TTSP_ERROR_NONE Successful
 177 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 178 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 179 * @retval #TTSP_ERROR_OPERATION_FAILED Fail
 180 */
 181 typedef int (*ttspe_set_pitch)(int pitch);
 182
 183 /**
 184 * @brief Load voice of the engine.
 185 *
 186 * @param[in] language language
 187 * @param[in] type voice type
 188 *
 189 * @return 0 on success, otherwise a negative error value
 190 * @retval #TTSP_ERROR_NONE Successful
 191 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 192 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 193 * @retval #TTSP_ERROR_OUT_OF_MEMORY Out of memory
 194 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
 195 * @retval #TTSP_ERROR_OPERATION_FAILED Fail
 196 *
 197 * @see ttspe_unload_voice()
 198 */
 199 typedef int (*ttspe_load_voice)(const char* language, int type);
 200
 201 /**
 202 * @brief Unload voice of the engine.
 203 *
 204 * @param[in] language language
 205 * @param[in] type voice type
 206 *
 207 * @return 0 on success, otherwise a negative error value
 208 * @retval #TTSP_ERROR_NONE Successful
 209 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 210 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 211 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
 212 * @retval #TTSP_ERROR_OPERATION_FAILED Fail
 213 *
 214 * @see ttspe_load_voice()
 215 */
 216 typedef int (*ttspe_unload_voice)(const char* language, int type);
 217
 218 /**
 219 * @brief Starts voice synthesis, asynchronously.
 220 *
 221 * @param[in] language A language
 222 * @param[in] type A voice type
 223 * @param[in] text Texts
 224 * @param[in] speed A speaking speed
 225 * @param[in] user_data The user data to be passed to the callback function
 226 *
 227 * @return 0 on success, otherwise a negative error value
 228 * @retval #TTSP_ERROR_NONE Successful
 229 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 230 * @retval #TTSP_ERROR_INVALID_STATE Not initialized or already started synthesis
 231 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
 232 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 233 * @retval #TTSP_ERROR_OUT_OF_NETWORK Out of network
 234 *
 235 * @post This function invokes ttspe_result_cb().
 236 *
 237 * @see ttspe_result_cb()
 238 * @see ttspe_cancel_synthesis()
 239 */
 240 typedef int (*ttspe_start_synthesis)(const char* language, int type, const char* text, int speed, void* user_data);
 241
 242 /**
 243 * @brief Cancels voice synthesis.
 244 *
 245 * @return 0 on success, otherwise a negative error value
 246 * @retval #TTSP_ERROR_NONE Successful
 247 * @retval #TTSP_ERROR_INVALID_STATE Not initialized or not started synthesis
 248 *
 249 * @pre The ttspe_start_synthesis() should be performed
 250 *
 251 * @see ttspe_start_synthesis()
 252 */
 253 typedef int (*ttspe_cancel_synthesis)(void);
 254
 255 /**
 256 * @brief Set private data.
 257 * @since_tizen 3.0
 258 *
 259 * @param[in] key Key field of private data.
 260 * @param[in] data Data field of private data.
 261 *
 262 * @return 0 on success, otherwise a negative error value
 263 * @retval #TTSE_ERROR_NONE Successful
 264 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 265 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failed
 266 *
 267 * @see ttse_get_private_data()
 268 */
 269 typedef int (* ttspe_set_private_data)(const char* key, const char* data);
 270
 271 /**
 272 * @brief Get private data.
 273 * @since_tizen 3.0
 274 *
 275 * @param[out] key Key field of private data.
 276 * @param[out] data Data field of private data.
 277 *
 278 * @return 0 on success, otherwise a negative error value
 279 * @retval #TTSE_ERROR_NONE Successful
 280 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 281 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failed
 282 *
 283 * @see ttse_set_private_data()
 284 */
 285 typedef int (* ttspe_get_private_data)(const char* key, char** data);
 286
 287
 288 /**
 289 * @brief Gets the mode.
 290 *
 291 * @param[out] mode The tts daemon mode
 292 *
 293 * @return 0 on success, otherwise a negative error value
 294 * @retval #TTSP_ERROR_NONE Successful
 295 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 296 *
 297 */
 298 typedef int (*ttspd_get_mode)(ttsp_mode_e* mode);
 299
 300 /**
 301 * @brief Gets the speed range.
 302 *
 303 * @param[out] min The minimun speed value
 304 * @param[out] normal The normal speed value
 305 * @param[out] max The maximum speed value
 306 *
 307 * @return 0 on success, otherwise a negative error value
 308 * @retval #TTSP_ERROR_NONE Successful
 309 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 310 *
 311 */
 312 typedef int (*ttspd_get_speed_range)(int* min, int* normal, int* max);
 313
 314 /**
 315 * @brief Gets the pitch range.
 316 *
 317 * @param[out] min The minimun pitch value
 318 * @param[out] normal The normal pitch value
 319 * @param[out] max The maximum pitch value
 320 *
 321 * @return 0 on success, otherwise a negative error value
 322 * @retval #TTSP_ERROR_NONE Successful
 323 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 324 *
 325 */
 326 typedef int (*ttspd_get_pitch_range)(int* min, int* normal, int* max);
 327
 328 /**
 329 * @brief A structure of the engine functions
 330 */
 331 typedef struct {
 332         int size;                                               /**< Size of structure */
 333         int version;                                            /**< Version */
 334
 335         ttspe_initialize                initialize;             /**< Initialize engine */
 336         ttspe_deinitialize              deinitialize;           /**< Shutdown engine */
 337
 338         /* Get / Set engine information */
 339         ttspe_foreach_supported_voices  foreach_voices;         /**< Get voice list */
 340         ttspe_is_valid_voice            is_valid_voice;         /**< Check voice */
 341         ttspe_set_pitch                 set_pitch;              /**< Set default pitch */
 342
 343         /* Load / Unload voice */
 344         ttspe_load_voice                load_voice;             /**< Load voice */
 345         ttspe_unload_voice              unload_voice;           /**< Unload voice */
 346
 347         /* Control synthesis */
 348         ttspe_start_synthesis           start_synth;            /**< Start synthesis */
 349         ttspe_cancel_synthesis          cancel_synth;           /**< Cancel synthesis */
 350         ttspe_set_private_data          set_private_data;       /**< Set private data */
 351         ttspe_get_private_data          get_private_data;       /**< Get private data */
 352 } ttspe_funcs_s;
 353
 354 /**
 355 * @brief A structure of the daemon functions
 356 */
 357 typedef struct {
 358         int size;                                               /**< size */
 359         int version;                                            /**< version */
 360
 361         ttspd_get_mode                  get_mode;               /**< Get mode */
 362         ttspd_get_speed_range           get_speed_range;        /**< Get speed range */
 363         ttspd_get_pitch_range           get_pitch_range;        /**< Get pitch range */
 364 } ttspd_funcs_s;
 365
 366 /**
 367 * @brief Loads the engine by the daemon.
 368 *
 369 * @param[in] pdfuncs The daemon functions
 370 * @param[out] pefuncs The engine functions
 371 *
 372 * @return 0 on success, otherwise a negative error value
 373 * @retval #TTSP_ERROR_NONE Successful
 374 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 375 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 376 *
 377 * @pre The ttsp_get_engine_info() should be successful.
 378 * @post The daemon calls the engine functions of ttspe_funcs_s.
 379 *
 380 * @see ttsp_get_engine_info()
 381 * @see ttsp_unload_engine()
 382 */
 383 int ttsp_load_engine(ttspd_funcs_s* pdfuncs, ttspe_funcs_s* pefuncs);
 384
 385 /**
 386 * @brief Unloads the engine by the daemon.
 387 *
 388 * @pre The ttsp_load_engine() should be performed.
 389 *
 390 * @see ttsp_load_engine()
 391 */
 392 void ttsp_unload_engine(void);
 393
 394 /**
 395 * @brief Called to get this engine base information.
 396 *
 397 * @param[in] engine_uuid The engine id
 398 * @param[in] engine_name The engine name
 399 * @param[in] setting_ug_name The setting ug name
 400 * @param[in] use_network @c true to need network \n @c false not to need network
 401 * @param[in] user_data The user data passed from the engine info function
 402 *
 403 * @pre ttsp_get_engine_info() will invoke this callback.
 404 *
 405 * @see ttsp_get_engine_info()
 406 */
 407 typedef void (*ttsp_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* setting_ug_name,
 408                                      bool use_network, void* user_data);
 409
 410 /**
 411 * @brief Gets base information of the engine by the daemon.
 412 *
 413 * @param[in] callback A callback function
 414 * @param[in] user_data The user data to be passed to the callback function
 415 *
 416 * @return 0 on success, otherwise a negative error value
 417 * @retval #TTSP_ERROR_NONE Successful
 418 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 419 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 420 *
 421 * @post This function invokes ttsp_engine_info_cb() for getting engine information.
 422 *
 423 * @see ttsp_engine_info_cb()
 424 * @see ttsp_load_engine()
 425 */
 426 int ttsp_get_engine_info(ttsp_engine_info_cb callback, void* user_data);
 427
 428 #ifdef __cplusplus
 429 }
 430 #endif
 431
 432 /**
 433 * @}@}
 434 */
 435
 436 #endif /* __TTSP_H__ */