2 * Copyright (c) 2011-2014 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
27 * @addtogroup CAPI_UIX_STT_MODULE
37 * @brief Enumerations for error codes.
38 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
41 STT_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
42 STT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
43 STT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
44 STT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
45 STT_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from the daemon */
46 STT_ERROR_RECORDER_BUSY = TIZEN_ERROR_RESOURCE_BUSY, /**< Device or resource busy */
47 STT_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Network is down */
48 STT_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,/**< Permission denied */
49 STT_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< STT NOT supported */
50 STT_ERROR_INVALID_STATE = TIZEN_ERROR_STT | 0x01, /**< Invalid state */
51 STT_ERROR_INVALID_LANGUAGE = TIZEN_ERROR_STT | 0x02, /**< Invalid language */
52 STT_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_STT | 0x03, /**< No available engine */
53 STT_ERROR_OPERATION_FAILED = TIZEN_ERROR_STT | 0x04, /**< Operation failed */
54 STT_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_STT | 0x05, /**< Not supported feature of current engine */
55 STT_ERROR_NO_SPEECH = TIZEN_ERROR_STT | 0x06 /**< No speech while recording */
59 * @brief Definition for free form dictation and default type.
60 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
62 #define STT_RECOGNITION_TYPE_FREE "stt.recognition.type.FREE"
65 * @brief Definition for continuous free dictation.
66 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
68 #define STT_RECOGNITION_TYPE_FREE_PARTIAL "stt.recognition.type.FREE.PARTIAL"
71 * @brief Definition for search.
72 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
74 #define STT_RECOGNITION_TYPE_SEARCH "stt.recognition.type.SEARCH"
77 * @brief Definition for web search.
78 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
80 #define STT_RECOGNITION_TYPE_WEB_SEARCH "stt.recognition.type.WEB_SEARCH"
83 * @brief Definition for map.
84 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
86 #define STT_RECOGNITION_TYPE_MAP "stt.recognition.type.MAP"
89 * @brief Definition for none message.
90 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
92 #define STT_RESULT_MESSAGE_NONE "stt.result.message.none"
95 * @brief Definition for failed recognition because the speech started too soon.
96 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
98 #define STT_RESULT_MESSAGE_ERROR_TOO_SOON "stt.result.message.error.too.soon"
101 * @brief Definition for failed recognition because the speech is too short.
102 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
104 #define STT_RESULT_MESSAGE_ERROR_TOO_SHORT "stt.result.message.error.too.short"
107 * @brief Definition for failed recognition because the speech is too long.
108 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110 #define STT_RESULT_MESSAGE_ERROR_TOO_LONG "stt.result.message.error.too.long"
113 * @brief Definition for failed recognition because the speech is too quiet to listen.
114 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
116 #define STT_RESULT_MESSAGE_ERROR_TOO_QUIET "stt.result.message.error.too.quiet"
119 * @brief Definition for failed recognition because the speech is too loud to listen.
120 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
122 #define STT_RESULT_MESSAGE_ERROR_TOO_LOUD "stt.result.message.error.too.loud"
125 * @brief Definition for failed recognition because the speech is too fast to listen.
126 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
128 #define STT_RESULT_MESSAGE_ERROR_TOO_FAST "stt.result.message.error.too.fast"
132 * @brief Enumeration for state.
133 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
136 STT_STATE_CREATED = 0, /**< 'CREATED' state */
137 STT_STATE_READY = 1, /**< 'READY' state */
138 STT_STATE_RECORDING = 2, /**< 'RECORDING' state */
139 STT_STATE_PROCESSING = 3 /**< 'PROCESSING' state*/
143 * @brief Enumeration for result event.
144 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
147 STT_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the recognition full or last result is ready */
148 STT_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the recognition partial result is ready */
149 STT_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
150 } stt_result_event_e;
153 * @brief Enumeration for result time callback event.
154 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
157 STT_RESULT_TIME_EVENT_BEGINNING = 0, /**< Event when the token is beginning type */
158 STT_RESULT_TIME_EVENT_MIDDLE = 1, /**< Event when the token is middle type */
159 STT_RESULT_TIME_EVENT_END = 2 /**< Event when the token is end type */
160 } stt_result_time_event_e;
163 * @brief Enumeration for silence detection type.
164 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
167 STT_OPTION_SILENCE_DETECTION_FALSE = 0, /**< Silence detection type - False */
168 STT_OPTION_SILENCE_DETECTION_TRUE = 1, /**< Silence detection type - True */
169 STT_OPTION_SILENCE_DETECTION_AUTO = 2 /**< Silence detection type - Auto */
170 } stt_option_silence_detection_e;
173 * @brief A structure of STT handler.
174 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
176 typedef struct stt_s *stt_h;
179 * @brief Called to get the engine information.
180 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
182 * @param[in] engine_id Engine id
183 * @param[in] engine_name Engine name
184 * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines()
186 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
187 * @pre stt_foreach_supported_engines() will invoke this callback.
189 * @see stt_foreach_supported_engines()
191 typedef bool(*stt_supported_engine_cb)(stt_h stt, const char* engine_id, const char* engine_name, void* user_data);
194 * @brief Called when STT gets the recognition result from the engine.
195 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
197 * @remarks After stt_stop() is called, silence is detected from recording, or partial result is occured,
198 * this function is called.
200 * @param[in] stt The STT handle
201 * @param[in] event The result event
202 * @param[in] data Result texts
203 * @param[in] data_count Result text count
204 * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
205 * @param[in] user_data The user data passed from the callback registration function
207 * @pre stt_stop() will invoke this callback if you register it using stt_set_result_cb().
208 * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT state will be #STT_STATE_READY.
211 * @see stt_set_recognition_result_cb()
212 * @see stt_unset_recognition_result_cb()
214 typedef void (*stt_recognition_result_cb)(stt_h stt, stt_result_event_e event, const char** data, int data_count,
215 const char* msg, void *user_data);
218 * @brief Called when STT get the result time stamp in free partial type.
219 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
221 * @param[in] stt The STT handle
222 * @param[in] index The result index
223 * @param[in] event The token event
224 * @param[in] text The result text
225 * @param[in] start_time The start time of result text
226 * @param[in] end_time The end time of result text
227 * @param[in] user_data The user data passed from the foreach function
229 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
231 * @pre stt_recognition_result_cb() should be called.
233 * @see stt_recognition_result_cb()
235 typedef bool (*stt_result_time_cb)(stt_h stt, int index, stt_result_time_event_e event, const char* text,
236 long start_time, long end_time, void* user_data);
239 * @brief Called when the state of STT is changed.
240 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
242 * @param[in] stt The STT handle
243 * @param[in] previous A previous state
244 * @param[in] current A current state
245 * @param[in] user_data The user data passed from the callback registration function
247 * @pre An application registers this callback using stt_set_state_changed_cb() to detect changing state.
249 * @see stt_set_state_changed_cb()
250 * @see stt_unset_state_changed_cb()
252 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
255 * @brief Called when an error occurs.
256 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
258 * @param[in] stt The STT handle
259 * @param[in] reason The error type (e.g. #STT_ERROR_OUT_OF_NETWORK, #STT_ERROR_IO_ERROR)
260 * @param[in] user_data The user data passed from the callback registration function
262 * @pre An application registers this callback using stt_set_error_cb() to detect error.
264 * @see stt_set_error_cb()
265 * @see stt_unset_error_cb()
267 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
270 * @brief Called to retrieve the supported languages.
271 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
272 * @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.
274 * @param[in] stt The STT handle
275 * @param[in] language The language
276 * @param[in] user_data The user data passed from the foreach function
278 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
279 * @pre stt_foreach_supported_languages() will invoke this callback.
281 * @see stt_foreach_supported_languages()
283 typedef bool (*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
286 * @brief Called when the default language is changed.
287 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
289 * @param[in] stt The STT handle
290 * @param[in] previous_language A previous language
291 * @param[in] current_language A current language
292 * @param[in] user_data The user data passed from the callback registration function
294 * @see stt_set_default_language_changed_cb()
296 typedef void (*stt_default_language_changed_cb)(stt_h stt, const char* previous_language,
297 const char* current_language, void* user_data);
300 * @brief Called when the engine is changed.
303 * @param[in] stt The STT handle
304 * @param[in] engine_id Engine id
305 * @param[in] language The default language
306 * @param[in] support_silence support silence detection
307 * @param[in] need_credential necessity of credential
308 * @param[in] user_data The user data passed from the callback registration function
310 * @see stt_set_engine_changed_cb()
312 typedef bool (*stt_engine_changed_cb)(stt_h stt, const char* engine_id, const char* language,
313 bool support_silence, bool need_credential, void* user_data);
316 * @brief Creates a STT handle.
317 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
319 * @privilege %http://tizen.org/privilege/recorder
321 * @remarks If the function succeeds, @a stt handle must be released with stt_destroy().
323 * @param[out] stt The STT handle
325 * @return 0 on success, otherwise a negative error value
326 * @retval #STT_ERROR_NONE Successful
327 * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
328 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
329 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
330 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
332 * @post If this function is called, the STT state will be #STT_STATE_CREATED.
336 int stt_create(stt_h* stt);
339 * @brief Destroys a STT handle.
340 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
342 * @privilege %http://tizen.org/privilege/recorder
344 * @param[in] stt The STT handle
346 * @return 0 on success, otherwise a negative error value
347 * @retval #STT_ERROR_NONE Successful
348 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
349 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
350 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
354 int stt_destroy(stt_h stt);
357 * @brief Retrieves supported engine information using a callback function.
358 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
360 * @privilege %http://tizen.org/privilege/recorder
362 * @param[in] stt The STT handle
363 * @param[in] callback The callback function to invoke
364 * @param[in] user_data The user data to be passed to the callback function
366 * @return 0 on success, otherwise a negative error value
367 * @retval #STT_ERROR_NONE Success
368 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
369 * @retval #STT_ERROR_INVALID_STATE STT Not initialized
370 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
371 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
373 * @pre The state should be #STT_STATE_CREATED.
374 * @post This function invokes stt_supported_engine_cb() repeatedly for getting engine information.
376 * @see stt_supported_engine_cb()
378 int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, void* user_data);
381 * @brief Gets the current engine id.
382 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
384 * @privilege %http://tizen.org/privilege/recorder
386 * @remarks If the function is success, @a engine_id must be released using free().
388 * @param[in] stt The STT handle
389 * @param[out] engine_id Engine id
391 * @return 0 on success, otherwise a negative error value
392 * @retval #STT_ERROR_NONE Success
393 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
394 * @retval #STT_ERROR_INVALID_STATE STT Not initialized
395 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
396 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
398 * @pre The state should be #STT_STATE_CREATED.
400 * @see stt_set_engine()
402 int stt_get_engine(stt_h stt, char** engine_id);
405 * @brief Sets the engine id.
406 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
408 * @privilege %http://tizen.org/privilege/recorder
410 * @param[in] stt The STT handle
411 * @param[in] engine_id Engine id
413 * @return 0 on success, otherwise a negative error value
414 * @retval #STT_ERROR_NONE Success
415 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
416 * @retval #STT_ERROR_INVALID_STATE STT Not initialized
417 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
418 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
420 * @pre The state should be #STT_STATE_CREATED.
422 * @see stt_get_engine()
424 int stt_set_engine(stt_h stt, const char* engine_id);
427 * @brief Sets the app credential.
430 * @privilege %http://tizen.org/privilege/recorder
432 * @param[in] stt The STT handle
433 * @param[in] credential The app credential
435 * @return 0 on success, otherwise a negative error value
436 * @retval #STT_ERROR_NONE Success
437 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
438 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
440 * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
445 int stt_set_credential(stt_h stt, const char* credential);
448 * @brief Connects the daemon asynchronously.
449 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
451 * @privilege %http://tizen.org/privilege/recorder
453 * @param[in] stt The STT handle
455 * @return 0 on success, otherwise a negative error value
456 * @retval #STT_ERROR_NONE Successful
457 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
458 * @retval #STT_ERROR_INVALID_STATE Invalid state
459 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
461 * @pre The state should be #STT_STATE_CREATED.
462 * @post If this function is successful, the STT state will be #STT_STATE_READY. \n
463 * If this function is failed, the error callback is called. (e.g. #STT_ERROR_ENGINE_NOT_FOUND)
465 * @see stt_unprepare()
467 int stt_prepare(stt_h stt);
470 * @brief Disconnects the daemon.
471 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
473 * @privilege %http://tizen.org/privilege/recorder
475 * @param[in] stt The STT handle
477 * @return 0 on success, otherwise a negative error value
478 * @retval #STT_ERROR_NONE Successful
479 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
480 * @retval #STT_ERROR_INVALID_STATE Invalid state
481 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
483 * @pre The state should be #STT_STATE_READY.
484 * @post If this function is called, the STT state will be #STT_STATE_CREATED.
488 int stt_unprepare(stt_h stt);
491 * @brief Retrieves all supported languages of current engine using callback function.
492 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
494 * @privilege %http://tizen.org/privilege/recorder
496 * @param[in] stt The STT handle
497 * @param[in] callback The callback function to invoke
498 * @param[in] user_data The user data to be passed to the callback function
500 * @return 0 on success, otherwise a negative error value
501 * @retval #STT_ERROR_NONE Successful
502 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
503 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
504 * @retval #STT_ERROR_ENGINE_NOT_FOUND No available engine
505 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
507 * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
509 * @see stt_supported_language_cb()
510 * @see stt_get_default_language()
512 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
515 * @brief Gets the default language set by the user.
516 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
518 * @privilege %http://tizen.org/privilege/recorder
519 * @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. \n
520 * For example, "ko_KR" for Korean, "en_US" for American English. \n
521 * If the function succeeds, @a language must be released using free() when it is no longer required.
523 * @param[in] stt The STT handle
524 * @param[out] language The language
526 * @return 0 on success, otherwise a negative error value
527 * @retval #STT_ERROR_NONE Successful
528 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
529 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
530 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
532 * @see stt_foreach_supported_languages()
534 int stt_get_default_language(stt_h stt, char** language);
537 * @brief Gets the current STT state.
538 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
540 * @privilege %http://tizen.org/privilege/recorder
542 * @param[in] stt The STT handle
543 * @param[out] state The current STT state
545 * @return 0 on success, otherwise a negative error value
546 * @retval #STT_ERROR_NONE Successful
547 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
548 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
553 * @see stt_state_changed_cb()
555 int stt_get_state(stt_h stt, stt_state_e* state);
558 * @brief Gets the current error message.
561 * @privilege %http://tizen.org/privilege/recorder
562 * @remarks This function should be called during an stt error callback. If not, the error as operation failure will be returned. \n
563 * If the function succeeds, @a err_msg must be released using free() when it is no longer required.
565 * @param[in] stt The STT handle
566 * @param[out] err_msg The current error message
568 * @return 0 on success, otherwise a negative error value
569 * @retval #STT_ERROR_NONE Successful
570 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
571 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
572 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
574 * @see stt_set_error_cb()
575 * @see stt_unset_error_cb()
577 int stt_get_error_message(stt_h stt, char** err_msg);
580 * @brief Checks whether the recognition type is supported.
581 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
583 * @privilege %http://tizen.org/privilege/recorder
585 * @param[in] stt The STT handle
586 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
587 * @param[out] support The result status @c true = supported, @c false = not supported
589 * @return 0 on success, otherwise a negative error value
590 * @retval #STT_ERROR_NONE Successful
591 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
592 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
593 * @retval #STT_ERROR_INVALID_STATE Invalid state
594 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
596 * @pre The state should be #STT_STATE_READY.
598 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
601 * @brief Sets the silence detection.
602 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
604 * @privilege %http://tizen.org/privilege/recorder
606 * @param[in] stt The STT handle
607 * @param[in] type The option type
609 * @return 0 on success, otherwise a negative error value
610 * @retval #STT_ERROR_NONE Successful
611 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
612 * @retval #STT_ERROR_INVALID_STATE Invalid state
613 * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
614 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
616 * @pre The state should be #STT_STATE_READY.
618 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
621 * @brief Sets the sound to start recording.
622 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
624 * @privilege %http://tizen.org/privilege/recorder
626 * @remarks Sound file type should be wav type.
628 * @param[in] stt The STT handle
629 * @param[in] filename The sound file path
631 * @return 0 on success, otherwise a negative error value
632 * @retval #STT_ERROR_NONE Successful
633 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
634 * @retval #STT_ERROR_INVALID_STATE Invalid state
635 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
636 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
638 * @pre The state should be #STT_STATE_READY.
640 int stt_set_start_sound(stt_h stt, const char* filename);
643 * @brief Unsets the sound to start recording.
644 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
646 * @privilege %http://tizen.org/privilege/recorder
648 * @param[in] stt The STT handle
650 * @return 0 on success, otherwise a negative error value
651 * @retval #STT_ERROR_NONE Successful
652 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
653 * @retval #STT_ERROR_INVALID_STATE Invalid state
654 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
655 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
657 * @pre The state should be #STT_STATE_READY.
659 int stt_unset_start_sound(stt_h stt);
662 * @brief Sets the sound to stop recording.
663 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
665 * @privilege %http://tizen.org/privilege/recorder
667 * @remarks Sound file type should be wav type.
669 * @param[in] stt The STT handle
670 * @param[in] filename The sound file path
672 * @return 0 on success, otherwise a negative error value
673 * @retval #STT_ERROR_NONE Successful
674 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
675 * @retval #STT_ERROR_INVALID_STATE Invalid state
676 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
677 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
679 * @pre The state should be #STT_STATE_READY.
681 int stt_set_stop_sound(stt_h stt, const char* filename);
684 * @brief Unsets the sound to stop recording.
685 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
687 * @privilege %http://tizen.org/privilege/recorder
689 * @param[in] stt The STT handle
691 * @return 0 on success, otherwise a negative error value
692 * @retval #STT_ERROR_NONE Successful
693 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
694 * @retval #STT_ERROR_INVALID_STATE Invalid state
695 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
696 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
698 * @pre The state should be #STT_STATE_READY.
700 int stt_unset_stop_sound(stt_h stt);
703 * @brief Starts recording and recognition asynchronously.
704 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
706 * @privilege %http://tizen.org/privilege/recorder
708 * @remarks This function starts recording in the daemon and sending recording data to engine. \n
709 * This work continues until stt_stop(), stt_cancel() or silence detected by engine.
711 * @param[in] stt The STT handle
712 * @param[in] language The language selected from stt_foreach_supported_languages()
713 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
715 * @return 0 on success, otherwise a negative error value
716 * @retval #STT_ERROR_NONE Successful
717 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
718 * @retval #STT_ERROR_INVALID_STATE Invalid state
719 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
720 * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
721 * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
722 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
724 * @pre The state should be #STT_STATE_READY.
725 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
726 * If this function succeeds, the STT state will be #STT_STATE_RECORDING.
730 * @see stt_state_changed_cb()
732 int stt_start(stt_h stt, const char* language, const char* type);
735 * @brief Finishes the recording and starts recognition processing in engine asynchronously.
736 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
738 * @privilege %http://tizen.org/privilege/recorder
740 * @param[in] stt The STT handle
742 * @return 0 on success, otherwise a negative error value
743 * @retval #STT_ERROR_NONE Successful
744 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
745 * @retval #STT_ERROR_INVALID_STATE Invalid state
746 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
747 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
749 * @pre The state should be #STT_STATE_RECORDING.
750 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
751 * If this function succeeds, the STT state will be #STT_STATE_PROCESSING. \n
752 * After processing of engine, stt_result_cb() is called.
756 * @see stt_state_changed_cb()
758 int stt_stop(stt_h stt);
761 * @brief Cancels processing recognition and recording asynchronously.
762 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
764 * @privilege %http://tizen.org/privilege/recorder
766 * @remarks This function cancels recording and engine cancels recognition processing. \n
767 * After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
769 * @param[in] stt The STT handle
771 * @return 0 on success, otherwise a negative error value
772 * @retval #STT_ERROR_NONE Successful
773 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
774 * @retval #STT_ERROR_INVALID_STATE Invalid state
775 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
776 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
778 * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
779 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
780 * If this function succeeds, the STT state will be #STT_STATE_READY.
784 * @see stt_state_changed_cb()
786 int stt_cancel(stt_h stt);
789 * @brief Gets the microphone volume during recording.
790 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
792 * @privilege %http://tizen.org/privilege/recorder
794 * @param[in] stt The STT handle
795 * @param[out] volume Recording volume
797 * @return 0 on success, otherwise a negative error value
798 * @retval #STT_ERROR_NONE Successful
799 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
800 * @retval #STT_ERROR_INVALID_STATE Invalid state
801 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
802 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
804 * @pre The state should be #STT_STATE_RECORDING.
808 int stt_get_recording_volume(stt_h stt, float* volume);
811 * @brief Retrieves the time stamp of the current recognition result using the callback function.
812 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
814 * @privilege %http://tizen.org/privilege/recorder
816 * @remarks This function should be called in stt_recognition_result_cb().
817 * After stt_recognition_result_cb(), result data is NOT valid.
819 * @param[in] stt The STT handle
820 * @param[in] callback The callback function to invoke
821 * @param[in] user_data The user data to be passed to the callback function
823 * @return 0 on success, otherwise a negative error value
824 * @retval #STT_ERROR_NONE Successful
825 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
826 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
827 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
829 * @pre This function should be called in stt_recognition_result_cb().
830 * @post This function invokes stt_result_time_cb() repeatedly for getting time information.
832 * @see stt_result_time_cb()
833 * @see stt_recognition_result_cb()
835 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
838 * @brief Registers a callback function to get the recognition result.
839 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
841 * @privilege %http://tizen.org/privilege/recorder
843 * @param[in] stt The STT handle
844 * @param[in] callback The callback function to register
845 * @param[in] user_data The user data to be passed to the callback function
847 * @return 0 on success, otherwise a negative error value
848 * @retval #STT_ERROR_NONE Successful
849 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
850 * @retval #STT_ERROR_INVALID_STATE Invalid state
851 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
853 * @pre The state should be #STT_STATE_CREATED.
855 * @see stt_recognition_result_cb()
856 * @see stt_unset_recognition_result_cb()
858 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
861 * @brief Unregisters the callback function.
862 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
864 * @privilege %http://tizen.org/privilege/recorder
866 * @param[in] stt The STT handle
868 * @return 0 on success, otherwise a negative error value
869 * @retval #STT_ERROR_NONE Successful
870 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
871 * @retval #STT_ERROR_INVALID_STATE Invalid state
872 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
874 * @pre The state should be #STT_STATE_CREATED.
876 * @see stt_set_recognition_result_cb()
878 int stt_unset_recognition_result_cb(stt_h stt);
881 * @brief Registers a callback function to be called when STT state changes.
882 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
884 * @privilege %http://tizen.org/privilege/recorder
886 * @param[in] stt The STT handle
887 * @param[in] callback The callback function to register
888 * @param[in] user_data The user data to be passed to the callback function
890 * @return 0 on success, otherwise a negative error value
891 * @retval #STT_ERROR_NONE Successful
892 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
893 * @retval #STT_ERROR_INVALID_STATE Invalid state
894 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
896 * @pre The state should be #STT_STATE_CREATED.
898 * @see stt_state_changed_cb()
899 * @see stt_unset_state_changed_cb()
901 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
904 * @brief Unregisters the callback function.
905 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
907 * @privilege %http://tizen.org/privilege/recorder
909 * @param[in] stt The STT handle
911 * @return 0 on success, otherwise a negative error value
912 * @retval #STT_ERROR_NONE Successful
913 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
914 * @retval #STT_ERROR_INVALID_STATE Invalid state
915 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
917 * @pre The state should be #STT_STATE_CREATED.
919 * @see stt_set_state_changed_cb()
921 int stt_unset_state_changed_cb(stt_h stt);
924 * @brief Registers a callback function to be called when an error occurred.
925 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
927 * @privilege %http://tizen.org/privilege/recorder
929 * @param[in] stt The STT handle
930 * @param[in] callback The callback function to register
931 * @param[in] user_data The user data to be passed to the callback function
933 * @return 0 on success, otherwise a negative error value
934 * @retval #STT_ERROR_NONE Successful
935 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
936 * @retval #STT_ERROR_INVALID_STATE Invalid state
937 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
939 * @pre The state should be #STT_STATE_CREATED.
941 * @see stt_error_cb()
942 * @see stt_unset_error_cb()
944 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
947 * @brief Unregisters the callback function.
948 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
950 * @privilege %http://tizen.org/privilege/recorder
952 * @param[in] stt The STT handle
954 * @return 0 on success, 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
960 * @pre The state should be #STT_STATE_CREATED.
962 * @see stt_set_error_cb()
964 int stt_unset_error_cb(stt_h stt);
967 * @brief Registers a callback function to detect the default language change.
968 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
970 * @privilege %http://tizen.org/privilege/recorder
972 * @param[in] stt The STT handle
973 * @param[in] callback The callback function to register
974 * @param[in] user_data The user data to be passed to the callback function
976 * @return 0 on success, otherwise a negative error value
977 * @retval #STT_ERROR_NONE Successful
978 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
979 * @retval #STT_ERROR_INVALID_STATE Invalid state
980 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
982 * @pre The state should be #STT_STATE_CREATED.
984 * @see stt_default_language_changed_cb()
985 * @see stt_unset_default_language_changed_cb()
987 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
990 * @brief Unregisters the callback function.
991 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
993 * @privilege %http://tizen.org/privilege/recorder
995 * @param[in] stt The STT handle
997 * @return 0 on success, otherwise a negative error value
998 * @retval #STT_ERROR_NONE Successful
999 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1000 * @retval #STT_ERROR_INVALID_STATE Invalid state
1001 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1003 * @pre The state should be #STT_STATE_CREATED.
1005 * @see stt_set_default_language_changed_cb()
1007 int stt_unset_default_language_changed_cb(stt_h stt);
1017 #endif /* __STT_H__ */