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