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 Sets the private data to stt engine.
451 * @param[in] stt The STT handle
452 * @param[in] key The field name of private data
453 * @param[in] data The data for set
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_PERMISSION_DENIED Permission denied
460 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
461 * @retval #STT_ERROR_TIMED_OUT No answer from the daemon
463 * @pre The state should be #STT_STATE_READY.
465 * @see stt_get_private_data()
467 int stt_set_private_data(stt_h stt, const char* key, const char* data);
470 * @brief Gets the private data from stt engine.
473 * @param[in] stt The STT handle
474 * @param[in] key The field name of private data
475 * @param[out] data The data
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_PERMISSION_DENIED Permission denied
482 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
483 * @retval #STT_ERROR_TIMED_OUT No answer from the daemon
485 * @pre The state should be #STT_STATE_READY.
487 * @see stt_set_private_data()
489 int stt_get_private_data(stt_h stt, const char* key, char** data);
492 * @brief Connects the daemon asynchronously.
493 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
495 * @privilege %http://tizen.org/privilege/recorder
497 * @param[in] stt The STT handle
499 * @return 0 on success, otherwise a negative error value
500 * @retval #STT_ERROR_NONE Successful
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
505 * @pre The state should be #STT_STATE_CREATED.
506 * @post If this function is successful, the STT state will be #STT_STATE_READY. \n
507 * If this function is failed, the error callback is called. (e.g. #STT_ERROR_ENGINE_NOT_FOUND)
509 * @see stt_unprepare()
511 int stt_prepare(stt_h stt);
514 * @brief Disconnects the daemon.
515 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
517 * @privilege %http://tizen.org/privilege/recorder
519 * @param[in] stt The STT handle
521 * @return 0 on success, otherwise a negative error value
522 * @retval #STT_ERROR_NONE Successful
523 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
524 * @retval #STT_ERROR_INVALID_STATE Invalid state
525 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
527 * @pre The state should be #STT_STATE_READY.
528 * @post If this function is called, the STT state will be #STT_STATE_CREATED.
532 int stt_unprepare(stt_h stt);
535 * @brief Retrieves all supported languages of current engine using callback function.
536 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
538 * @privilege %http://tizen.org/privilege/recorder
540 * @param[in] stt The STT handle
541 * @param[in] callback The callback function to invoke
542 * @param[in] user_data The user data to be passed to the callback function
544 * @return 0 on success, otherwise a negative error value
545 * @retval #STT_ERROR_NONE Successful
546 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
547 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
548 * @retval #STT_ERROR_ENGINE_NOT_FOUND No available engine
549 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
551 * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
553 * @see stt_supported_language_cb()
554 * @see stt_get_default_language()
556 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
559 * @brief Gets the default language set by the user.
560 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
562 * @privilege %http://tizen.org/privilege/recorder
563 * @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
564 * For example, "ko_KR" for Korean, "en_US" for American English. \n
565 * If the function succeeds, @a language must be released using free() when it is no longer required.
567 * @param[in] stt The STT handle
568 * @param[out] language The language
570 * @return 0 on success, otherwise a negative error value
571 * @retval #STT_ERROR_NONE Successful
572 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
573 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
574 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
576 * @see stt_foreach_supported_languages()
578 int stt_get_default_language(stt_h stt, char** language);
581 * @brief Gets the current STT state.
582 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
584 * @privilege %http://tizen.org/privilege/recorder
586 * @param[in] stt The STT handle
587 * @param[out] state The current STT state
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_NOT_SUPPORTED STT NOT supported
597 * @see stt_state_changed_cb()
599 int stt_get_state(stt_h stt, stt_state_e* state);
602 * @brief Gets the current error message.
605 * @privilege %http://tizen.org/privilege/recorder
606 * @remarks This function should be called during an stt error callback. If not, the error as operation failure will be returned. \n
607 * If the function succeeds, @a err_msg must be released using free() when it is no longer required.
609 * @param[in] stt The STT handle
610 * @param[out] err_msg The current error message
612 * @return 0 on success, otherwise a negative error value
613 * @retval #STT_ERROR_NONE Successful
614 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
615 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
616 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
618 * @see stt_set_error_cb()
619 * @see stt_unset_error_cb()
621 int stt_get_error_message(stt_h stt, char** err_msg);
624 * @brief Checks whether the recognition type is supported.
625 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
627 * @privilege %http://tizen.org/privilege/recorder
629 * @param[in] stt The STT handle
630 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
631 * @param[out] support The result status @c true = supported, @c false = not supported
633 * @return 0 on success, 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_INVALID_STATE Invalid state
638 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
640 * @pre The state should be #STT_STATE_READY.
642 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
645 * @brief Sets the silence detection.
646 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
648 * @privilege %http://tizen.org/privilege/recorder
650 * @param[in] stt The STT handle
651 * @param[in] type The option type
653 * @return 0 on success, otherwise a negative error value
654 * @retval #STT_ERROR_NONE Successful
655 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
656 * @retval #STT_ERROR_INVALID_STATE Invalid state
657 * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
658 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
660 * @pre The state should be #STT_STATE_READY.
662 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
665 * @brief Sets the sound to start recording.
666 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
668 * @privilege %http://tizen.org/privilege/recorder
670 * @remarks Sound file type should be wav type.
672 * @param[in] stt The STT handle
673 * @param[in] filename The sound file path
675 * @return 0 on success, otherwise a negative error value
676 * @retval #STT_ERROR_NONE Successful
677 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
678 * @retval #STT_ERROR_INVALID_STATE Invalid state
679 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
680 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
682 * @pre The state should be #STT_STATE_READY.
684 int stt_set_start_sound(stt_h stt, const char* filename);
687 * @brief Unsets the sound to start recording.
688 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
690 * @privilege %http://tizen.org/privilege/recorder
692 * @param[in] stt The STT handle
694 * @return 0 on success, otherwise a negative error value
695 * @retval #STT_ERROR_NONE Successful
696 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
697 * @retval #STT_ERROR_INVALID_STATE Invalid state
698 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
699 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
701 * @pre The state should be #STT_STATE_READY.
703 int stt_unset_start_sound(stt_h stt);
706 * @brief Sets the sound to stop recording.
707 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
709 * @privilege %http://tizen.org/privilege/recorder
711 * @remarks Sound file type should be wav type.
713 * @param[in] stt The STT handle
714 * @param[in] filename The sound file path
716 * @return 0 on success, otherwise a negative error value
717 * @retval #STT_ERROR_NONE Successful
718 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
719 * @retval #STT_ERROR_INVALID_STATE Invalid state
720 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
721 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
723 * @pre The state should be #STT_STATE_READY.
725 int stt_set_stop_sound(stt_h stt, const char* filename);
728 * @brief Unsets the sound to stop recording.
729 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
731 * @privilege %http://tizen.org/privilege/recorder
733 * @param[in] stt The STT handle
735 * @return 0 on success, 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
742 * @pre The state should be #STT_STATE_READY.
744 int stt_unset_stop_sound(stt_h stt);
747 * @brief Starts recording and recognition asynchronously.
748 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
750 * @privilege %http://tizen.org/privilege/recorder
752 * @remarks This function starts recording in the daemon and sending recording data to engine. \n
753 * This work continues until stt_stop(), stt_cancel() or silence detected by engine.
755 * @param[in] stt The STT handle
756 * @param[in] language The language selected from stt_foreach_supported_languages()
757 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
759 * @return 0 on success, otherwise a negative error value
760 * @retval #STT_ERROR_NONE Successful
761 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
762 * @retval #STT_ERROR_INVALID_STATE Invalid state
763 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
764 * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
765 * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
766 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
768 * @pre The state should be #STT_STATE_READY.
769 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
770 * If this function succeeds, the STT state will be #STT_STATE_RECORDING.
774 * @see stt_state_changed_cb()
776 int stt_start(stt_h stt, const char* language, const char* type);
779 * @brief Finishes the recording and starts recognition processing in engine asynchronously.
780 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
782 * @privilege %http://tizen.org/privilege/recorder
784 * @param[in] stt The STT handle
786 * @return 0 on success, otherwise a negative error value
787 * @retval #STT_ERROR_NONE Successful
788 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
789 * @retval #STT_ERROR_INVALID_STATE Invalid state
790 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
791 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
793 * @pre The state should be #STT_STATE_RECORDING.
794 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
795 * If this function succeeds, the STT state will be #STT_STATE_PROCESSING. \n
796 * After processing of engine, stt_result_cb() is called.
800 * @see stt_state_changed_cb()
802 int stt_stop(stt_h stt);
805 * @brief Cancels processing recognition and recording asynchronously.
806 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
808 * @privilege %http://tizen.org/privilege/recorder
810 * @remarks This function cancels recording and engine cancels recognition processing. \n
811 * After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
813 * @param[in] stt The STT handle
815 * @return 0 on success, otherwise a negative error value
816 * @retval #STT_ERROR_NONE Successful
817 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
818 * @retval #STT_ERROR_INVALID_STATE Invalid state
819 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
820 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
822 * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
823 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
824 * If this function succeeds, the STT state will be #STT_STATE_READY.
828 * @see stt_state_changed_cb()
830 int stt_cancel(stt_h stt);
833 * @brief Gets the microphone volume during recording.
834 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
836 * @privilege %http://tizen.org/privilege/recorder
838 * @param[in] stt The STT handle
839 * @param[out] volume Recording volume
841 * @return 0 on success, otherwise a negative error value
842 * @retval #STT_ERROR_NONE Successful
843 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
844 * @retval #STT_ERROR_INVALID_STATE Invalid state
845 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
846 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
848 * @pre The state should be #STT_STATE_RECORDING.
852 int stt_get_recording_volume(stt_h stt, float* volume);
855 * @brief Retrieves the time stamp of the current recognition result using the callback function.
856 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
858 * @privilege %http://tizen.org/privilege/recorder
860 * @remarks This function should be called in stt_recognition_result_cb().
861 * After stt_recognition_result_cb(), result data is NOT valid.
863 * @param[in] stt The STT handle
864 * @param[in] callback The callback function to invoke
865 * @param[in] user_data The user data to be passed to the callback function
867 * @return 0 on success, otherwise a negative error value
868 * @retval #STT_ERROR_NONE Successful
869 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
870 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
871 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
873 * @pre This function should be called in stt_recognition_result_cb().
874 * @post This function invokes stt_result_time_cb() repeatedly for getting time information.
876 * @see stt_result_time_cb()
877 * @see stt_recognition_result_cb()
879 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
882 * @brief Registers a callback function to get the recognition result.
883 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
885 * @privilege %http://tizen.org/privilege/recorder
887 * @param[in] stt The STT handle
888 * @param[in] callback The callback function to register
889 * @param[in] user_data The user data to be passed to the callback function
891 * @return 0 on success, otherwise a negative error value
892 * @retval #STT_ERROR_NONE Successful
893 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
894 * @retval #STT_ERROR_INVALID_STATE Invalid state
895 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
897 * @pre The state should be #STT_STATE_CREATED.
899 * @see stt_recognition_result_cb()
900 * @see stt_unset_recognition_result_cb()
902 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
905 * @brief Unregisters the callback function.
906 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
908 * @privilege %http://tizen.org/privilege/recorder
910 * @param[in] stt The STT handle
912 * @return 0 on success, otherwise a negative error value
913 * @retval #STT_ERROR_NONE Successful
914 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
915 * @retval #STT_ERROR_INVALID_STATE Invalid state
916 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
918 * @pre The state should be #STT_STATE_CREATED.
920 * @see stt_set_recognition_result_cb()
922 int stt_unset_recognition_result_cb(stt_h stt);
925 * @brief Registers a callback function to be called when STT state changes.
926 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
928 * @privilege %http://tizen.org/privilege/recorder
930 * @param[in] stt The STT handle
931 * @param[in] callback The callback function to register
932 * @param[in] user_data The user data to be passed to the callback function
934 * @return 0 on success, otherwise a negative error value
935 * @retval #STT_ERROR_NONE Successful
936 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
937 * @retval #STT_ERROR_INVALID_STATE Invalid state
938 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
940 * @pre The state should be #STT_STATE_CREATED.
942 * @see stt_state_changed_cb()
943 * @see stt_unset_state_changed_cb()
945 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
948 * @brief Unregisters the callback function.
949 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
951 * @privilege %http://tizen.org/privilege/recorder
953 * @param[in] stt The STT handle
955 * @return 0 on success, otherwise a negative error value
956 * @retval #STT_ERROR_NONE Successful
957 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
958 * @retval #STT_ERROR_INVALID_STATE Invalid state
959 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
961 * @pre The state should be #STT_STATE_CREATED.
963 * @see stt_set_state_changed_cb()
965 int stt_unset_state_changed_cb(stt_h stt);
968 * @brief Registers a callback function to be called when an error occurred.
969 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
971 * @privilege %http://tizen.org/privilege/recorder
973 * @param[in] stt The STT handle
974 * @param[in] callback The callback function to register
975 * @param[in] user_data The user data to be passed to the callback function
977 * @return 0 on success, otherwise a negative error value
978 * @retval #STT_ERROR_NONE Successful
979 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
980 * @retval #STT_ERROR_INVALID_STATE Invalid state
981 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
983 * @pre The state should be #STT_STATE_CREATED.
985 * @see stt_error_cb()
986 * @see stt_unset_error_cb()
988 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
991 * @brief Unregisters the callback function.
992 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
994 * @privilege %http://tizen.org/privilege/recorder
996 * @param[in] stt The STT handle
998 * @return 0 on success, otherwise a negative error value
999 * @retval #STT_ERROR_NONE Successful
1000 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1001 * @retval #STT_ERROR_INVALID_STATE Invalid state
1002 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1004 * @pre The state should be #STT_STATE_CREATED.
1006 * @see stt_set_error_cb()
1008 int stt_unset_error_cb(stt_h stt);
1011 * @brief Registers a callback function to detect the default language change.
1012 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1014 * @privilege %http://tizen.org/privilege/recorder
1016 * @param[in] stt The STT handle
1017 * @param[in] callback The callback function to register
1018 * @param[in] user_data The user data to be passed to the callback function
1020 * @return 0 on success, otherwise a negative error value
1021 * @retval #STT_ERROR_NONE Successful
1022 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1023 * @retval #STT_ERROR_INVALID_STATE Invalid state
1024 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1026 * @pre The state should be #STT_STATE_CREATED.
1028 * @see stt_default_language_changed_cb()
1029 * @see stt_unset_default_language_changed_cb()
1031 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
1034 * @brief Unregisters the callback function.
1035 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1037 * @privilege %http://tizen.org/privilege/recorder
1039 * @param[in] stt The STT handle
1041 * @return 0 on success, otherwise a negative error value
1042 * @retval #STT_ERROR_NONE Successful
1043 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1044 * @retval #STT_ERROR_INVALID_STATE Invalid state
1045 * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1047 * @pre The state should be #STT_STATE_CREATED.
1049 * @see stt_set_default_language_changed_cb()
1051 int stt_unset_default_language_changed_cb(stt_h stt);
1061 #endif /* __STT_H__ */