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 Defines of speaking speed.
  65 */
  66 #define TTSP_SPEED_MIN          1
  67 #define TTSP_SPEED_NORMAL       8
  68 #define TTSP_SPEED_MAX          15
  69
  70 /**
  71 * @brief Defines of speaking pitch.
  72 */
  73 #define TTSP_PITCH_MIN          1
  74 #define TTSP_PITCH_NORMAL       8
  75 #define TTSP_PITCH_MAX          15
  76
  77 /**
  78 * @brief Defines of voice type.
  79 */
  80 #define TTSP_VOICE_TYPE_MALE    1
  81 #define TTSP_VOICE_TYPE_FEMALE  2
  82 #define TTSP_VOICE_TYPE_CHILD   3
  83
  84 /**
  85 * @brief Called when the daemon gets synthesized result.
  86 *
  87 * @param[in] event A result event
  88 * @param[in] data Result data
  89 * @param[in] data_size Result data size
  90 * @param[in] audio_type A audio type
  91 * @param[in] rate A sample rate
  92 * @param[in] user_data The user data passed from the start synthesis function
  93 *
  94 * @return @c true to continue with the next iteration of synthesis \n @c false to stop
  95 *
  96 * @pre ttspe_start_synthesis() will invoke this callback.
  97 *
  98 * @see ttspe_start_synthesis()
  99 */
 100 typedef bool (*ttspe_result_cb)(ttsp_result_event_e event, const void* data, unsigned int data_size,
 101                         ttsp_audio_type_e audio_type, int rate, void *user_data);
 102
 103 /**
 104 * @brief Called when the daemon gets a language and a voice type.
 105 *
 106 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 107 *               followed by ISO 639-1 for the two-letter language code. \n
 108 *               For example, "ko_KR" for Korean, "en_US" for American English.
 109 * @param[in] type A voice type
 110 * @param[in] user_data The user data passed from the the foreach function
 111 *
 112 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 113 *
 114 * @pre ttspe_foreach_supported_voices() will invoke this callback.
 115 *
 116 * @see ttspe_foreach_supported_voices()
 117 */
 118 typedef bool (*ttspe_supported_voice_cb)(const char* language, int type, void* user_data);
 119
 120 /**
 121 * @brief Initializes the engine.
 122 *
 123 * @param[in] callbacks A callback function
 124 *
 125 * @return 0 on success, otherwise a negative error value
 126 * @retval #TTSP_ERROR_NONE Successful
 127 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 128 * @retval #TTSP_ERROR_INVALID_STATE Already initialized
 129 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 130 *
 131 * @see ttspe_deinitialize()
 132 */
 133 typedef int (* ttspe_initialize)(ttspe_result_cb callback);
 134
 135 /**
 136 * @brief Deinitializes the engine.
 137 *
 138 * @return 0 on success, otherwise a negative error value
 139 * @retval #TTSP_ERROR_NONE Successful
 140 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 141 *
 142 * @see ttspe_initialize()
 143 */
 144 typedef int (* ttspe_deinitialize)(void);
 145
 146 /**
 147 * @brief Retrieves all supported voices of the engine using callback function.
 148 *
 149 * @param[in] callback A callback function
 150 * @param[in] user_data The user data to be passed to the callback function
 151 *
 152 * @return 0 on success, otherwise a negative error value
 153 * @retval #TTSP_ERROR_NONE Successful
 154 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 155 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 156 *
 157 * @post This function invokes ttspe_supported_voice_cb() repeatedly for getting all supported languages.
 158 *
 159 * @see ttspe_supported_voice_cb()
 160 */
 161 typedef int (* ttspe_foreach_supported_voices)(ttspe_supported_voice_cb callback, void* user_data);
 162
 163 /**
 164 * @brief Checks whether the voice is valid or not.
 165 *
 166 * @param[in] language A language
 167 * @param[in] type A voice type
 168 *
 169 * @return @c true to be valid \n @c false not to be valid
 170 *
 171 * @see ttspe_foreach_supported_voices()
 172 */
 173 typedef bool (* ttspe_is_valid_voice)(const char* language, int type);
 174
 175 /**
 176 * @brief Sets default pitch.
 177 *
 178 * @param[in] pitch default pitch
 179 *
 180 * @return 0 on success, otherwise a negative error value
 181 * @retval #TTSP_ERROR_NONE Successful
 182 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 183 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 184 * @retval #TTSP_ERROR_OPERATION_FAILED Fail
 185 */
 186 typedef int (* ttspe_set_pitch)(int pitch);
 187
 188 /**
 189 * @brief Load voice of the engine.
 190 *
 191 * @param[in] language language
 192 * @param[in] type voice type
 193 *
 194 * @return 0 on success, otherwise a negative error value
 195 * @retval #TTSP_ERROR_NONE Successful
 196 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 197 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 198 * @retval #TTSP_ERROR_OUT_OF_MEMORY Out of memory
 199 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
 200 * @retval #TTSP_ERROR_OPERATION_FAILED Fail
 201 *
 202 * @see ttspe_unload_voice()
 203 */
 204 typedef int (* ttspe_load_voice)(const char* language, int type);
 205
 206 /**
 207 * @brief Unload voice of the engine.
 208 *
 209 * @param[in] language language
 210 * @param[in] type voice type
 211 *
 212 * @return 0 on success, otherwise a negative error value
 213 * @retval #TTSP_ERROR_NONE Successful
 214 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 215 * @retval #TTSP_ERROR_INVALID_STATE Not initialized
 216 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
 217 * @retval #TTSP_ERROR_OPERATION_FAILED Fail
 218 *
 219 * @see ttspe_load_voice()
 220 */
 221 typedef int (* ttspe_unload_voice)(const char* language, int type);
 222
 223 /**
 224 * @brief Starts voice synthesis, asynchronously.
 225 *
 226 * @param[in] language A language
 227 * @param[in] type A voice type
 228 * @param[in] text Texts
 229 * @param[in] speed A speaking speed
 230 * @param[in] user_data The user data to be passed to the callback function
 231 *
 232 * @return 0 on success, otherwise a negative error value
 233 * @retval #TTSP_ERROR_NONE Successful
 234 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 235 * @retval #TTSP_ERROR_INVALID_STATE Not initialized or already started synthesis
 236 * @retval #TTSP_ERROR_INVALID_VOICE Invalid voice
 237 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 238 * @retval #TTSP_ERROR_OUT_OF_NETWORK Out of network
 239 *
 240 * @post This function invokes ttspe_result_cb().
 241 *
 242 * @see ttspe_result_cb()
 243 * @see ttspe_cancel_synthesis()
 244 */
 245 typedef int (* ttspe_start_synthesis)(const char* language, int type, const char* text, int speed, void* user_data);
 246
 247 /**
 248 * @brief Cancels voice synthesis.
 249 *
 250 * @return 0 on success, otherwise a negative error value
 251 * @retval #TTSP_ERROR_NONE Successful
 252 * @retval #TTSP_ERROR_INVALID_STATE Not initialized or not started synthesis
 253 *
 254 * @pre The ttspe_start_synthesis() should be performed
 255 *
 256 * @see ttspe_start_synthesis()
 257 */
 258 typedef int (* ttspe_cancel_synthesis)(void);
 259
 260 /**
 261 * @brief A structure of the engine functions
 262 */
 263 typedef struct {
 264         int size;                                               /**< Size of structure */
 265         int version;                                            /**< Version */
 266
 267         ttspe_initialize                initialize;             /**< Initialize engine */
 268         ttspe_deinitialize              deinitialize;           /**< Shutdown engine */
 269
 270         /* Get / Set engine information */
 271         ttspe_foreach_supported_voices  foreach_voices;         /**< Get voice list */
 272         ttspe_is_valid_voice            is_valid_voice;         /**< Check voice */
 273         ttspe_set_pitch                 set_pitch;              /**< Set default pitch */
 274
 275         /* Load / Unload voice */
 276         ttspe_load_voice                load_voice;             /**< Load voice */
 277         ttspe_unload_voice              unload_voice;           /**< Unload voice */
 278
 279         /* Control synthesis */
 280         ttspe_start_synthesis           start_synth;            /**< Start synthesis */
 281         ttspe_cancel_synthesis          cancel_synth;           /**< Cancel synthesis */
 282 } ttspe_funcs_s;
 283
 284 /**
 285 * @brief A structure of the daemon functions
 286 */
 287 typedef struct {
 288         int size;                                               /**< size */
 289         int version;                                            /**< version */
 290
 291 }ttspd_funcs_s;
 292
 293 /**
 294 * @brief Loads the engine by the daemon.
 295 *
 296 * @param[in] pdfuncs The daemon functions
 297 * @param[out] pefuncs The engine functions
 298 *
 299 * @return 0 on success, otherwise a negative error value
 300 * @retval #TTSP_ERROR_NONE Successful
 301 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 302 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 303 *
 304 * @pre The ttsp_get_engine_info() should be successful.
 305 * @post The daemon calls the engine functions of ttspe_funcs_s.
 306 *
 307 * @see ttsp_get_engine_info()
 308 * @see ttsp_unload_engine()
 309 */
 310 int ttsp_load_engine(ttspd_funcs_s* pdfuncs, ttspe_funcs_s* pefuncs);
 311
 312 /**
 313 * @brief Unloads the engine by the daemon.
 314 *
 315 * @pre The ttsp_load_engine() should be performed.
 316 *
 317 * @see ttsp_load_engine()
 318 */
 319 void ttsp_unload_engine(void);
 320
 321 /**
 322 * @brief Called to get this engine base information.
 323 *
 324 * @param[in] engine_uuid The engine id
 325 * @param[in] engine_name The engine name
 326 * @param[in] setting_ug_name The setting ug name
 327 * @param[in] use_network @c true to need network \n @c false not to need network
 328 * @param[in] user_data The user data passed from the engine info function
 329 *
 330 * @pre ttsp_get_engine_info() will invoke this callback.
 331 *
 332 * @see ttsp_get_engine_info()
 333 */
 334 typedef void (*ttsp_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* setting_ug_name,
 335                                      bool use_network, void* user_data);
 336
 337 /**
 338 * @brief Gets base information of the engine by the daemon.
 339 *
 340 * @param[in] callback A callback function
 341 * @param[in] user_data The user data to be passed to the callback function
 342 *
 343 * @return 0 on success, otherwise a negative error value
 344 * @retval #TTSP_ERROR_NONE Successful
 345 * @retval #TTSP_ERROR_INVALID_PARAMETER Invalid parameter
 346 * @retval #TTSP_ERROR_OPERATION_FAILED Operation failed
 347 *
 348 * @post This function invokes ttsp_engine_info_cb() for getting engine information.
 349 *
 350 * @see ttsp_engine_info_cb()
 351 * @see ttsp_load_engine()
 352 */
 353 int ttsp_get_engine_info(ttsp_engine_info_cb callback, void* user_data);
 354
 355 #ifdef __cplusplus
 356 }
 357 #endif
 358
 359 /**
 360 * @}@}
 361 */
 362
 363 #endif /* __TTSP_H__ */