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 /**
 257 * @brief Gets the mode.
 258 *
 259 * @param[out] mode The tts daemon mode
 260 *
 261 * @return 0 on success, otherwise a negative error value
 262 * @retval #TTSP_ERROR_NONE Successful
 263 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 264 *
 265 */
 266 typedef int (* ttspd_get_mode)(ttsp_mode_e* mode);
 267
 268 /**
 269 * @brief Gets the speed range.
 270 *
 271 * @param[out] min The minimun speed value
 272 * @param[out] normal The normal speed value
 273 * @param[out] max The maximum speed value
 274 *
 275 * @return 0 on success, otherwise a negative error value
 276 * @retval #TTSP_ERROR_NONE Successful
 277 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 278 *
 279 */
 280 typedef int (* ttspd_get_speed_range)(int* min, int* normal, int* max);
 281
 282 /**
 283 * @brief Gets the pitch range.
 284 *
 285 * @param[out] min The minimun pitch value
 286 * @param[out] normal The normal pitch value
 287 * @param[out] max The maximum pitch value
 288 *
 289 * @return 0 on success, otherwise a negative error value
 290 * @retval #TTSP_ERROR_NONE Successful
 291 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 292 *
 293 */
 294 typedef int (* ttspd_get_pitch_range)(int* min, int* normal, int* max);
 295
 296 /**
 297 * @brief A structure of the engine functions
 298 */
 299 typedef struct {
 300         int size;                                               /**< Size of structure */
 301         int version;                                            /**< Version */
 302
 303         ttspe_initialize                initialize;             /**< Initialize engine */
 304         ttspe_deinitialize              deinitialize;           /**< Shutdown engine */
 305
 306         /* Get / Set engine information */
 307         ttspe_foreach_supported_voices  foreach_voices;         /**< Get voice list */
 308         ttspe_is_valid_voice            is_valid_voice;         /**< Check voice */
 309         ttspe_set_pitch                 set_pitch;              /**< Set default pitch */
 310
 311         /* Load / Unload voice */
 312         ttspe_load_voice                load_voice;             /**< Load voice */
 313         ttspe_unload_voice              unload_voice;           /**< Unload voice */
 314
 315         /* Control synthesis */
 316         ttspe_start_synthesis           start_synth;            /**< Start synthesis */
 317         ttspe_cancel_synthesis          cancel_synth;           /**< Cancel synthesis */
 318 } ttspe_funcs_s;
 319
 320 /**
 321 * @brief A structure of the daemon functions
 322 */
 323 typedef struct {
 324         int size;                                               /**< size */
 325         int version;                                            /**< version */
 326
 327         ttspd_get_mode                  get_mode;               /**< Get mode */
 328         ttspd_get_speed_range           get_speed_range;        /**< Get speed range */
 329         ttspd_get_pitch_range           get_pitch_range;        /**< Get pitch range */
 330 }ttspd_funcs_s;
 331
 332 /**
 333 * @brief Loads the engine by the daemon.
 334 *
 335 * @param[in] pdfuncs The daemon functions
 336 * @param[out] pefuncs The engine functions
 337 *
 338 * @return 0 on success, otherwise a negative error value
 339 * @retval #TTSP_ERROR_NONE Successful
 340 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 341 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 342 *
 343 * @pre The ttsp_get_engine_info() should be successful.
 344 * @post The daemon calls the engine functions of ttspe_funcs_s.
 345 *
 346 * @see ttsp_get_engine_info()
 347 * @see ttsp_unload_engine()
 348 */
 349 int ttsp_load_engine(ttspd_funcs_s* pdfuncs, ttspe_funcs_s* pefuncs);
 350
 351 /**
 352 * @brief Unloads the engine by the daemon.
 353 *
 354 * @pre The ttsp_load_engine() should be performed.
 355 *
 356 * @see ttsp_load_engine()
 357 */
 358 void ttsp_unload_engine(void);
 359
 360 /**
 361 * @brief Called to get this engine base information.
 362 *
 363 * @param[in] engine_uuid The engine id
 364 * @param[in] engine_name The engine name
 365 * @param[in] setting_ug_name The setting ug name
 366 * @param[in] use_network @c true to need network \n @c false not to need network
 367 * @param[in] user_data The user data passed from the engine info function
 368 *
 369 * @pre ttsp_get_engine_info() will invoke this callback.
 370 *
 371 * @see ttsp_get_engine_info()
 372 */
 373 typedef void (*ttsp_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* setting_ug_name,
 374                                      bool use_network, void* user_data);
 375
 376 /**
 377 * @brief Gets base information of the engine by the daemon.
 378 *
 379 * @param[in] callback A callback function
 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 #TTSP_ERROR_NONE Successful
 384 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 385 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 386 *
 387 * @post This function invokes ttsp_engine_info_cb() for getting engine information.
 388 *
 389 * @see ttsp_engine_info_cb()
 390 * @see ttsp_load_engine()
 391 */
 392 int ttsp_get_engine_info(ttsp_engine_info_cb callback, void* user_data);
 393
 394 #ifdef __cplusplus
 395 }
 396 #endif
 397
 398 /**
 399 * @}@}
 400 */
 401
 402 #endif /* __TTSP_H__ */