2 * Copyright (c) 2011-2016 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.
31 * @addtogroup CAPI_UIX_STT_MODULE
43 * @brief Enumeration for error codes.
44 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 */
71 * @brief Definition for free form dictation and default type.
72 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
74 #define STT_RECOGNITION_TYPE_FREE "stt.recognition.type.FREE"
78 * @brief Definition for continuous free dictation.
79 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
81 #define STT_RECOGNITION_TYPE_FREE_PARTIAL "stt.recognition.type.FREE.PARTIAL"
85 * @brief Definition for search.
86 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
88 #define STT_RECOGNITION_TYPE_SEARCH "stt.recognition.type.SEARCH"
92 * @brief Definition for web search.
93 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
95 #define STT_RECOGNITION_TYPE_WEB_SEARCH "stt.recognition.type.WEB_SEARCH"
99 * @brief Definition for map.
100 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
102 #define STT_RECOGNITION_TYPE_MAP "stt.recognition.type.MAP"
106 * @brief Definition for none message.
107 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
109 #define STT_RESULT_MESSAGE_NONE "stt.result.message.none"
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
116 #define STT_RESULT_MESSAGE_ERROR_TOO_SOON "stt.result.message.error.too.soon"
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
123 #define STT_RESULT_MESSAGE_ERROR_TOO_SHORT "stt.result.message.error.too.short"
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
130 #define STT_RESULT_MESSAGE_ERROR_TOO_LONG "stt.result.message.error.too.long"
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
137 #define STT_RESULT_MESSAGE_ERROR_TOO_QUIET "stt.result.message.error.too.quiet"
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
144 #define STT_RESULT_MESSAGE_ERROR_TOO_LOUD "stt.result.message.error.too.loud"
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
151 #define STT_RESULT_MESSAGE_ERROR_TOO_FAST "stt.result.message.error.too.fast"
155 * @brief Definition for Bluetooth audio-in ID.
158 #define STT_AUDIO_ID_BLUETOOTH "STT_AUDIO_ID_BLUETOOTH"
162 * @brief Definition for Wi-Fi audio-in ID.
165 #define STT_AUDIO_ID_WIFI "STT_AUDIO_ID_WIFI"
169 * @brief Definition for none specified audio-in ID.
172 #define STT_AUDIO_ID_NONE "STT_AUDIO_ID_NONE"
176 * @brief Enumeration for state.
177 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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*/
188 * @brief Enumeration for result event.
189 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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;
199 * @brief Enumeration for result time callback event.
200 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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;
210 * @brief Enumeration for silence detection type.
211 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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;
220 * @brief Enumeration for speech status.
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;
230 * @brief Enumerations of audio type.
234 STT_AUDIO_TYPE_RAW_S16 = 0, /**< Signed 16-bit audio sample */
235 STT_AUDIO_TYPE_RAW_U8, /**< Unsigned 8-bit audio sample */
239 * @brief A structure of STT handle.
240 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
242 typedef struct stt_s *stt_h;
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()
257 typedef bool(*stt_supported_engine_cb)(stt_h stt, const char* engine_id, const char* engine_name, void* user_data);
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.
273 * @see stt_set_recognition_result_cb()
274 * @see stt_unset_recognition_result_cb()
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);
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()
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);
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()
310 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
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()
323 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
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()
338 typedef bool (*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
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()
350 typedef void (*stt_default_language_changed_cb)(stt_h stt, const char* previous_language,
351 const char* current_language, void* user_data);
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()
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);
371 * @brief Called when STT engine detects the beginning or end of the speech.
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()
378 typedef void (*stt_speech_status_cb)(stt_h stt, stt_speech_status_e status, void *user_data);
382 * @brief Creates a STT handle.
383 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
399 int stt_create(stt_h* stt);
403 * @brief Destroys a STT handle.
404 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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
417 int stt_destroy(stt_h stt);
421 * @brief Retrieves supported engine information using a callback function.
422 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
440 int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, void* user_data);
444 * @brief Gets the current engine ID.
445 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
462 int stt_get_engine(stt_h stt, char** engine_id);
466 * @brief Sets the engine ID.
467 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
485 int stt_set_engine(stt_h stt, const char* engine_id);
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.
507 int stt_set_credential(stt_h stt, const char* credential);
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()
531 int stt_set_private_data(stt_h stt, const char* key, const char* data);
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()
554 int stt_get_private_data(stt_h stt, const char* key, char** data);
558 * @brief Connects the STT service asynchronously.
559 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
575 int stt_prepare(stt_h stt);
579 * @brief Disconnects the STT service.
580 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
595 int stt_unprepare(stt_h stt);
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
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()
619 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
623 * @brief Gets the default language set by the user.
624 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
641 int stt_get_default_language(stt_h stt, char** language);
645 * @brief Gets the current STT state.
646 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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
660 * @see stt_state_changed_cb()
662 int stt_get_state(stt_h stt, stt_state_e* state);
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()
681 int stt_get_error_message(stt_h stt, char** err_msg);
685 * @brief Checks whether the recognition type is supported.
686 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
703 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
707 * @brief Sets the silence detection.
708 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
723 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
727 * @brief Sets the sound to start recording.
728 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
744 int stt_set_start_sound(stt_h stt, const char* filename);
748 * @brief Unsets the sound to start recording.
749 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
763 int stt_unset_start_sound(stt_h stt);
767 * @brief Sets the sound to stop recording.
768 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
784 int stt_set_stop_sound(stt_h stt, const char* filename);
788 * @brief Unsets the sound to stop recording.
789 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
803 int stt_unset_stop_sound(stt_h stt);
807 * @brief Starts recording and recognition asynchronously.
808 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
833 * @see stt_state_changed_cb()
835 int stt_start(stt_h stt, const char* language, const char* type);
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
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.
864 * @see stt_state_changed_cb()
866 int stt_stop(stt_h stt);
870 * @brief Cancels processing recognition and recording asynchronously.
871 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
894 * @see stt_state_changed_cb()
896 int stt_cancel(stt_h stt);
900 * @brief Gets the microphone volume during recording.
901 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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.
917 int stt_get_recording_volume(stt_h stt, float* volume);
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
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()
942 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
946 * @brief Sets a callback function to get the recognition result.
947 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
964 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
968 * @brief Unsets the callback function.
969 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
983 int stt_unset_recognition_result_cb(stt_h stt);
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
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()
1005 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
1009 * @brief Unsets the callback function.
1010 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
1024 int stt_unset_state_changed_cb(stt_h stt);
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
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()
1046 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
1050 * @brief Unsets the callback function.
1051 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
1065 int stt_unset_error_cb(stt_h stt);
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
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()
1087 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
1091 * @brief Unsets the callback function.
1092 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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()
1106 int stt_unset_default_language_changed_cb(stt_h stt);
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()
1125 int stt_set_engine_changed_cb(stt_h stt, stt_engine_changed_cb callback, void* user_data);
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()
1141 int stt_unset_engine_changed_cb(stt_h stt);
1145 * @brief Sets a callback function to detect the speech status is changed.
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()
1163 int stt_set_speech_status_cb(stt_h stt, stt_speech_status_cb callback, void* user_data);
1167 * @brief Unsets the callback function to detect the speech status is changed.
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()
1182 int stt_unset_speech_status_cb(stt_h stt);
1186 * @brief Starts audio streaming and recognition asynchronously.
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()
1210 * @see stt_state_changed_cb()
1212 int stt_start_audio_streaming(stt_h stt, const char* language, const char* type);
1216 * @brief Sends audio data to STT engine.
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()
1236 * @see stt_get_audio_format()
1238 int stt_send_audio_streaming(stt_h stt, const char* data, size_t data_size);
1242 * @brief Finishes the audio streaming and starts recognition processing in engine asynchronously.
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()
1263 * @see stt_state_changed_cb()
1265 int stt_stop_audio_streaming(stt_h stt);
1269 * @brief Gets the recognizable audio format information.
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()
1285 int stt_get_audio_format(stt_h stt, stt_audio_type_e* type, int* rate, int* num_of_channels);
1289 * @brief Sets an ID of audio-in.
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()
1306 int stt_set_audio_id(stt_h stt, const char *audio_id);
1310 * @brief Gets an ID of audio-in.
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()
1328 int stt_get_audio_id(stt_h stt, char **audio_id);
1341 #endif /* __STT_H__ */