server/ttsp.h

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