server/sttp.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 #ifndef __STTP_H__
  15 #define __STTP_H__
  16
  17 #include <errno.h>
  18 #include <stdbool.h>
  19
  20 /**
  21 * @addtogroup STT_ENGINE_MODULE
  22 * @{
  23 */
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30 * @brief Enumerations of error codes.
  31 */
  32 typedef enum {
  33         STTP_ERROR_NONE                 =  0,           /**< Successful */
  34         STTP_ERROR_OUT_OF_MEMORY        = -ENOMEM,      /**< Out of Memory */
  35         STTP_ERROR_IO_ERROR             = -EIO,         /**< I/O error */
  36         STTP_ERROR_INVALID_PARAMETER    = -EINVAL,      /**< Invalid parameter */
  37         STTP_ERROR_OUT_OF_NETWORK       = -ENETDOWN,    /**< Out of network */
  38         STTP_ERROR_INVALID_STATE        = -0x0100031,   /**< Invalid state */
  39         STTP_ERROR_INVALID_LANGUAGE     = -0x0100032,   /**< Invalid language */
  40         STTP_ERROR_OPERATION_FAILED     = -0x0100034,   /**< Operation failed */
  41         STTP_ERROR_NOT_SUPPORTED_FEATURE= -0x0100035    /**< Not supported feature */
  42 }sttp_error_e;
  43
  44 /**
  45 * @brief Enumerations of audio type.
  46 */
  47 typedef enum {
  48         STTP_AUDIO_TYPE_PCM_S16_LE = 0, /**< Signed 16bit audio type, Little endian */
  49         STTP_AUDIO_TYPE_PCM_U8          /**< Unsigned 8bit audio type */
  50 }sttp_audio_type_e;
  51
  52 /**
  53 * @brief Enumerations of callback event.
  54 */
  55 typedef enum {
  56         STTP_RESULT_EVENT_FINAL_RESULT = 0,     /**< Event when the recognition full or last result is ready  */
  57         STTP_RESULT_EVENT_PARTIAL_RESULT,       /**< Event when the recognition partial result is ready  */
  58         STTP_RESULT_EVENT_ERROR                 /**< Event when the recognition has failed */
  59 }sttp_result_event_e;
  60
  61 /**
  62 * @brief Enumerations of result time callback event.
  63 */
  64 typedef enum {
  65         STTP_RESULT_TIME_EVENT_BEGINNING = 0,   /**< Event when the token is beginning type */
  66         STTP_RESULT_TIME_EVENT_MIDDLE,          /**< Event when the token is middle type */
  67         STTP_RESULT_TIME_EVENT_END              /**< Event when the token is end type */
  68 }sttp_result_time_event_e;
  69
  70 /**
  71 * @brief Enumerations of silence type.
  72 */
  73 typedef enum {
  74         STTP_SILENCE_TYPE_NO_RECORD_TIMEOUT = 0,        /**< No sound is recorded */
  75         STTP_SILENCE_TYPE_END_OF_SPEECH_DETECTED        /**< End of speech is detected */
  76 }sttp_silence_type_e;
  77
  78 /**
  79 * @brief Recognition type : free form dictation and default type.
  80 */
  81 #define STTP_RECOGNITION_TYPE_FREE              "stt.recognition.type.FREE"
  82
  83 /**
  84 * @brief Recognition type : free form dictation continuously.
  85 */
  86 #define STTP_RECOGNITION_TYPE_FREE_PARTIAL      "stt.recognition.type.FREE.PARTIAL"
  87
  88 /**
  89 * @brief Recognition type : Search.
  90 */
  91 #define STTP_RECOGNITION_TYPE_SEARCH            "stt.recognition.type.SEARCH"
  92
  93 /**
  94 * @brief Recognition type : web search.
  95 */
  96 #define STTP_RECOGNITION_TYPE_WEB_SEARCH        "stt.recognition.type.WEB_SEARCH"
  97
  98 /**
  99 * @brief Recognition type : Map.
 100 */
 101 #define STTP_RECOGNITION_TYPE_MAP               "stt.recognition.type.MAP"
 102
 103
 104 /**
 105 * @brief Result message : None message
 106 */
 107 #define STTP_RESULT_MESSAGE_NONE                "stt.result.message.none"
 108
 109 /**
 110 * @brief Result error message : Recognition was failed because the speech started too soon
 111 */
 112 #define STTP_RESULT_MESSAGE_ERROR_TOO_SOON      "stt.result.message.error.too.soon"
 113
 114 /**
 115 * @brief Result error message : Recognition was failed because the speech started too short
 116 */
 117 #define STTP_RESULT_MESSAGE_ERROR_TOO_SHORT     "stt.result.message.error.too.short"
 118
 119 /**
 120 * @brief Result error message : Recognition was failed because the speech started too long
 121 */
 122 #define STTP_RESULT_MESSAGE_ERROR_TOO_LONG      "stt.result.message.error.too.long"
 123
 124 /**
 125 * @brief Result error message : Recognition was failed because the speech started too quiet to listen
 126 */
 127 #define STTP_RESULT_MESSAGE_ERROR_TOO_QUIET     "stt.result.message.error.too.quiet"
 128
 129 /**
 130 * @brief Result error message : Recognition was failed because the speech started too loud to listen
 131 */
 132 #define STTP_RESULT_MESSAGE_ERROR_TOO_LOUD      "stt.result.message.error.too.loud"
 133
 134 /**
 135 * @brief Result error message : Recognition was failed because the speech started too fast to listen
 136 */
 137 #define STTP_RESULT_MESSAGE_ERROR_TOO_FAST      "stt.result.message.error.too.fast"
 138
 139 /**
 140 * @brief Called to get recognition result.
 141 *
 142 * @param[in] event A result event
 143 * @param[in] type A recognition type (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_FREE_PARTIAL)
 144 * @param[in] data Result texts
 145 * @param[in] data_count Result text count
 146 * @param[in] msg Engine message (e.g. #STTP_RESULT_MESSAGE_NONE, #STTP_RESULT_MESSAGE_ERROR_TOO_SHORT)
 147 * @param[in] user_data  The user data passed from the start function
 148 *
 149 * @pre sttpe_stop() will invoke this callback.
 150 *
 151 * @see sttpe_start()
 152 * @see sttpe_stop()
 153 */
 154 typedef void (*sttpe_result_cb)(sttp_result_event_e event, const char* type, const char** data, int data_count,
 155                                 const char* msg, void* time_info, void* user_data);
 156
 157 /**
 158 * @brief Called to retrieve the time stamp of result.
 159 *
 160 * @param[in] index The result index
 161 * @param[in] event The token event
 162 * @param[in] text The result text
 163 * @param[in] start_time The start time of result text
 164 * @param[in] end_time The end time of result text
 165 * @param[in] user_data The user data passed from the foreach function
 166 *
 167 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 168 *
 169 * @pre sttpe_result_cb() should be called.
 170 *
 171 * @see sttpe_result_cb()
 172 */
 173 typedef bool (*sttpe_result_time_cb)(int index, sttp_result_time_event_e event, const char* text,
 174                                 long start_time, long end_time, void* user_data);
 175
 176 /**
 177 * @brief Called to detect silence from recording data.
 178 *
 179 * @param[in] user_data  The user data passed from the start function.
 180 *
 181 * @pre sttpe_set_recording_data() will invoke this callback.
 182 *
 183 * @see sttpe_set_recording_data()
 184 */
 185 typedef void (*sttpe_silence_detected_cb)(sttp_silence_type_e type, void* user_data);
 186
 187 /**
 188 * @brief Called to retrieve the supported languages.
 189 *
 190 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 191 *               followed by ISO 639-1 for the two-letter language code \n
 192 *               For example, "ko_KR" for Korean, "en_US" for American English
 193 * @param[in] user_data The user data passed from the foreach function
 194 *
 195 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 196 *
 197 * @pre sttpe_foreach_supported_languages() will invoke this callback.
 198 *
 199 * @see sttpe_foreach_supported_languages()
 200 */
 201 typedef bool (*sttpe_supported_language_cb)(const char* language, void* user_data);
 202
 203 /**
 204 * @brief Initializes the engine.
 205 *
 206 * @param[in] result_cb A callback function for recognition result
 207 * @param[in] silence_cb A callback function for silence detection
 208 *
 209 * @return 0 on success, otherwise a negative error value
 210 * @retval #STTP_ERROR_NONE Successful
 211 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 212 * @retval #STTP_ERROR_INVALID_STATE Already initialized
 213 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 214 *
 215 * @see sttpe_deinitialize()
 216 */
 217 typedef int (* sttpe_initialize)(sttpe_result_cb result_cb, sttpe_silence_detected_cb silence_cb);
 218
 219 /**
 220 * @brief Deinitializes the engine
 221 *
 222 * @return 0 on success, otherwise a negative error value
 223 * @retval #STTP_ERROR_NONE Successful
 224 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 225 *
 226 * @see sttpe_initialize()
 227 */
 228 typedef int (* sttpe_deinitialize)(void);
 229
 230 /**
 231 * @brief Retrieves all supported languages of the engine.
 232 *
 233 * @param[in] callback a callback function
 234 * @param[in] user_data The user data to be passed to the callback function
 235 *
 236 * @return 0 on success, otherwise a negative error value
 237 * @retval #STTP_ERROR_NONE Successful
 238 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 239 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 240 *
 241 * @post This function invokes sttpe_supported_language_cb() repeatedly for getting supported languages.
 242 *
 243 * @see sttpe_supported_language_cb()
 244 */
 245 typedef int (* sttpe_foreach_supported_langs)(sttpe_supported_language_cb callback, void* user_data);
 246
 247 /**
 248 * @brief Checks whether a language is valid or not.
 249 *
 250 * @param[in] language A language
 251 *
 252 * @return @c true to valid language, \n @c false to invalid language.
 253 *
 254 * @see sttpe_foreach_supported_languages()
 255 */
 256 typedef bool (* sttpe_is_valid_language)(const char* language);
 257
 258 /**
 259 * @brief Gets whether the engine supports silence detection.
 260 *
 261 * @return @c true to support silence detection, \n @c false not to support silence detection.
 262 *
 263 * @see sttpe_set_silence_detection()
 264 */
 265 typedef bool (* sttpe_support_silence_detection)(void);
 266
 267 /**
 268 * @brief Gets supporting recognition type.
 269 *
 270 * @return @c true to support recognition type, \n @c false not to support recognition type.
 271 *
 272 */
 273 typedef bool (* sttpe_support_recognition_type)(const char* type);
 274
 275 /**
 276 * @brief Gets recording format of the engine.
 277 *
 278 * @param[out] types The format used by the recorder.
 279 * @param[out] rate The sample rate used by the recorder.
 280 * @param[out] channels The number of channels used by the recorder.
 281 *
 282 * @return 0 on success, otherwise a negative error value
 283 * @retval #STTP_ERROR_NONE Successful
 284 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 285 */
 286 typedef int (* sttpe_get_recording_format)(sttp_audio_type_e* types, int* rate, int* channels);
 287
 288 /**
 289 * @brief Sets silence detection option.
 290 *
 291 * @param[in] value A value
 292 *
 293 * @return 0 on success, otherwise a negative error value
 294 * @retval #STTP_ERROR_NONE Successful
 295 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 296 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 297 */
 298 typedef int (* sttpe_set_silence_detection)(bool value);
 299
 300 /**
 301 * @brief Gets whether application is agreed to get engine service.
 302 *
 303 * @param[in] appid Application ID
 304 * @param[in] value A value
 305 *
 306 * @return 0 on success, otherwise a negative error value
 307 * @retval #STTP_ERROR_NONE Successful
 308 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 309 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 310 */
 311 typedef int (* sttpe_check_app_agreed)(const char* appid, bool* value);
 312
 313 /**
 314 * @brief Retrieves result time info in recognition callback of daemon.
 315 *
 316 * @param[in] callback a callback function
 317 * @param[in] user_data The user data to be passed to the callback function
 318 *
 319 * @return 0 on success, otherwise a negative error value
 320 * @retval #STTP_ERROR_NONE Successful
 321 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 322 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 323 *
 324 * @pre sttpe_result_cb() will be invoke this function.
 325 * @post This function invokes sttpe_result_time_cb() repeatedly for getting result time information.
 326 *
 327 * @see sttpe_result_time_cb()
 328 */
 329 typedef int (* sttpe_foreach_result_time)(void* time_info, sttpe_result_time_cb callback, void* user_data);
 330
 331 /**
 332 * @brief Start recognition.
 333 *
 334 * @param[in] language A language.
 335 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
 336 * @param[in] user_data The user data to be passed to the callback function.
 337 *
 338 * @return 0 on success, otherwise a negative error value
 339 * @retval #STTP_ERROR_NONE Successful
 340 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 341 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 342 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
 343 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 344 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 345 *
 346 * @pre The engine is not in recognition processing.
 347 *
 348 * @see sttpe_set_recording_data()
 349 * @see sttpe_stop()
 350 * @see sttpe_cancel()
 351 */
 352 typedef int (* sttpe_start)(const char* language, const char* type, void *user_data);
 353
 354 /**
 355 * @brief Sets recording data for speech recognition from recorder.
 356 *
 357 * @remark This function should be returned immediately after recording data copy.
 358 *
 359 * @param[in] data A recording data
 360 * @param[in] length A length of recording data
 361 *
 362 * @return 0 on success, otherwise a negative error value
 363 * @retval #STTP_ERROR_NONE Successful
 364 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 365 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 366 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 367 *
 368 * @pre sttpe_start() should succeed.
 369 * @post If the engine supports partial result, it will invoke sttpe_result_cb().
 370 *
 371 * @see sttpe_start()
 372 * @see sttpe_cancel()
 373 * @see sttpe_stop()
 374 */
 375 typedef int (* sttpe_set_recording_data)(const void* data, unsigned int length);
 376
 377 /**
 378 * @brief Stops to set recording data.
 379 *
 380 * @return 0 on success, otherwise a negative error value
 381 * @retval #STTP_ERROR_NONE Successful
 382 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 383 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 384 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 385 *
 386 * @pre sttpe_start() should succeed.
 387 * @post After processing of the engine, sttpe_result_cb() is called.
 388 *
 389 * @see sttpe_start()
 390 * @see sttpe_set_recording_data()
 391 * @see sttpe_result_cb()
 392 * @see sttpe_cancel()
 393 */
 394 typedef int (* sttpe_stop)(void);
 395
 396 /**
 397 * @brief Cancels the recognition process.
 398 *
 399 * @return 0 on success, otherwise a negative error value.
 400 * @retval #STTP_ERROR_NONE Successful.
 401 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
 402 * @pre STT engine is in recognition processing or recording.
 403 *
 404 * @see sttpe_start()
 405 * @see sttpe_stop()
 406 */
 407 typedef int (* sttpe_cancel)(void);
 408
 409 /**
 410 * @brief Start recognition of file.
 411 *
 412 * @param[in] language A language.
 413 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
 414 * @param[in] filepath A filepath for recognition.
 415 * @param[in] audio_type A audio type of file.
 416 * @param[in] sample_rate A sample rate of file.
 417 * @param[in] user_data The user data to be passed to the callback function.
 418 *
 419 * @return 0 on success, otherwise a negative error value
 420 * @retval #STTP_ERROR_NONE Successful
 421 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 422 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 423 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
 424 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 425 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 426 *
 427 * @pre The engine is not in recognition processing.
 428 *
 429 * @see sttpe_cancel_file()
 430 */
 431 typedef int (* sttpe_start_file)(const char* language, const char* type, const char* filepath,
 432                                  sttp_audio_type_e audio_type, int sample_rate, void *user_data);
 433
 434 /**
 435 * @brief Cancels the recognition process of file.
 436 *
 437 * @return 0 on success, otherwise a negative error value.
 438 * @retval #STTP_ERROR_NONE Successful.
 439 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
 440 * @pre STT engine is in recognition processing.
 441 *
 442 * @see sttpe_start_file()
 443 */
 444 typedef int (* sttpe_cancel_file)(void);
 445
 446 /**
 447 * @brief A structure of the engine functions.
 448 */
 449 typedef struct {
 450         int size;                                               /**< Size of structure */
 451         int version;                                            /**< Version */
 452
 453         sttpe_initialize                initialize;             /**< Initialize engine */
 454         sttpe_deinitialize              deinitialize;           /**< Shutdown engine */
 455
 456         /* Get engine information */
 457         sttpe_foreach_supported_langs   foreach_langs;          /**< Foreach language list */
 458         sttpe_is_valid_language         is_valid_lang;          /**< Check language */
 459         sttpe_support_silence_detection support_silence;        /**< Get silence detection support */
 460         sttpe_support_recognition_type  support_recognition_type; /**< Get recognition type support */
 461         sttpe_get_recording_format      get_audio_format;       /**< Get audio format */
 462         sttpe_foreach_result_time       foreach_result_time;    /**< Foreach result time */
 463
 464         /* Set engine information */
 465         sttpe_set_silence_detection     set_silence_detection;  /**< Set silence detection */
 466
 467         /* Check app agreement */
 468         sttpe_check_app_agreed          check_app_agreed;       /**< Get app agreement */
 469
 470         /* Control recognition */
 471         sttpe_start                     start;                  /**< Start recognition */
 472         sttpe_set_recording_data        set_recording;          /**< Set recording data */
 473         sttpe_stop                      stop;                   /**< Shutdown function */
 474         sttpe_cancel                    cancel;                 /**< Cancel recognition */
 475
 476         /* Control file recognition */
 477         sttpe_start_file                start_file;             /**< Start recognition */
 478         sttpe_cancel_file               cancel_file;            /**< Cancel recognition */
 479 } sttpe_funcs_s;
 480
 481 /**
 482 * @brief A structure of the daemon functions.
 483 */
 484 typedef struct {
 485         int size;                                               /**< size */
 486         int version;                                            /**< version */
 487
 488 } sttpd_funcs_s;
 489
 490 /**
 491 * @brief Loads the engine.
 492 *
 493 * @param[in] pdfuncs The daemon functions
 494 * @param[out] pefuncs The engine functions
 495 *
 496 * @return This function returns zero on success, or negative with error code on failure
 497 * @retval #STTP_ERROR_NONE Successful
 498 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 499 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 500 *
 501 * @pre The sttp_get_engine_info() should be successful.
 502 * @post The daemon calls engine functions of sttpe_funcs_s.
 503 *
 504 * @see sttp_get_engine_info()
 505 * @see sttp_unload_engine()
 506 */
 507 int sttp_load_engine(sttpd_funcs_s* pdfuncs, sttpe_funcs_s* pefuncs);
 508
 509 /**
 510 * @brief Unloads this engine by the daemon.
 511 *
 512 * @pre The sttp_load_engine() should be successful.
 513 *
 514 * @see sttp_load_engine()
 515 */
 516 void sttp_unload_engine(void);
 517
 518 /**
 519 * @brief Called to get the engine base information.
 520 *
 521 * @param[in] engine_uuid The engine id
 522 * @param[in] engine_name The engine name
 523 * @param[in] engine_setting The setting name
 524 * @param[in] use_network @c true to need network @c false not to need network.
 525 * @param[in] user_data The User data passed from sttp_get_engine_info()
 526 *
 527 * @pre sttp_get_engine_info() will invoke this callback.
 528 *
 529 * @see sttp_get_engine_info()
 530 */
 531 typedef void (*sttpe_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* engine_setting,
 532                                      bool use_network, void* user_data);
 533
 534 /**
 535 * @brief Gets the engine base information before the engine is loaded by the daemon.
 536 *
 537 * @param[in] callback Callback function
 538 * @param[in] user_data User data to be passed to the callback function
 539 *
 540 * @return This function returns zero on success, or negative with error code on failure
 541 * @retval #STTP_ERROR_NONE Successful
 542 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 543 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 544 *
 545 * @post This function invokes sttpe_engine_info_cb() for getting engine information.
 546 *
 547 * @see sttpe_engine_info_cb()
 548 * @see sttp_load_engine()
 549 */
 550 int sttp_get_engine_info(sttpe_engine_info_cb callback, void* user_data);
 551
 552 #ifdef __cplusplus
 553 }
 554 #endif
 555
 556 /**
 557  * @}@}
 558  */
 559
 560 #endif /* __STTP_H__ */