include/stt.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
  18 #ifndef __STT_H__
  19 #define __STT_H__
  20
  21
  22 #include <tizen.h>
  23
  24
  25 /**
  26  * @file stt.h
  27  */
  28
  29
  30 /**
  31 * @addtogroup CAPI_UIX_STT_MODULE
  32 * @{
  33 */
  34
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #endif
  40
  41
  42 /**
  43  * @brief Enumeration for error codes.
  44  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  45 */
  46 typedef enum {
  47         STT_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  48         STT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
  49         STT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
  50         STT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  51         STT_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from the STT service */
  52         STT_ERROR_RECORDER_BUSY = TIZEN_ERROR_RESOURCE_BUSY, /**< Device or resource busy */
  53         STT_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Network is down */
  54         STT_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  55         STT_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< STT NOT supported */
  56         STT_ERROR_INVALID_STATE = TIZEN_ERROR_STT | 0x01, /**< Invalid state */
  57         STT_ERROR_INVALID_LANGUAGE = TIZEN_ERROR_STT | 0x02, /**< Invalid language */
  58         STT_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_STT | 0x03, /**< No available engine  */
  59         STT_ERROR_OPERATION_FAILED = TIZEN_ERROR_STT | 0x04, /**< Operation failed  */
  60         STT_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_STT | 0x05, /**< Not supported feature of current engine */
  61         STT_ERROR_RECORDING_TIMED_OUT = TIZEN_ERROR_STT | 0x06, /**< Recording timed out @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  62         STT_ERROR_NO_SPEECH = TIZEN_ERROR_STT | 0x07, /**< No speech while recording @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  63         STT_ERROR_IN_PROGRESS_TO_READY = TIZEN_ERROR_STT | 0x08, /**< Progress to ready is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  64         STT_ERROR_IN_PROGRESS_TO_RECORDING = TIZEN_ERROR_STT | 0x09, /**< Progress to recording is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  65         STT_ERROR_IN_PROGRESS_TO_PROCESSING = TIZEN_ERROR_STT | 0x10, /**< Progress to processing is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  66         STT_ERROR_SERVICE_RESET = TIZEN_ERROR_STT | 0x11 /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  67 } stt_error_e;
  68
  69
  70 /**
  71  * @brief Definition for free form dictation and default type.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73 */
  74 #define STT_RECOGNITION_TYPE_FREE               "stt.recognition.type.FREE"
  75
  76
  77 /**
  78  * @brief Definition for continuous free dictation.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80 */
  81 #define STT_RECOGNITION_TYPE_FREE_PARTIAL       "stt.recognition.type.FREE.PARTIAL"
  82
  83
  84 /**
  85  * @brief Definition for search.
  86  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  87 */
  88 #define STT_RECOGNITION_TYPE_SEARCH             "stt.recognition.type.SEARCH"
  89
  90
  91 /**
  92  * @brief Definition for web search.
  93  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  94 */
  95 #define STT_RECOGNITION_TYPE_WEB_SEARCH         "stt.recognition.type.WEB_SEARCH"
  96
  97
  98 /**
  99  * @brief Definition for map.
 100  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 101 */
 102 #define STT_RECOGNITION_TYPE_MAP                "stt.recognition.type.MAP"
 103
 104
 105 /**
 106  * @brief Definition for none message.
 107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 108 */
 109 #define STT_RESULT_MESSAGE_NONE                 "stt.result.message.none"
 110
 111
 112 /**
 113  * @brief Definition for failed recognition because the speech started too soon.
 114  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 115 */
 116 #define STT_RESULT_MESSAGE_ERROR_TOO_SOON       "stt.result.message.error.too.soon"
 117
 118
 119 /**
 120  * @brief Definition for failed recognition because the speech is too short.
 121  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 122 */
 123 #define STT_RESULT_MESSAGE_ERROR_TOO_SHORT      "stt.result.message.error.too.short"
 124
 125
 126 /**
 127  * @brief Definition for failed recognition because the speech is too long.
 128  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 129 */
 130 #define STT_RESULT_MESSAGE_ERROR_TOO_LONG       "stt.result.message.error.too.long"
 131
 132
 133 /**
 134  * @brief Definition for failed recognition because the speech is too quiet to listen.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136 */
 137 #define STT_RESULT_MESSAGE_ERROR_TOO_QUIET      "stt.result.message.error.too.quiet"
 138
 139
 140 /**
 141  * @brief Definition for failed recognition because the speech is too loud to listen.
 142  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 143 */
 144 #define STT_RESULT_MESSAGE_ERROR_TOO_LOUD       "stt.result.message.error.too.loud"
 145
 146
 147 /**
 148  * @brief Definition for failed recognition because the speech is too fast to listen.
 149  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 150 */
 151 #define STT_RESULT_MESSAGE_ERROR_TOO_FAST       "stt.result.message.error.too.fast"
 152
 153
 154 /**
 155  * @brief Definition for Bluetooth audio-in ID.
 156  * @since_tizen 8.0
 157 */
 158 #define STT_AUDIO_ID_BLUETOOTH          "STT_AUDIO_ID_BLUETOOTH"
 159
 160
 161 /**
 162  * @brief Definition for Wi-Fi audio-in ID.
 163  * @since_tizen 8.0
 164 */
 165 #define STT_AUDIO_ID_WIFI                       "STT_AUDIO_ID_WIFI"
 166
 167
 168 /**
 169  * @brief Definition for none specified audio-in ID.
 170  * @since_tizen 8.0
 171 */
 172 #define STT_AUDIO_ID_NONE                       "STT_AUDIO_ID_NONE"
 173
 174
 175 /**
 176  * @brief Enumeration for state.
 177  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 178 */
 179 typedef enum {
 180         STT_STATE_CREATED = 0, /**< 'CREATED' state */
 181         STT_STATE_READY = 1, /**< 'READY' state */
 182         STT_STATE_RECORDING = 2, /**< 'RECORDING' state */
 183         STT_STATE_PROCESSING = 3 /**< 'PROCESSING' state*/
 184 } stt_state_e;
 185
 186
 187 /**
 188  * @brief Enumeration for result event.
 189  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 190 */
 191 typedef enum {
 192         STT_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the recognition full or last result is ready  */
 193         STT_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the recognition partial result is ready  */
 194         STT_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
 195 } stt_result_event_e;
 196
 197
 198 /**
 199  * @brief Enumeration for result time callback event.
 200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 201 */
 202 typedef enum {
 203         STT_RESULT_TIME_EVENT_BEGINNING = 0, /**< Event when the token is beginning type */
 204         STT_RESULT_TIME_EVENT_MIDDLE = 1, /**< Event when the token is middle type */
 205         STT_RESULT_TIME_EVENT_END = 2 /**< Event when the token is end type */
 206 } stt_result_time_event_e;
 207
 208
 209 /**
 210  * @brief Enumeration for silence detection type.
 211  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 212 */
 213 typedef enum {
 214         STT_OPTION_SILENCE_DETECTION_FALSE = 0, /**< Silence detection type - False */
 215         STT_OPTION_SILENCE_DETECTION_TRUE = 1, /**< Silence detection type - True */
 216         STT_OPTION_SILENCE_DETECTION_AUTO = 2 /**< Silence detection type - Auto */
 217 } stt_option_silence_detection_e;
 218
 219 /**
 220 * @brief Enumeration for speech status.
 221 * @since_tizen 5.5
 222 */
 223 typedef enum {
 224         STT_SPEECH_STATUS_BEGINNING_OF_SPEECH_DETECTED = 0, /**< The beginning Of speech is detected */
 225         STT_SPEECH_STATUS_END_OF_SPEECH_DETECTED /**< The end of speech is detected */
 226 } stt_speech_status_e;
 227
 228
 229 /**
 230 * @brief Enumerations of audio type.
 231 * @since_tizen 8.0
 232 */
 233 typedef enum {
 234         STT_AUDIO_TYPE_RAW_S16 = 0,     /**< Signed 16-bit audio sample */
 235         STT_AUDIO_TYPE_RAW_U8,          /**< Unsigned 8-bit audio sample */
 236 } stt_audio_type_e;
 237
 238 /**
 239  * @brief A structure of STT handle.
 240  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 241 */
 242 typedef struct stt_s *stt_h;
 243
 244
 245 /**
 246  * @brief Called to get the engine information.
 247  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 248  * @param[in] stt The STT handle
 249  * @param[in] engine_id Engine ID
 250  * @param[in] engine_name Engine name
 251  * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines()
 252  * @return @c true to continue with the next iteration of the loop,
 253  *         otherwise @c false to break out of the loop
 254  * @pre stt_foreach_supported_engines() will invoke this callback.
 255  * @see stt_foreach_supported_engines()
 256 */
 257 typedef bool(*stt_supported_engine_cb)(stt_h stt, const char* engine_id, const char* engine_name, void* user_data);
 258
 259
 260 /**
 261  * @brief Called when STT gets the recognition result from the engine.
 262  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 263  * @remarks After stt_stop() is called, silence is detected from recording, or partial result is occurred, this function is called.
 264  * @param[in] stt The STT handle
 265  * @param[in] event The result event
 266  * @param[in] data Result texts
 267  * @param[in] data_count Result text count
 268  * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
 269  * @param[in] user_data The user data passed from the callback registration function
 270  * @pre stt_stop() will invoke this callback if you register it using stt_set_result_cb().
 271  * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT state will be #STT_STATE_READY.
 272  * @see stt_stop()
 273  * @see stt_set_recognition_result_cb()
 274  * @see stt_unset_recognition_result_cb()
 275 */
 276 typedef void (*stt_recognition_result_cb)(stt_h stt, stt_result_event_e event, const char** data, int data_count,
 277                                           const char* msg, void *user_data);
 278
 279
 280 /**
 281  * @brief Called when STT get the result time stamp in free partial type.
 282  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 283  * @param[in] stt The STT handle
 284  * @param[in] index The result index
 285  * @param[in] event The token event
 286  * @param[in] text The result text
 287  * @param[in] start_time The start time of result text
 288  * @param[in] end_time The end time of result text
 289  * @param[in] user_data The user data passed from the foreach function
 290  * @return @c true to continue with the next iteration of the loop
 291  *         otherwise @c false to break out of the loop
 292  * @pre stt_recognition_result_cb() should be called.
 293  * @see stt_recognition_result_cb()
 294 */
 295 typedef bool (*stt_result_time_cb)(stt_h stt, int index, stt_result_time_event_e event, const char* text,
 296                                    long start_time, long end_time, void* user_data);
 297
 298
 299 /**
 300  * @brief Called when the state of STT is changed.
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  * @param[in] stt The STT handle
 303  * @param[in] previous A previous state
 304  * @param[in] current A current state
 305  * @param[in] user_data The user data passed from the callback registration function
 306  * @pre An application registers this callback using stt_set_state_changed_cb() to detect changing state.
 307  * @see stt_set_state_changed_cb()
 308  * @see stt_unset_state_changed_cb()
 309 */
 310 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
 311
 312
 313 /**
 314  * @brief Called when an error occurs.
 315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 316  * @param[in] stt The STT handle
 317  * @param[in] reason The error type (e.g. #STT_ERROR_OUT_OF_NETWORK, #STT_ERROR_IO_ERROR)
 318  * @param[in] user_data The user data passed from the callback registration function
 319  * @pre An application registers this callback using stt_set_error_cb() to detect error.
 320  * @see stt_set_error_cb()
 321  * @see stt_unset_error_cb()
 322 */
 323 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
 324
 325
 326 /**
 327  * @brief Called to retrieve the supported languages.
 328  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 329  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.
 330  * @param[in] stt The STT handle
 331  * @param[in] language The language
 332  * @param[in] user_data The user data passed from the foreach function
 333  * @return @c true to continue with the next iteration of the loop,
 334  *         @c false to break out of the loop
 335  * @pre stt_foreach_supported_languages() will invoke this callback.
 336  * @see stt_foreach_supported_languages()
 337 */
 338 typedef bool (*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
 339
 340
 341 /**
 342  * @brief Called when the default language is changed.
 343  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 344  * @param[in] stt The STT handle
 345  * @param[in] previous_language A previous language
 346  * @param[in] current_language A current language
 347  * @param[in] user_data The user data passed from the callback registration function
 348  * @see stt_set_default_language_changed_cb()
 349 */
 350 typedef void (*stt_default_language_changed_cb)(stt_h stt, const char* previous_language,
 351                                                 const char* current_language, void* user_data);
 352
 353
 354 /**
 355  * @brief Called when the engine is changed.
 356  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 357  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.
 358  * @param[in] stt The STT handle
 359  * @param[in] engine_id Engine ID
 360  * @param[in] language The default language
 361  * @param[in] support_silence Whether the silence detection is supported or not
 362  * @param[in] need_credential The necessity of credential
 363  * @param[in] user_data The user data passed from the callback registration function
 364  * @see stt_set_engine_changed_cb()
 365 */
 366 typedef void (*stt_engine_changed_cb)(stt_h stt, const char* engine_id, const char* language,
 367                                                 bool support_silence, bool need_credential, void* user_data);
 368
 369
 370 /**
 371  * @brief Called when STT engine detects the beginning or end of the speech.
 372  * @since_tizen 5.5
 373  * @param[in] stt The STT handle
 374  * @param[in] status The speech status
 375  * @param[in] user_data The user data passed from the callback registration function
 376  * @see stt_set_speech_status_cb()
 377  */
 378 typedef void (*stt_speech_status_cb)(stt_h stt, stt_speech_status_e status, void *user_data);
 379
 380
 381 /**
 382  * @brief Creates a STT handle.
 383  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 384  * @privlevel public
 385  * @privilege %http://tizen.org/privilege/recorder
 386  * @remarks If the function succeeds, @a stt handle must be released with stt_destroy().
 387  * @param[out] stt The STT handle
 388  * @return @c 0 on success,
 389  *         otherwise a negative error value
 390  * @retval #STT_ERROR_NONE Successful
 391  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 392  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 394  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 395  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 396  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 397  * @see stt_destroy()
 398 */
 399 int stt_create(stt_h* stt);
 400
 401
 402 /**
 403  * @brief Destroys a STT handle.
 404  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 405  * @privlevel public
 406  * @privilege %http://tizen.org/privilege/recorder
 407  * @param[in] stt The STT handle
 408  * @return @c 0 on success,
 409  *         otherwise a negative error value
 410  * @retval #STT_ERROR_NONE Successful
 411  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 412  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 413  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 414  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 415  * @see stt_create()
 416 */
 417 int stt_destroy(stt_h stt);
 418
 419
 420 /**
 421  * @brief Retrieves supported engine information using a callback function.
 422  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 423  * @privlevel public
 424  * @privilege %http://tizen.org/privilege/recorder
 425  * @param[in] stt The STT handle
 426  * @param[in] callback The callback function to invoke
 427  * @param[in] user_data The user data to be passed to the callback function
 428  * @return @c 0 on success,
 429  *         otherwise a negative error value
 430  * @retval #STT_ERROR_NONE Success
 431  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 432  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 433  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 434  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 435  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 436  * @pre The state should be #STT_STATE_CREATED.
 437  * @post This function invokes stt_supported_engine_cb() repeatedly for getting engine information.
 438  * @see stt_supported_engine_cb()
 439 */
 440 int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, void* user_data);
 441
 442
 443 /**
 444  * @brief Gets the current engine ID.
 445  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 446  * @privlevel public
 447  * @privilege %http://tizen.org/privilege/recorder
 448  * @remarks If the function is success, @a engine_id must be released using free().
 449  * @param[in] stt The STT handle
 450  * @param[out] engine_id Engine ID
 451  * @return @c 0 on success,
 452  *         otherwise a negative error value
 453  * @retval #STT_ERROR_NONE Success
 454  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 455  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 456  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 457  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 458  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 459  * @pre The state should be #STT_STATE_CREATED.
 460  * @see stt_set_engine()
 461 */
 462 int stt_get_engine(stt_h stt, char** engine_id);
 463
 464
 465 /**
 466  * @brief Sets the engine ID.
 467  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 468  * @privlevel public
 469  * @privilege %http://tizen.org/privilege/recorder
 470  * @privilege %http://tizen.org/privilege/appmanager.launch
 471  * @remarks A privilege (%http://tizen.org/privilege/appmanager.launch) is necessary since 3.0.
 472  * @param[in] stt The STT handle
 473  * @param[in] engine_id Engine ID
 474  * @return @c 0 on success,
 475  *         otherwise a negative error value
 476  * @retval #STT_ERROR_NONE Success
 477  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 478  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 479  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 480  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 481  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 482  * @pre The state should be #STT_STATE_CREATED.
 483  * @see stt_get_engine()
 484 */
 485 int stt_set_engine(stt_h stt, const char* engine_id);
 486
 487
 488 /**
 489  * @brief Sets the app credential.
 490  * @details Using this API, the application can set a credential.
 491  *          The credential is a key to verify the authorization about using the engine.
 492  *          If the application sets the credential, it will be able to use functions of the engine entirely.
 493  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 494  * @remarks The necessity of the credential depends on the engine. In case of the engine which is basically embedded in Tizen, the credential is not necessary so far.
 495  *          However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
 496  * @param[in] stt The STT handle
 497  * @param[in] credential The app credential
 498  * @return @c 0 on success,
 499  *         otherwise a negative error value
 500  * @retval #STT_ERROR_NONE Success
 501  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 502  * @retval #STT_ERROR_INVALID_STATE Invalid state
 503  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 504  * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
 505  * @see stt_start()
 506 */
 507 int stt_set_credential(stt_h stt, const char* credential);
 508
 509
 510 /**
 511  * @brief Sets the private data to stt engine.
 512  * @details The private data is the setting parameter for applying keys provided by the engine.
 513  *          Using this API, the application can set the private data and use the corresponding key of the engine.
 514  *          For example, if the engine provides 'partial recognition' as a recognition type, the application can set the private data as the following.
 515  *          int ret = stt_set_private_data(stt_h, "recognition_type", "PARTIAL");
 516  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 517  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 518  * @param[in] stt The STT handle
 519  * @param[in] key The field name of private data
 520  * @param[in] data The data for set
 521  * @return @c 0 on success,
 522  *         otherwise a negative error value
 523  * @retval #STT_ERROR_NONE Successful
 524  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 525  * @retval #STT_ERROR_INVALID_STATE Invalid state
 526  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 527  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
 528  * @pre The state should be #STT_STATE_READY.
 529  * @see stt_get_private_data()
 530 */
 531 int stt_set_private_data(stt_h stt, const char* key, const char* data);
 532
 533
 534 /**
 535  * @brief Gets the private data from stt engine.
 536  * @details The private data is the information provided by the engine.
 537  *          Using this API, the application can get the private data which corresponds to the key from the engine.
 538  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 539  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 540  * @remarks The @a data must be released using free() when it is no longer required.
 541  * @param[in] stt The STT handle
 542  * @param[in] key The field name of private data
 543  * @param[out] data The data field of private data
 544  * @return @c 0 on success,
 545  *         otherwise a negative error value
 546  * @retval #STT_ERROR_NONE Successful
 547  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 548  * @retval #STT_ERROR_INVALID_STATE Invalid state
 549  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 550  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
 551  * @pre The state should be #STT_STATE_READY.
 552  * @see stt_set_private_data()
 553 */
 554 int stt_get_private_data(stt_h stt, const char* key, char** data);
 555
 556
 557 /**
 558  * @brief Connects the STT service asynchronously.
 559  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 560  * @privlevel public
 561  * @privilege %http://tizen.org/privilege/recorder
 562  * @param[in] stt The STT handle
 563  * @return @c 0 on success,
 564  *         otherwise a negative error value
 565  * @retval #STT_ERROR_NONE Successful
 566  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 567  * @retval #STT_ERROR_INVALID_STATE Invalid state
 568  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 569  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 570  * @pre The state should be #STT_STATE_CREATED.
 571  * @post If this function is successful, the STT state will be #STT_STATE_READY.
 572  *       If this function is failed, the error callback is called. (e.g. #STT_ERROR_ENGINE_NOT_FOUND)
 573  * @see stt_unprepare()
 574 */
 575 int stt_prepare(stt_h stt);
 576
 577
 578 /**
 579  * @brief Disconnects the STT service.
 580  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 581  * @privlevel public
 582  * @privilege %http://tizen.org/privilege/recorder
 583  * @param[in] stt The STT handle
 584  * @return @c 0 on success,
 585  *         otherwise a negative error value
 586  * @retval #STT_ERROR_NONE Successful
 587  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 588  * @retval #STT_ERROR_INVALID_STATE Invalid state
 589  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 590  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 591  * @pre The state should be #STT_STATE_READY.
 592  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 593  * @see stt_prepare()
 594 */
 595 int stt_unprepare(stt_h stt);
 596
 597
 598 /**
 599  * @brief Retrieves all supported languages of current engine using callback function.
 600  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 601  * @privlevel public
 602  * @privilege %http://tizen.org/privilege/recorder
 603  * @param[in] stt The STT handle
 604  * @param[in] callback The callback function to invoke
 605  * @param[in] user_data The user data to be passed to the callback function
 606  * @return @c 0 on success,
 607  *         otherwise a negative error value
 608  * @retval #STT_ERROR_NONE Successful
 609  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 610  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 611  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 612  * @retval #STT_ERROR_ENGINE_NOT_FOUND No available engine
 613  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 614  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 615  * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
 616  * @see stt_supported_language_cb()
 617  * @see stt_get_default_language()
 618 */
 619 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
 620
 621
 622 /**
 623  * @brief Gets the default language set by the user.
 624  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 625  * @privlevel public
 626  * @privilege %http://tizen.org/privilege/recorder
 627  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code.
 628  *          For example, "ko_KR" for Korean, "en_US" for American English.
 629  *          If the function succeeds, @a language must be released using free() when it is no longer required.
 630  * @param[in] stt The STT handle
 631  * @param[out] language The language
 632  * @return @c 0 on success,
 633  *         otherwise a negative error value
 634  * @retval #STT_ERROR_NONE Successful
 635  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 636  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 637  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 638  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 639  * @see stt_foreach_supported_languages()
 640 */
 641 int stt_get_default_language(stt_h stt, char** language);
 642
 643
 644 /**
 645  * @brief Gets the current STT state.
 646  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 647  * @privlevel public
 648  * @privilege %http://tizen.org/privilege/recorder
 649  * @param[in] stt The STT handle
 650  * @param[out] state The current STT state
 651  * @return @c 0 on success,
 652  *         otherwise a negative error value
 653  * @retval #STT_ERROR_NONE Successful
 654  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 655  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 656  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 657  * @see stt_start()
 658  * @see stt_stop()
 659  * @see stt_cancel()
 660  * @see stt_state_changed_cb()
 661 */
 662 int stt_get_state(stt_h stt, stt_state_e* state);
 663
 664
 665 /**
 666  * @brief Gets the current error message.
 667  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 668  * @remarks This function should be called during an stt error callback. If not, the error as operation failure will be returned.
 669  *          If the function succeeds, @a err_msg must be released using free() when it is no longer required.
 670  * @param[in] stt The STT handle
 671  * @param[out] err_msg The current error message
 672  * @return @c 0 on success,
 673  *         otherwise a negative error value
 674  * @retval #STT_ERROR_NONE Successful
 675  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 676  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 677  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 678  * @see stt_set_error_cb()
 679  * @see stt_unset_error_cb()
 680 */
 681 int stt_get_error_message(stt_h stt, char** err_msg);
 682
 683
 684 /**
 685  * @brief Checks whether the recognition type is supported.
 686  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 687  * @privlevel public
 688  * @privilege %http://tizen.org/privilege/recorder
 689  * @param[in] stt The STT handle
 690  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 691  * @param[out] support The result status @c true = supported,
 692  *                     @c false = not supported
 693  * @return @c 0 on success,
 694  *         otherwise a negative error value
 695  * @retval #STT_ERROR_NONE Successful
 696  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 697  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 698  * @retval #STT_ERROR_INVALID_STATE Invalid state
 699  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 700  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 701  * @pre The state should be #STT_STATE_READY.
 702 */
 703 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
 704
 705
 706 /**
 707  * @brief Sets the silence detection.
 708  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 709  * @privlevel public
 710  * @privilege %http://tizen.org/privilege/recorder
 711  * @param[in] stt The STT handle
 712  * @param[in] type The option type
 713  * @return @c 0 on success,
 714  *         otherwise a negative error value
 715  * @retval #STT_ERROR_NONE Successful
 716  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 717  * @retval #STT_ERROR_INVALID_STATE Invalid state
 718  * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
 719  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 720  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 721  * @pre The state should be #STT_STATE_READY.
 722 */
 723 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
 724
 725
 726 /**
 727  * @brief Sets the sound to start recording.
 728  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 729  * @privlevel public
 730  * @privilege %http://tizen.org/privilege/recorder
 731  * @remarks Sound file type should be wav type.
 732  * @param[in] stt The STT handle
 733  * @param[in] filename The sound file path
 734  * @return @c 0 on success,
 735  *         otherwise a negative error value
 736  * @retval #STT_ERROR_NONE Successful
 737  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 738  * @retval #STT_ERROR_INVALID_STATE Invalid state
 739  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 740  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 741  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 742  * @pre The state should be #STT_STATE_READY.
 743 */
 744 int stt_set_start_sound(stt_h stt, const char* filename);
 745
 746
 747 /**
 748  * @brief Unsets the sound to start recording.
 749  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 750  * @privlevel public
 751  * @privilege %http://tizen.org/privilege/recorder
 752  * @param[in] stt The STT handle
 753  * @return @c 0 on success,
 754  *         otherwise a negative error value
 755  * @retval #STT_ERROR_NONE Successful
 756  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 757  * @retval #STT_ERROR_INVALID_STATE Invalid state
 758  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 759  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 760  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 761  * @pre The state should be #STT_STATE_READY.
 762 */
 763 int stt_unset_start_sound(stt_h stt);
 764
 765
 766 /**
 767  * @brief Sets the sound to stop recording.
 768  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 769  * @privlevel public
 770  * @privilege %http://tizen.org/privilege/recorder
 771  * @remarks Sound file type should be wav type.
 772  * @param[in] stt The STT handle
 773  * @param[in] filename The sound file path
 774  * @return @c 0 on success,
 775  *         otherwise a negative error value
 776  * @retval #STT_ERROR_NONE Successful
 777  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 778  * @retval #STT_ERROR_INVALID_STATE Invalid state
 779  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 780  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 781  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 782  * @pre The state should be #STT_STATE_READY.
 783 */
 784 int stt_set_stop_sound(stt_h stt, const char* filename);
 785
 786
 787 /**
 788  * @brief Unsets the sound to stop recording.
 789  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 790  * @privlevel public
 791  * @privilege %http://tizen.org/privilege/recorder
 792  * @param[in] stt The STT handle
 793  * @return @c 0 on success,
 794  *         otherwise a negative error value
 795  * @retval #STT_ERROR_NONE Successful
 796  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 797  * @retval #STT_ERROR_INVALID_STATE Invalid state
 798  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 799  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 800  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 801  * @pre The state should be #STT_STATE_READY.
 802 */
 803 int stt_unset_stop_sound(stt_h stt);
 804
 805
 806 /**
 807  * @brief Starts recording and recognition asynchronously.
 808  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 809  * @privlevel public
 810  * @privilege %http://tizen.org/privilege/recorder
 811  * @remarks This function starts recording in the STT service and sending recording data to engine.
 812  *          This work continues until stt_stop(), stt_cancel() or silence detected by engine.
 813  * @param[in] stt The STT handle
 814  * @param[in] language The language selected from stt_foreach_supported_languages()
 815  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 816  * @return @c 0 on success,
 817  *         otherwise a negative error value
 818  * @retval #STT_ERROR_NONE Successful
 819  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 820  * @retval #STT_ERROR_INVALID_STATE Invalid state
 821  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 822  * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
 823  * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
 824  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 825  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 826  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 827  * @pre The state should be #STT_STATE_READY.
 828  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 829  *       If this function succeeds, the STT state will be #STT_STATE_RECORDING.
 830  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_RECORDING.
 831  * @see stt_stop()
 832  * @see stt_cancel()
 833  * @see stt_state_changed_cb()
 834 */
 835 int stt_start(stt_h stt, const char* language, const char* type);
 836
 837
 838 /**
 839  * @brief Finishes the recording and starts recognition processing in engine asynchronously.
 840  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 841  * @privlevel public
 842  * @privilege %http://tizen.org/privilege/recorder
 843  * @remarks This function can only stop recording started by stt_start().
 844  * @param[in] stt The STT handle
 845  * @return @c 0 on success,
 846  *         otherwise a negative error value
 847  * @retval #STT_ERROR_NONE Successful
 848  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 849  * @retval #STT_ERROR_INVALID_STATE Invalid state
 850  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 851  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 852  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 853  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
 854  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 855  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
 856  * @pre The state should be #STT_STATE_RECORDING.
 857  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 858  *       If this function succeeds, the STT state will be #STT_STATE_PROCESSING.
 859  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_PROCESSING.
 860  *       If you call this function after starting recording by stt_start_audio_streaming(), you will receive #STT_ERROR_OPERATION_FAILED.
 861  *       After processing of engine, stt_result_cb() is called.
 862  * @see stt_start()
 863  * @see stt_cancel()
 864  * @see stt_state_changed_cb()
 865 */
 866 int stt_stop(stt_h stt);
 867
 868
 869 /**
 870  * @brief Cancels processing recognition and recording asynchronously.
 871  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 872  * @privlevel public
 873  * @privilege %http://tizen.org/privilege/recorder
 874  * @remarks This function cancels recording and engine cancels recognition processing.
 875  *          After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
 876  * @param[in] stt The STT handle
 877  * @return @c 0 on success,
 878  *         otherwise a negative error value
 879  * @retval #STT_ERROR_NONE Successful
 880  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 881  * @retval #STT_ERROR_INVALID_STATE Invalid state
 882  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 883  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 884  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 885  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
 886  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 887  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
 888  * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
 889  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 890  *       If this function succeeds, the STT state will be #STT_STATE_READY.
 891  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_READY.
 892  * @see stt_start()
 893  * @see stt_stop()
 894  * @see stt_state_changed_cb()
 895 */
 896 int stt_cancel(stt_h stt);
 897
 898
 899 /**
 900  * @brief Gets the microphone volume during recording.
 901  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 902  * @privlevel public
 903  * @privilege %http://tizen.org/privilege/recorder
 904  * @param[in] stt The STT handle
 905  * @param[out] volume Recording volume
 906  * @return @c 0 on success,
 907  *         otherwise a negative error value
 908  * @retval #STT_ERROR_NONE Successful
 909  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 910  * @retval #STT_ERROR_INVALID_STATE Invalid state
 911  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 912  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 913  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 914  * @pre The state should be #STT_STATE_RECORDING.
 915  * @see stt_start()
 916 */
 917 int stt_get_recording_volume(stt_h stt, float* volume);
 918
 919
 920 /**
 921  * @brief Retrieves the time stamp of the current recognition result using the callback function.
 922  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 923  * @privlevel public
 924  * @privilege %http://tizen.org/privilege/recorder
 925  * @remarks This function should be called in stt_recognition_result_cb().
 926  *          After stt_recognition_result_cb(), result data is NOT valid.
 927  * @param[in] stt The STT handle
 928  * @param[in] callback The callback function to invoke
 929  * @param[in] user_data The user data to be passed to the callback function
 930  * @return @c 0 on success,
 931  *         otherwise a negative error value
 932  * @retval #STT_ERROR_NONE Successful
 933  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 934  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 935  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 936  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 937  * @pre This function should be called in stt_recognition_result_cb().
 938  * @post This function invokes stt_result_time_cb() repeatedly for getting time information.
 939  * @see stt_result_time_cb()
 940  * @see stt_recognition_result_cb()
 941 */
 942 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
 943
 944
 945 /**
 946  * @brief Sets a callback function to get the recognition result.
 947  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 948  * @privlevel public
 949  * @privilege %http://tizen.org/privilege/recorder
 950  * @param[in] stt The STT handle
 951  * @param[in] callback The callback function to register
 952  * @param[in] user_data The user data to be passed to the callback function
 953  * @return @c 0 on success,
 954  *         otherwise a negative error value
 955  * @retval #STT_ERROR_NONE Successful
 956  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 957  * @retval #STT_ERROR_INVALID_STATE Invalid state
 958  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 959  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 960  * @pre The state should be #STT_STATE_CREATED.
 961  * @see stt_recognition_result_cb()
 962  * @see stt_unset_recognition_result_cb()
 963 */
 964 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
 965
 966
 967 /**
 968  * @brief Unsets the callback function.
 969  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 970  * @privlevel public
 971  * @privilege %http://tizen.org/privilege/recorder
 972  * @param[in] stt The STT handle
 973  * @return @c 0 on success,
 974  *         otherwise a negative error value
 975  * @retval #STT_ERROR_NONE Successful
 976  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 977  * @retval #STT_ERROR_INVALID_STATE Invalid state
 978  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 979  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 980  * @pre The state should be #STT_STATE_CREATED.
 981  * @see stt_set_recognition_result_cb()
 982 */
 983 int stt_unset_recognition_result_cb(stt_h stt);
 984
 985
 986 /**
 987  * @brief Sets a callback function to be called when STT state changes.
 988  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 989  * @privlevel public
 990  * @privilege %http://tizen.org/privilege/recorder
 991  * @param[in] stt The STT handle
 992  * @param[in] callback The callback function to register
 993  * @param[in] user_data The user data to be passed to the callback function
 994  * @return @c 0 on success,
 995  *         otherwise a negative error value
 996  * @retval #STT_ERROR_NONE Successful
 997  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 998  * @retval #STT_ERROR_INVALID_STATE Invalid state
 999  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1000  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1001  * @pre The state should be #STT_STATE_CREATED.
1002  * @see stt_state_changed_cb()
1003  * @see stt_unset_state_changed_cb()
1004 */
1005 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
1006
1007
1008 /**
1009  * @brief Unsets the callback function.
1010  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1011  * @privlevel public
1012  * @privilege %http://tizen.org/privilege/recorder
1013  * @param[in] stt The STT handle
1014  * @return @c 0 on success,
1015  *         otherwise a negative error value
1016  * @retval #STT_ERROR_NONE Successful
1017  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1018  * @retval #STT_ERROR_INVALID_STATE Invalid state
1019  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1020  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1021  * @pre The state should be #STT_STATE_CREATED.
1022  * @see stt_set_state_changed_cb()
1023 */
1024 int stt_unset_state_changed_cb(stt_h stt);
1025
1026
1027 /**
1028  * @brief Sets a callback function to be called when an error occurred.
1029  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1030  * @privlevel public
1031  * @privilege %http://tizen.org/privilege/recorder
1032  * @param[in] stt The STT handle
1033  * @param[in] callback The callback function to register
1034  * @param[in] user_data The user data to be passed to the callback function
1035  * @return @c 0 on success,
1036  *         otherwise a negative error value
1037  * @retval #STT_ERROR_NONE Successful
1038  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1039  * @retval #STT_ERROR_INVALID_STATE Invalid state
1040  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1041  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1042  * @pre The state should be #STT_STATE_CREATED.
1043  * @see stt_error_cb()
1044  * @see stt_unset_error_cb()
1045 */
1046 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
1047
1048
1049 /**
1050  * @brief Unsets the callback function.
1051  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1052  * @privlevel public
1053  * @privilege %http://tizen.org/privilege/recorder
1054  * @param[in] stt The STT handle
1055  * @return @c 0 on success,
1056  *         otherwise a negative error value
1057  * @retval #STT_ERROR_NONE Successful
1058  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1059  * @retval #STT_ERROR_INVALID_STATE Invalid state
1060  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1061  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1062  * @pre The state should be #STT_STATE_CREATED.
1063  * @see stt_set_error_cb()
1064 */
1065 int stt_unset_error_cb(stt_h stt);
1066
1067
1068 /**
1069  * @brief Sets a callback function to detect the default language change.
1070  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1071  * @privlevel public
1072  * @privilege %http://tizen.org/privilege/recorder
1073  * @param[in] stt The STT handle
1074  * @param[in] callback The callback function to register
1075  * @param[in] user_data The user data to be passed to the callback function
1076  * @return @c 0 on success,
1077  *         otherwise a negative error value
1078  * @retval #STT_ERROR_NONE Successful
1079  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1080  * @retval #STT_ERROR_INVALID_STATE Invalid state
1081  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1082  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1083  * @pre The state should be #STT_STATE_CREATED.
1084  * @see stt_default_language_changed_cb()
1085  * @see stt_unset_default_language_changed_cb()
1086 */
1087 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
1088
1089
1090 /**
1091  * @brief Unsets the callback function.
1092  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1093  * @privlevel public
1094  * @privilege %http://tizen.org/privilege/recorder
1095  * @param[in] stt The STT handle
1096  * @return @c 0 on success,
1097  *         otherwise a negative error value
1098  * @retval #STT_ERROR_NONE Successful
1099  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1100  * @retval #STT_ERROR_INVALID_STATE Invalid state
1101  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1102  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1103  * @pre The state should be #STT_STATE_CREATED.
1104  * @see stt_set_default_language_changed_cb()
1105 */
1106 int stt_unset_default_language_changed_cb(stt_h stt);
1107
1108
1109 /**
1110  * @brief Sets a callback function to detect the engine change.
1111  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1112  * @param[in] stt The STT handle
1113  * @param[in] callback The callback function to register
1114  * @param[in] user_data The user data to be passed to the callback function
1115  * @return @c 0 on success,
1116  *         otherwise a negative error value
1117  * @retval #STT_ERROR_NONE Successful
1118  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1119  * @retval #STT_ERROR_INVALID_STATE Invalid state
1120  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1121  * @pre The state should be #STT_STATE_CREATED.
1122  * @see stt_engine_changed_cb()
1123  * @see stt_unset_engine_changed_cb()
1124 */
1125 int stt_set_engine_changed_cb(stt_h stt, stt_engine_changed_cb callback, void* user_data);
1126
1127
1128 /**
1129  * @brief Unsets the callback function.
1130  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1131  * @param[in] stt The STT handle
1132  * @return @c 0 on success,
1133  *         otherwise a negative error value
1134  * @retval #STT_ERROR_NONE Successful
1135  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1136  * @retval #STT_ERROR_INVALID_STATE Invalid state
1137  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1138  * @pre The state should be #STT_STATE_CREATED.
1139  * @see stt_set_engine_changed_cb()
1140 */
1141 int stt_unset_engine_changed_cb(stt_h stt);
1142
1143
1144 /**
1145  * @brief Sets a callback function to detect the speech status is changed.
1146  * @since_tizen 5.5
1147  * @privlevel public
1148  * @privilege %http://tizen.org/privilege/recorder
1149  * @param[in] stt The STT handle
1150  * @param[in] callback The callback function to register
1151  * @param[in] user_data The user data to be passed to the callback function
1152  * @return @c 0 on success,
1153  *         otherwise a negative error value
1154  * @retval #STT_ERROR_NONE Successful
1155  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1156  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1157  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1158  * @retval #STT_ERROR_INVALID_STATE Invalid state
1159  * @pre The state should be #STT_STATE_CREATED.
1160  * @see stt_speech_status_cb()
1161  * @see stt_unset_speech_status_cb()
1162 */
1163 int stt_set_speech_status_cb(stt_h stt, stt_speech_status_cb callback, void* user_data);
1164
1165
1166 /**
1167  * @brief Unsets the callback function to detect the speech status is changed.
1168  * @since_tizen 5.5
1169  * @privlevel public
1170  * @privilege %http://tizen.org/privilege/recorder
1171  * @param[in] stt The STT handle
1172  * @return @c 0 on success,
1173  *         otherwise a negative error value
1174  * @retval #STT_ERROR_NONE Successful
1175  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1176  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1177  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1178  * @retval #STT_ERROR_INVALID_STATE Invalid state
1179  * @pre The state should be #STT_STATE_CREATED.
1180  * @see stt_set_speech_status_cb()
1181 */
1182 int stt_unset_speech_status_cb(stt_h stt);
1183
1184
1185 /**
1186  * @brief Starts audio streaming and recognition asynchronously.
1187  * @since_tizen 8.0
1188  * @remarks This function starts audio streaming in the STT service.
1189  *          This work continues until stt_stop_audio_streaming(), stt_cancel() or silence detected by engine.
1190  * @param[in] stt The STT handle
1191  * @param[in] language The language selected from stt_foreach_supported_languages() (e.g. #NULL(Automatic), 'en_US')
1192  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
1193  * @return @c 0 on success,
1194  *         otherwise a negative error value
1195  * @retval #STT_ERROR_NONE Successful
1196  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1197  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1198  * @retval #STT_ERROR_INVALID_STATE Invalid state
1199  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
1200  * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
1201  * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
1202  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
1203  * @pre The state should be #STT_STATE_READY.
1204  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
1205  *       If this function succeeds, the STT state will be #STT_STATE_RECORDING.
1206  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_RECORDING.
1207  * @see stt_stop_audio_streaming()
1208  * @see stt_send_audio_streaming()
1209  * @see stt_cancel()
1210  * @see stt_state_changed_cb()
1211 */
1212 int stt_start_audio_streaming(stt_h stt, const char* language, const char* type);
1213
1214
1215 /**
1216  * @brief Sends audio data to STT engine.
1217  * @since_tizen 8.0
1218  * @remarks The audio format of @a data should satisfy the audio format from stt_get_audio_format().
1219  * @param[in] stt The STT handle
1220  * @param[in] data The raw PCM data
1221  * @param[in] data_size The number of bytes of @a data
1222  * @return @c 0 on success,
1223  *         otherwise a negative error value
1224  * @retval #STT_ERROR_NONE Successful
1225  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1226  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1227  * @retval #STT_ERROR_INVALID_STATE Invalid state
1228  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
1229  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
1230  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
1231  * @pre The state should be #STT_STATE_RECORDING.
1232  * @post If you call this function after starting recording by stt_start(), you will receive #STT_ERROR_OPERATION_FAILED.
1233  * @see stt_start_audio_streaming()
1234  * @see stt_stop_audio_streaming()
1235  * @see stt_cancel()
1236  * @see stt_get_audio_format()
1237 */
1238 int stt_send_audio_streaming(stt_h stt, const char* data, size_t data_size);
1239
1240
1241 /**
1242  * @brief Finishes the audio streaming and starts recognition processing in engine asynchronously.
1243  * @since_tizen 8.0
1244  * @remarks This function can only stop recording started by stt_start_audio_streaming().
1245  * @param[in] stt The STT handle
1246  * @return @c 0 on success,
1247  *         otherwise a negative error value
1248  * @retval #STT_ERROR_NONE Successful
1249  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1250  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1251  * @retval #STT_ERROR_INVALID_STATE Invalid state
1252  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
1253  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
1254  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
1255  * @pre The state should be #STT_STATE_RECORDING.
1256  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
1257  *       If this function succeeds, the STT state will be #STT_STATE_PROCESSING.
1258  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_PROCESSING.
1259  *       If you call this function after starting recording by stt_start(), you will receive #STT_ERROR_OPERATION_FAILED.
1260  *       After processing of engine, stt_result_cb() is called.
1261  * @see stt_start_audio_streaming()
1262  * @see stt_cancel()
1263  * @see stt_state_changed_cb()
1264 */
1265 int stt_stop_audio_streaming(stt_h stt);
1266
1267
1268 /**
1269  * @brief Gets the recognizable audio format information.
1270  * @since_tizen 8.0
1271  * @param[in] stt The STT handle
1272  * @param[out] type The audio type
1273  * @param[out] rate The sample rates
1274  * @param[out] num_of_channels The number of channels
1275  * @return @c 0 on success,
1276  *         otherwise a negative error value
1277  * @retval #STT_ERROR_NONE Successful
1278  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1279  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1280  * @retval #STT_ERROR_INVALID_STATE Invalid state
1281  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
1282  * @pre The state should be #STT_STATE_READY.
1283  * @see stt_send_audio_streaming()
1284 */
1285 int stt_get_audio_format(stt_h stt, stt_audio_type_e* type, int* rate, int* num_of_channels);
1286
1287
1288 /**
1289  * @brief Sets an ID of audio-in.
1290  * @since_tizen 8.0
1291  * @privlevel public
1292  * @privilege %http://tizen.org/privilege/recorder
1293  * @param[in] stt The STT handle
1294  * @param[in] audio_id The audio id (e.g. #STT_AUDIO_ID_BLUETOOTH, #STT_AUDIO_ID_WIFI, #STT_AUDIO_ID_NONE or USB device ID)
1295  * @return @c 0 on success,
1296  *         otherwise a negative error value
1297  * @retval #STT_ERROR_NONE Successful
1298  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1299  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1300  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1301  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
1302  * @retval #STT_ERROR_INVALID_STATE Invalid state
1303  * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
1304  * @see stt_get_audio_id()
1305  */
1306 int stt_set_audio_id(stt_h stt, const char *audio_id);
1307
1308
1309 /**
1310  * @brief Gets an ID of audio-in.
1311  * @since_tizen 8.0
1312  * @privlevel public
1313  * @privilege %http://tizen.org/privilege/recorder
1314  * @remarks @a audio_id must be released using free() when it is no longer required.
1315  * @param[in] stt The STT handle
1316  * @param[out] audio_id The audio id (e.g. #STT_AUDIO_ID_BLUETOOTH, #STT_AUDIO_ID_WIFI, #STT_AUDIO_ID_NONE or USB device ID)
1317  * @return @c 0 on success,
1318  *         otherwise a negative error value
1319  * @retval #STT_ERROR_NONE Successful
1320  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1321  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1322  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1323  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
1324  * @retval #STT_ERROR_INVALID_STATE Invalid state
1325  * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
1326  * @see stt_set_audio_id()
1327  */
1328 int stt_get_audio_id(stt_h stt, char **audio_id);
1329
1330
1331 #ifdef __cplusplus
1332 }
1333 #endif
1334
1335
1336 /**
1337  * @}
1338  */
1339
1340
1341 #endif /* __STT_H__ */
1342