include/stt_file.h

   1 /*
   2  * Copyright (c) 2011-2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __STT_FILE_H__
  18 #define __STT_FILE_H__
  19
  20 #include <errno.h>
  21 #include <stdbool.h>
  22
  23 /**
  24 * @addtogroup STT_FILE_MODULE
  25 * @{
  26 */
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33 /**
  34 * @brief Enumerations of error codes.
  35 */
  36 typedef enum {
  37         STT_FILE_ERROR_NONE                     = 0,                    /**< Successful */
  38         STT_FILE_ERROR_OUT_OF_MEMORY            = -ENOMEM,              /**< Out of Memory */
  39         STT_FILE_ERROR_IO_ERROR                 = -EIO,                 /**< I/O error */
  40         STT_FILE_ERROR_INVALID_PARAMETER        = -EINVAL,              /**< Invalid parameter */
  41         STT_FILE_ERROR_OUT_OF_NETWORK           = -ENETDOWN,            /**< Out of network */
  42         STT_FILE_ERROR_INVALID_STATE            = -0x0100000 | 0x31,    /**< Invalid state */
  43         STT_FILE_ERROR_INVALID_LANGUAGE         = -0x0100000 | 0x32,    /**< Invalid language */
  44         STT_FILE_ERROR_ENGINE_NOT_FOUND         = -0x0100000 | 0x33,    /**< No available engine  */
  45         STT_FILE_ERROR_OPERATION_FAILED         = -0x0100000 | 0x34,    /**< Operation failed  */
  46         STT_FILE_ERROR_NOT_SUPPORTED_FEATURE    = -0x0100000 | 0x35,    /**< Not supported feature of current engine */
  47         STT_FILE_ERROR_NOT_AGREE_SERVICE        = -0x0100000 | 0x36     /**< Not agreed service of engine*/
  48 } stt_file_error_e;
  49
  50 /**
  51 * @brief Enumerations of state.
  52 */
  53 typedef enum {
  54         STT_FILE_STATE_NONE             = 0,    /**< 'NONE' state */
  55         STT_FILE_STATE_READY            = 1,    /**< 'READY' state */
  56         STT_FILE_STATE_PROCESSING       = 2,    /**< 'PROCESSING' state */
  57 } stt_file_state_e;
  58
  59 /**
  60 * @brief Enumerations of audio type.
  61 */
  62 typedef enum {
  63         STT_FILE_AUDIO_TYPE_RAW_S16 = 0,        /**< Signed 16-bit audio sample */
  64         STT_FILE_AUDIO_TYPE_RAW_U8,             /**< Unsigned 8-bit audio sample */
  65         STT_FILE_AUDIO_TYPE_MAX
  66 } stt_file_audio_type_e;
  67
  68 /**
  69 * @brief Enumerations of result event.
  70 */
  71 typedef enum {
  72         STT_FILE_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the recognition full or last result is ready  */
  73         STT_FILE_RESULT_EVENT_PARTIAL_RESULT,   /**< Event when the recognition partial result is ready  */
  74         STT_FILE_RESULT_EVENT_ERROR             /**< Event when the recognition has failed */
  75 } stt_file_result_event_e;
  76
  77 /**
  78 * @brief Enumerations of result time callback event.
  79 */
  80 typedef enum {
  81         STT_FILE_RESULT_TIME_EVENT_BEGINNING = 0,       /**< Event when the token is beginning type */
  82         STT_FILE_RESULT_TIME_EVENT_MIDDLE = 1,          /**< Event when the token is middle type */
  83         STT_FILE_RESULT_TIME_EVENT_END = 2              /**< Event when the token is end type */
  84 } stt_file_result_time_event_e;
  85
  86 /**
  87 * @brief Recognition type : Continuous free dictation.
  88 */
  89 #define STT_RECOGNITION_TYPE_FREE_PARTIAL       "stt.recognition.type.FREE.PARTIAL"
  90
  91
  92 /**
  93 * @brief Called to get a engine information.
  94 *
  95 * @param[in] engine_id Engine id.
  96 * @param[in] engine_name Engine name.
  97 * @param[in] user_data User data passed from the stt_file_setting_foreach_supported_engines().
  98 *
  99 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 100 * @pre stt_file_foreach_supported_engines() will invoke this callback.
 101 *
 102 * @see stt_file_foreach_supported_engines()
 103 */
 104 typedef bool(*stt_file_supported_engine_cb)(const char* engine_id, const char* engine_name, void* user_data);
 105
 106 /**
 107 * @brief Called when STT gets the recognition result from engine.
 108 *
 109 * @remark After stt_file_start() is called and recognition result is occured, this function is called.
 110 *
 111 * @param[in] event The result event
 112 * @param[in] data Result texts
 113 * @param[in] data_count Result text count
 114 * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
 115 * @param[in] user_data The user data passed from the callback registration function
 116 *
 117 * @pre stt_file_start() will invoke this callback if you register it using stt_file_set_recognition_result_cb().
 118 * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT FILE state will be #STT_FILE_STATE_READY.
 119 *
 120 * @see stt_file_set_recognition_result_cb()
 121 * @see stt_file_unset_recognition_result_cb()
 122 */
 123 typedef void (*stt_file_recognition_result_cb)(stt_file_result_event_e event, const char** data, int data_count,
 124                                           const char* msg, void *user_data);
 125
 126 /**
 127 * @brief Called when STT get the time stamp of recognition result.
 128 *
 129 * @param[in] index The result index
 130 * @param[in] event The token event
 131 * @param[in] text The result text
 132 * @param[in] start_time The start time of result text
 133 * @param[in] end_time The end time of result text
 134 * @param[in] user_data The user data passed from the foreach function
 135 *
 136 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 137 *
 138 * @pre stt_file_recognition_result_cb() should be called.
 139 *
 140 * @see stt_file_recognition_result_cb()
 141 */
 142 typedef bool (*stt_file_result_time_cb)(int index, stt_file_result_time_event_e event, const char* text,
 143                                    long start_time, long end_time, void* user_data);
 144
 145 /**
 146 * @brief Called when the state of STT FILE is changed.
 147 *
 148 * @param[in] previous A previous state
 149 * @param[in] current A current state
 150 * @param[in] user_data The user data passed from the callback registration function.
 151 *
 152 * @pre An application registers this callback using stt_file_set_state_changed_cb() to detect changing state.
 153 *
 154 * @see stt_file_set_state_changed_cb()
 155 * @see stt_file_unset_state_changed_cb()
 156 */
 157 typedef void (*stt_file_state_changed_cb)(stt_file_state_e previous, stt_file_state_e current, void* user_data);
 158
 159 /**
 160 * @brief Called to retrieve the supported languages.
 161 *
 162 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 163 *               followed by ISO 639-1 for the two-letter language code. \n
 164 *               For example, "ko_KR" for Korean, "en_US" for American English.
 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 * @pre stt_file_foreach_supported_languages() will invoke this callback.
 169 *
 170 * @see stt_file_foreach_supported_languages()
 171 */
 172 typedef bool (*stt_file_supported_language_cb)(const char* language, void* user_data);
 173
 174
 175 /**
 176 * @brief Initialize STT FILE.
 177 *
 178 * @return 0 on success, otherwise a negative error value
 179 * @retval #STT_FILE_ERROR_NONE Successful
 180 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 181 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
 182 * @retval #STT_FILE_ERROR_ENGINE_NOT_FOUND Engine not found
 183 *
 184 * @pre The state should be #STT_FILE_STATE_NONE.
 185 * @post If this function is called, the STT state will be #STT_FILE_STATE_READY.
 186 *
 187 * @see stt_file_deinitialize(void)
 188 */
 189 int stt_file_initialize(void);
 190
 191 /**
 192 * @brief Deinitialize STT FILE.
 193 *
 194 * @return 0 on success, otherwise a negative error value
 195 * @retval #STT_FILE_ERROR_NONE Successful
 196 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 197 *
 198 * @pre The state should be #STT_FILE_STATE_READY.
 199 * @post If this function is called, the STT FILE state will be #STT_FILE_STATE_NONE.
 200 *
 201 * @see stt_file_initialize(void)
 202 */
 203 int stt_file_deinitialize(void);
 204
 205 /**
 206 * @brief Gets the current state.
 207 *
 208 * @param[out] state The current state of STT
 209 *
 210 * @return 0 on success, otherwise a negative error value
 211 * @retval #STT_FILE_ERROR_NONE Successful
 212 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
 213 *
 214 * @see stt_file_state_changed_cb()
 215 */
 216 int stt_file_get_state(stt_file_state_e* state);
 217
 218 /**
 219 * @brief Retrieve supported engine informations using callback function.
 220 *
 221 * @param[in] callback The callback function to invoke
 222 * @param[in] user_data The user data to be passed to the callback function.
 223 *
 224 * @return 0 on success, otherwise a negative error value.
 225 * @retval #STT_FILE_ERROR_NONE Success.
 226 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
 227 * @retval #STT_FILE_ERROR_INVALID_STATE STT Not initialized.
 228 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure.
 229 *
 230 * @pre The state should be #STT_FILE_STATE_READY.
 231 * @post This function invokes stt_file_supported_engine_cb() repeatedly for getting engine information.
 232 *
 233 * @see stt_file_supported_engine_cb()
 234 */
 235 int stt_file_foreach_supported_engines(stt_file_supported_engine_cb callback, void* user_data);
 236
 237 /**
 238 * @brief Get current engine id.
 239 *
 240 * @remark If the function is success, @a engine_id must be released with free() by you.
 241 *
 242 * @param[out] engine_id engine id.
 243 *
 244 * @return 0 on success, otherwise a negative error value.
 245 * @retval #STT_FILE_ERROR_NONE Success.
 246 * @retval #STT_FILE_ERROR_OUT_OF_MEMORY Out of memory.
 247 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
 248 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state.
 249 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure.
 250 *
 251 * @pre The state should be #STT_FILE_STATE_READY.
 252 *
 253 * @see stt_file_foreach_supported_engines()
 254 * @see stt_file_set_engine()
 255 */
 256 int stt_file_get_engine(char** engine_id);
 257
 258 /**
 259 * @brief Set engine id.
 260 *
 261 * @param[in] engine_id engine id.
 262 *
 263 * @return 0 on success, otherwise a negative error value.
 264 * @retval #STT_FILE_ERROR_NONE Success.
 265 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
 266 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state.
 267 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure.
 268 *
 269 * @pre The state should be #STT_FILE_STATE_READY.
 270 *
 271 * @see stt_file_get_engine()
 272 */
 273 int stt_file_set_engine(const char* engine_id);
 274
 275 /**
 276 * @brief Retrieves all supported languages of current engine using callback function.
 277 *
 278 * @param[in] callback The callback function to invoke
 279 * @param[in] user_data The user data to be passed to the callback function
 280 *
 281 * @return 0 on success, otherwise a negative error value
 282 * @retval #STT_FILE_ERROR_NONE Successful
 283 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
 284 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
 285 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 286 *
 287 * @pre The state should be #STT_FILE_STATE_READY.
 288 * @post This function invokes stt_file_supported_language_cb() repeatedly for getting languages.
 289 *
 290 * @see stt_file_supported_language_cb()
 291 * @see stt_file_get_default_language()
 292 */
 293 int stt_file_foreach_supported_languages(stt_file_supported_language_cb callback, void* user_data);
 294
 295
 296 /**
 297 * @brief Starts file recognition asynchronously.
 298 *
 299 * @param[in] language The language selected from stt_file_foreach_supported_languages()
 300 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 301 * @param[in] filepath PCM filepath for recognition
 302 * @param[in] audio_type audio type of file
 303 * @param[in] sample_rate sample rate of file
 304 *
 305 * @return 0 on success, otherwise a negative error value
 306 * @retval #STT_FILE_ERROR_NONE Successful
 307 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
 308 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 309 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
 310 * @retval #STT_FILE_ERROR_INVALID_LANGUAGE Invalid language
 311 * @retval #STT_FILE_ERROR_OUT_OF_NETWORK Out of network
 312 *
 313 * @pre The state should be #STT_FILE_STATE_READY.
 314 * @post It will invoke stt_file_state_changed_cb(), if you register a callback with stt_file_state_changed_cb(). \n
 315 * If this function succeeds, the STT state will be #STT_FILE_STATE_PROCESSING.
 316 *
 317 * @see stt_file_cancel()
 318 */
 319 int stt_file_start(const char* language, const char* type, const char* filepath,
 320                         stt_file_audio_type_e audio_type, int sample_rate);
 321
 322 /**
 323 * @brief Cancels processing recognition.
 324 *
 325 * @return 0 on success, otherwise a negative error value
 326 * @retval #STT_FILE_ERROR_NONE Successful
 327 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 328 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
 329 *
 330 * @pre The state should be #STT_FILE_STATE_PROCESSING.
 331 * @post It will invoke stt_file_state_changed_cb(), if you register a callback with stt_file_state_changed_cb(). \n
 332 * If this function succeeds, the STT state will be #STT_FILE_STATE_READY.
 333 *
 334 * @see stt_file_start()
 335 */
 336 int stt_file_cancel(void);
 337
 338
 339 /**
 340 * @brief Retrieves time stamp of current recognition result using callback function.
 341 *
 342 * @param[in] callback The callback function to invoke
 343 * @param[in] user_data The user data to be passed to the callback function
 344 *
 345 * @return 0 on success, otherwise a negative error value
 346 * @retval #STT_FILE_ERROR_NONE Successful
 347 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
 348 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
 349 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 350 *
 351 * @pre This function should be called in stt_file_recognition_result_cb().
 352 * @post This function invokes stt_file_result_time_cb() repeatedly for getting time information.
 353 *
 354 * @see stt_file_result_time_cb()
 355 * @see stt_file_recognition_result_cb()
 356 */
 357 int stt_file_foreach_detailed_result(stt_file_result_time_cb callback, void* user_data);
 358
 359 /**
 360 * @brief Registers a callback function for getting recognition result.
 361 *
 362 * @param[in] callback The callback function to register
 363 * @param[in] user_data The user data to be passed to the callback function
 364 *
 365 * @return 0 on success, otherwise a negative error value
 366 * @retval #STT_FILE_ERROR_NONE Successful
 367 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
 368 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 369 *
 370 * @pre The state should be #STT_FILE_STATE_READY.
 371 *
 372 * @see stt_file_recognition_result_cb()
 373 * @see stt_file_unset_recognition_result_cb()
 374 */
 375 int stt_file_set_recognition_result_cb(stt_file_recognition_result_cb callback, void* user_data);
 376
 377 /**
 378 * @brief Unregisters the callback function.
 379 *
 380 * @return 0 on success, otherwise a negative error value
 381 * @retval #STT_FILE_ERROR_NONE Successful
 382 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 383 *
 384 * @pre The state should be #STT_FILE_STATE_READY.
 385 *
 386 * @see stt_file_set_recognition_result_cb()
 387 */
 388 int stt_file_unset_recognition_result_cb(void);
 389
 390 /**
 391 * @brief Registers a callback function to be called when STT FILE state changes.
 392 *
 393 * @param[in] callback The callback function to register
 394 * @param[in] user_data The user data to be passed to the callback function
 395 *
 396 * @return 0 on success, otherwise a negative error value
 397 * @retval #STT_FILE_ERROR_NONE Successful
 398 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
 399 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 400 *
 401 * @pre The state should be #STT_FILE_STATE_READY.
 402 *
 403 * @see stt_file_state_changed_cb()
 404 * @see stt_file_unset_state_changed_cb()
 405 */
 406 int stt_file_set_state_changed_cb(stt_file_state_changed_cb callback, void* user_data);
 407
 408 /**
 409 * @brief Unregisters the callback function.
 410 *
 411 * @return 0 on success, otherwise a negative error value
 412 * @retval #STT_FILE_ERROR_NONE Successful
 413 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
 414 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
 415 *
 416 * @pre The state should be #STT_FILE_STATE_READY.
 417 *
 418 * @see stt_file_set_state_changed_cb()
 419 */
 420 int stt_file_unset_state_changed_cb(void);
 421
 422
 423 #ifdef __cplusplus
 424 }
 425 #endif
 426
 427 /**
 428  * @}@}
 429  */
 430
 431 #endif /* __STT_FILE_H__ */
 432