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.
17 #ifndef __STT_FILE_H__
18 #define __STT_FILE_H__
24 * @addtogroup STT_FILE_MODULE
34 * @brief Enumerations of error codes.
37 STT_FILE_ERROR_NONE = 0, /**< Successful */
38 STT_FILE_ERROR_OUT_OF_MEMORY = -ENOMEM, /**< Out of Memory */
39 STT_FILE_ERROR_IO_ERROR = -EIO, /**< I/O error */
40 STT_FILE_ERROR_INVALID_PARAMETER = -EINVAL, /**< Invalid parameter */
41 STT_FILE_ERROR_OUT_OF_NETWORK = -ENETDOWN, /**< Out of network */
42 STT_FILE_ERROR_INVALID_STATE = -0x0100000 | 0x31, /**< Invalid state */
43 STT_FILE_ERROR_INVALID_LANGUAGE = -0x0100000 | 0x32, /**< Invalid language */
44 STT_FILE_ERROR_ENGINE_NOT_FOUND = -0x0100000 | 0x33, /**< No available engine */
45 STT_FILE_ERROR_OPERATION_FAILED = -0x0100000 | 0x34, /**< Operation failed */
46 STT_FILE_ERROR_NOT_SUPPORTED_FEATURE = -0x0100000 | 0x35, /**< Not supported feature of current engine */
47 STT_FILE_ERROR_NOT_AGREE_SERVICE = -0x0100000 | 0x36 /**< Not agreed service of engine*/
51 * @brief Enumerations of state.
54 STT_FILE_STATE_NONE = 0, /**< 'NONE' state */
55 STT_FILE_STATE_READY = 1, /**< 'READY' state */
56 STT_FILE_STATE_PROCESSING = 2, /**< 'PROCESSING' state */
60 * @brief Enumerations of audio type.
63 STT_FILE_AUDIO_TYPE_RAW_S16 = 0, /**< Signed 16-bit audio sample */
64 STT_FILE_AUDIO_TYPE_RAW_U8, /**< Unsigned 8-bit audio sample */
65 STT_FILE_AUDIO_TYPE_MAX
66 } stt_file_audio_type_e;
69 * @brief Enumerations of result event.
72 STT_FILE_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the recognition full or last result is ready */
73 STT_FILE_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the recognition partial result is ready */
74 STT_FILE_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
75 } stt_file_result_event_e;
78 * @brief Enumerations of result time callback event.
81 STT_FILE_RESULT_TIME_EVENT_BEGINNING = 0, /**< Event when the token is beginning type */
82 STT_FILE_RESULT_TIME_EVENT_MIDDLE = 1, /**< Event when the token is middle type */
83 STT_FILE_RESULT_TIME_EVENT_END = 2 /**< Event when the token is end type */
84 } stt_file_result_time_event_e;
87 * @brief Recognition type : Continuous free dictation.
89 #define STT_RECOGNITION_TYPE_FREE_PARTIAL "stt.recognition.type.FREE.PARTIAL"
93 * @brief Called to get a engine information.
95 * @param[in] engine_id Engine id.
96 * @param[in] engine_name Engine name.
97 * @param[in] user_data User data passed from the stt_file_setting_foreach_supported_engines().
99 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
100 * @pre stt_file_foreach_supported_engines() will invoke this callback.
102 * @see stt_file_foreach_supported_engines()
104 typedef bool(*stt_file_supported_engine_cb)(const char* engine_id, const char* engine_name, void* user_data);
107 * @brief Called when STT gets the recognition result from engine.
109 * @remark After stt_file_start() is called and recognition result is occurred, this function is called.
111 * @param[in] event The result event
112 * @param[in] data Result texts
113 * @param[in] data_count Result text count
114 * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
115 * @param[in] user_data The user data passed from the callback registration function
117 * @pre stt_file_start() will invoke this callback if you register it using stt_file_set_recognition_result_cb().
118 * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT FILE state will be #STT_FILE_STATE_READY.
120 * @see stt_file_set_recognition_result_cb()
121 * @see stt_file_unset_recognition_result_cb()
123 typedef void (*stt_file_recognition_result_cb)(stt_file_result_event_e event, const char** data, int data_count,
124 const char* msg, void *user_data);
127 * @brief Called when STT get the time stamp of recognition result.
129 * @param[in] index The result index
130 * @param[in] event The token event
131 * @param[in] text The result text
132 * @param[in] start_time The start time of result text
133 * @param[in] end_time The end time of result text
134 * @param[in] user_data The user data passed from the foreach function
136 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
138 * @pre stt_file_recognition_result_cb() should be called.
140 * @see stt_file_recognition_result_cb()
142 typedef bool (*stt_file_result_time_cb)(int index, stt_file_result_time_event_e event, const char* text,
143 long start_time, long end_time, void* user_data);
146 * @brief Called when the state of STT FILE is changed.
148 * @param[in] previous A previous state
149 * @param[in] current A current state
150 * @param[in] user_data The user data passed from the callback registration function.
152 * @pre An application registers this callback using stt_file_set_state_changed_cb() to detect changing state.
154 * @see stt_file_set_state_changed_cb()
155 * @see stt_file_unset_state_changed_cb()
157 typedef void (*stt_file_state_changed_cb)(stt_file_state_e previous, stt_file_state_e current, void* user_data);
160 * @brief Called to retrieve the supported languages.
162 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
163 * followed by ISO 639-1 for the two-letter language code. \n
164 * For example, "ko_KR" for Korean, "en_US" for American English.
165 * @param[in] user_data The user data passed from the foreach function
167 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
168 * @pre stt_file_foreach_supported_languages() will invoke this callback.
170 * @see stt_file_foreach_supported_languages()
172 typedef bool (*stt_file_supported_language_cb)(const char* language, void* user_data);
176 * @brief Initialize STT FILE.
178 * @return 0 on success, otherwise a negative error value
179 * @retval #STT_FILE_ERROR_NONE Successful
180 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
181 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
182 * @retval #STT_FILE_ERROR_ENGINE_NOT_FOUND Engine not found
184 * @pre The state should be #STT_FILE_STATE_NONE.
185 * @post If this function is called, the STT state will be #STT_FILE_STATE_READY.
187 * @see stt_file_deinitialize(void)
189 int stt_file_initialize(void);
192 * @brief Deinitialize STT FILE.
194 * @return 0 on success, otherwise a negative error value
195 * @retval #STT_FILE_ERROR_NONE Successful
196 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
198 * @pre The state should be #STT_FILE_STATE_READY.
199 * @post If this function is called, the STT FILE state will be #STT_FILE_STATE_NONE.
201 * @see stt_file_initialize(void)
203 int stt_file_deinitialize(void);
206 * @brief Gets the current state.
208 * @param[out] state The current state of STT
210 * @return 0 on success, otherwise a negative error value
211 * @retval #STT_FILE_ERROR_NONE Successful
212 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
214 * @see stt_file_state_changed_cb()
216 int stt_file_get_state(stt_file_state_e* state);
219 * @brief Retrieve supported engine informations using callback function.
221 * @param[in] callback The callback function to invoke
222 * @param[in] user_data The user data to be passed to the callback function.
224 * @return 0 on success, otherwise a negative error value.
225 * @retval #STT_FILE_ERROR_NONE Success.
226 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
227 * @retval #STT_FILE_ERROR_INVALID_STATE STT Not initialized.
228 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure.
230 * @pre The state should be #STT_FILE_STATE_READY.
231 * @post This function invokes stt_file_supported_engine_cb() repeatedly for getting engine information.
233 * @see stt_file_supported_engine_cb()
235 int stt_file_foreach_supported_engines(stt_file_supported_engine_cb callback, void* user_data);
238 * @brief Get current engine id.
240 * @remark If the function is success, @a engine_id must be released with free() by you.
242 * @param[out] engine_id engine id.
244 * @return 0 on success, otherwise a negative error value.
245 * @retval #STT_FILE_ERROR_NONE Success.
246 * @retval #STT_FILE_ERROR_OUT_OF_MEMORY Out of memory.
247 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
248 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state.
249 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure.
251 * @pre The state should be #STT_FILE_STATE_READY.
253 * @see stt_file_foreach_supported_engines()
254 * @see stt_file_set_engine()
256 int stt_file_get_engine(char** engine_id);
259 * @brief Set engine id.
261 * @param[in] engine_id engine id.
263 * @return 0 on success, otherwise a negative error value.
264 * @retval #STT_FILE_ERROR_NONE Success.
265 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
266 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state.
267 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure.
269 * @pre The state should be #STT_FILE_STATE_READY.
271 * @see stt_file_get_engine()
273 int stt_file_set_engine(const char* engine_id);
276 * @brief Retrieves all supported languages of current engine using callback function.
278 * @param[in] callback The callback function to invoke
279 * @param[in] user_data The user data to be passed to the callback function
281 * @return 0 on success, otherwise a negative error value
282 * @retval #STT_FILE_ERROR_NONE Successful
283 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
284 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
285 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
287 * @pre The state should be #STT_FILE_STATE_READY.
288 * @post This function invokes stt_file_supported_language_cb() repeatedly for getting languages.
290 * @see stt_file_supported_language_cb()
291 * @see stt_file_get_default_language()
293 int stt_file_foreach_supported_languages(stt_file_supported_language_cb callback, void* user_data);
297 * @brief Starts file recognition asynchronously.
299 * @param[in] language The language selected from stt_file_foreach_supported_languages()
300 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE_PARTIAL)
301 * @param[in] filepath PCM filepath for recognition
302 * @param[in] audio_type audio type of file
303 * @param[in] sample_rate sample rate of file
305 * @return 0 on success, otherwise a negative error value
306 * @retval #STT_FILE_ERROR_NONE Successful
307 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter.
308 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
309 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
310 * @retval #STT_FILE_ERROR_INVALID_LANGUAGE Invalid language
311 * @retval #STT_FILE_ERROR_OUT_OF_NETWORK Out of network
313 * @pre The state should be #STT_FILE_STATE_READY.
314 * @post It will invoke stt_file_state_changed_cb(), if you register a callback with stt_file_state_changed_cb(). \n
315 * If this function succeeds, the STT state will be #STT_FILE_STATE_PROCESSING.
317 * @see stt_file_cancel()
319 int stt_file_start(const char* language, const char* type, const char* filepath,
320 stt_file_audio_type_e audio_type, int sample_rate);
323 * @brief Cancels processing recognition.
325 * @return 0 on success, otherwise a negative error value
326 * @retval #STT_FILE_ERROR_NONE Successful
327 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
328 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
330 * @pre The state should be #STT_FILE_STATE_PROCESSING.
331 * @post It will invoke stt_file_state_changed_cb(), if you register a callback with stt_file_state_changed_cb(). \n
332 * If this function succeeds, the STT state will be #STT_FILE_STATE_READY.
334 * @see stt_file_start()
336 int stt_file_cancel(void);
340 * @brief Retrieves time stamp of current recognition result using callback function.
342 * @param[in] callback The callback function to invoke
343 * @param[in] user_data The user data to be passed to the callback function
345 * @return 0 on success, otherwise a negative error value
346 * @retval #STT_FILE_ERROR_NONE Successful
347 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
348 * @retval #STT_FILE_ERROR_OPERATION_FAILED Operation failure
349 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
351 * @pre This function should be called in stt_file_recognition_result_cb().
352 * @post This function invokes stt_file_result_time_cb() repeatedly for getting time information.
354 * @see stt_file_result_time_cb()
355 * @see stt_file_recognition_result_cb()
357 int stt_file_foreach_detailed_result(stt_file_result_time_cb callback, void* user_data);
360 * @brief Registers a callback function for getting recognition result.
362 * @param[in] callback The callback function to register
363 * @param[in] user_data The user data to be passed to the callback function
365 * @return 0 on success, otherwise a negative error value
366 * @retval #STT_FILE_ERROR_NONE Successful
367 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
368 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
370 * @pre The state should be #STT_FILE_STATE_READY.
372 * @see stt_file_recognition_result_cb()
373 * @see stt_file_unset_recognition_result_cb()
375 int stt_file_set_recognition_result_cb(stt_file_recognition_result_cb callback, void* user_data);
378 * @brief Unregisters the callback function.
380 * @return 0 on success, otherwise a negative error value
381 * @retval #STT_FILE_ERROR_NONE Successful
382 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
384 * @pre The state should be #STT_FILE_STATE_READY.
386 * @see stt_file_set_recognition_result_cb()
388 int stt_file_unset_recognition_result_cb(void);
391 * @brief Registers a callback function to be called when STT FILE state changes.
393 * @param[in] callback The callback function to register
394 * @param[in] user_data The user data to be passed to the callback function
396 * @return 0 on success, otherwise a negative error value
397 * @retval #STT_FILE_ERROR_NONE Successful
398 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
399 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
401 * @pre The state should be #STT_FILE_STATE_READY.
403 * @see stt_file_state_changed_cb()
404 * @see stt_file_unset_state_changed_cb()
406 int stt_file_set_state_changed_cb(stt_file_state_changed_cb callback, void* user_data);
409 * @brief Unregisters the callback function.
411 * @return 0 on success, otherwise a negative error value
412 * @retval #STT_FILE_ERROR_NONE Successful
413 * @retval #STT_FILE_ERROR_INVALID_PARAMETER Invalid parameter
414 * @retval #STT_FILE_ERROR_INVALID_STATE Invalid state
416 * @pre The state should be #STT_FILE_STATE_READY.
418 * @see stt_file_set_state_changed_cb()
420 int stt_file_unset_state_changed_cb(void);
431 #endif /* __STT_FILE_H__ */