2 * Copyright (c) 2011-2014 Samsung Electronics Co., Ltd All Rights Reserved
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 * http://www.apache.org/licenses/LICENSE-2.0
7 * Unless required by applicable law or agreed to in writing, software
8 * distributed under the License is distributed on an "AS IS" BASIS,
9 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10 * See the License for the specific language governing permissions and
11 * limitations under the License.
21 * @addtogroup STT_ENGINE_MODULE
30 * @brief Enumerations of error codes.
33 STTP_ERROR_NONE = 0, /**< Successful */
34 STTP_ERROR_OUT_OF_MEMORY = -ENOMEM, /**< Out of Memory */
35 STTP_ERROR_IO_ERROR = -EIO, /**< I/O error */
36 STTP_ERROR_INVALID_PARAMETER = -EINVAL, /**< Invalid parameter */
37 STTP_ERROR_OUT_OF_NETWORK = -ENETDOWN, /**< Out of network */
38 STTP_ERROR_INVALID_STATE = -0x0100031, /**< Invalid state */
39 STTP_ERROR_INVALID_LANGUAGE = -0x0100032, /**< Invalid language */
40 STTP_ERROR_OPERATION_FAILED = -0x0100034, /**< Operation failed */
41 STTP_ERROR_NOT_SUPPORTED_FEATURE= -0x0100035 /**< Not supported feature */
45 * @brief Enumerations of audio type.
48 STTP_AUDIO_TYPE_PCM_S16_LE = 0, /**< Signed 16bit audio type, Little endian */
49 STTP_AUDIO_TYPE_PCM_U8 /**< Unsigned 8bit audio type */
53 * @brief Enumerations of callback event.
56 STTP_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the recognition full or last result is ready */
57 STTP_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the recognition partial result is ready */
58 STTP_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
62 * @brief Enumerations of result time callback event.
65 STTP_RESULT_TIME_EVENT_BEGINNING = 0, /**< Event when the token is beginning type */
66 STTP_RESULT_TIME_EVENT_MIDDLE, /**< Event when the token is middle type */
67 STTP_RESULT_TIME_EVENT_END /**< Event when the token is end type */
68 }sttp_result_time_event_e;
71 * @brief Enumerations of silence type.
74 STTP_SILENCE_TYPE_NO_RECORD_TIMEOUT = 0, /**< No sound is recorded */
75 STTP_SILENCE_TYPE_END_OF_SPEECH_DETECTED /**< End of speech is detected */
79 * @brief Recognition type : free form dictation and default type.
81 #define STTP_RECOGNITION_TYPE_FREE "stt.recognition.type.FREE"
84 * @brief Recognition type : free form dictation continuously.
86 #define STTP_RECOGNITION_TYPE_FREE_PARTIAL "stt.recognition.type.FREE.PARTIAL"
89 * @brief Recognition type : Search.
91 #define STTP_RECOGNITION_TYPE_SEARCH "stt.recognition.type.SEARCH"
94 * @brief Recognition type : web search.
96 #define STTP_RECOGNITION_TYPE_WEB_SEARCH "stt.recognition.type.WEB_SEARCH"
99 * @brief Recognition type : Map.
101 #define STTP_RECOGNITION_TYPE_MAP "stt.recognition.type.MAP"
105 * @brief Result message : None message
107 #define STTP_RESULT_MESSAGE_NONE "stt.result.message.none"
110 * @brief Result error message : Recognition was failed because the speech started too soon
112 #define STTP_RESULT_MESSAGE_ERROR_TOO_SOON "stt.result.message.error.too.soon"
115 * @brief Result error message : Recognition was failed because the speech started too short
117 #define STTP_RESULT_MESSAGE_ERROR_TOO_SHORT "stt.result.message.error.too.short"
120 * @brief Result error message : Recognition was failed because the speech started too long
122 #define STTP_RESULT_MESSAGE_ERROR_TOO_LONG "stt.result.message.error.too.long"
125 * @brief Result error message : Recognition was failed because the speech started too quiet to listen
127 #define STTP_RESULT_MESSAGE_ERROR_TOO_QUIET "stt.result.message.error.too.quiet"
130 * @brief Result error message : Recognition was failed because the speech started too loud to listen
132 #define STTP_RESULT_MESSAGE_ERROR_TOO_LOUD "stt.result.message.error.too.loud"
135 * @brief Result error message : Recognition was failed because the speech started too fast to listen
137 #define STTP_RESULT_MESSAGE_ERROR_TOO_FAST "stt.result.message.error.too.fast"
140 * @brief Called to get recognition result.
142 * @param[in] event A result event
143 * @param[in] type A recognition type (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_FREE_PARTIAL)
144 * @param[in] data Result texts
145 * @param[in] data_count Result text count
146 * @param[in] msg Engine message (e.g. #STTP_RESULT_MESSAGE_NONE, #STTP_RESULT_MESSAGE_ERROR_TOO_SHORT)
147 * @param[in] user_data The user data passed from the start function
149 * @pre sttpe_stop() will invoke this callback.
154 typedef void (*sttpe_result_cb)(sttp_result_event_e event, const char* type, const char** data, int data_count,
155 const char* msg, void* time_info, void* user_data);
158 * @brief Called to retrieve the time stamp of result.
160 * @param[in] index The result index
161 * @param[in] event The token event
162 * @param[in] text The result text
163 * @param[in] start_time The start time of result text
164 * @param[in] end_time The end time of result text
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
169 * @pre sttpe_result_cb() should be called.
171 * @see sttpe_result_cb()
173 typedef bool (*sttpe_result_time_cb)(int index, sttp_result_time_event_e event, const char* text,
174 long start_time, long end_time, void* user_data);
177 * @brief Called to detect silence from recording data.
179 * @param[in] user_data The user data passed from the start function.
181 * @pre sttpe_set_recording_data() will invoke this callback.
183 * @see sttpe_set_recording_data()
185 typedef void (*sttpe_silence_detected_cb)(sttp_silence_type_e type, void* user_data);
188 * @brief Called to retrieve the supported languages.
190 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
191 * followed by ISO 639-1 for the two-letter language code \n
192 * For example, "ko_KR" for Korean, "en_US" for American English
193 * @param[in] user_data The user data passed from the foreach function
195 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
197 * @pre sttpe_foreach_supported_languages() will invoke this callback.
199 * @see sttpe_foreach_supported_languages()
201 typedef bool (*sttpe_supported_language_cb)(const char* language, void* user_data);
204 * @brief Initializes the engine.
206 * @param[in] result_cb A callback function for recognition result
207 * @param[in] silence_cb A callback function for silence detection
209 * @return 0 on success, otherwise a negative error value
210 * @retval #STTP_ERROR_NONE Successful
211 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
212 * @retval #STTP_ERROR_INVALID_STATE Already initialized
213 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
215 * @see sttpe_deinitialize()
217 typedef int (* sttpe_initialize)(sttpe_result_cb result_cb, sttpe_silence_detected_cb silence_cb);
220 * @brief Deinitializes the engine
222 * @return 0 on success, otherwise a negative error value
223 * @retval #STTP_ERROR_NONE Successful
224 * @retval #STTP_ERROR_INVALID_STATE Not initialized
226 * @see sttpe_initialize()
228 typedef int (* sttpe_deinitialize)(void);
231 * @brief Retrieves all supported languages of the engine.
233 * @param[in] callback a callback function
234 * @param[in] user_data The user data to be passed to the callback function
236 * @return 0 on success, otherwise a negative error value
237 * @retval #STTP_ERROR_NONE Successful
238 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
239 * @retval #STTP_ERROR_INVALID_STATE Not initialized
241 * @post This function invokes sttpe_supported_language_cb() repeatedly for getting supported languages.
243 * @see sttpe_supported_language_cb()
245 typedef int (* sttpe_foreach_supported_langs)(sttpe_supported_language_cb callback, void* user_data);
248 * @brief Checks whether a language is valid or not.
250 * @param[in] language A language
252 * @return @c true to valid language, \n @c false to invalid language.
254 * @see sttpe_foreach_supported_languages()
256 typedef bool (* sttpe_is_valid_language)(const char* language);
259 * @brief Gets whether the engine supports silence detection.
261 * @return @c true to support silence detection, \n @c false not to support silence detection.
263 * @see sttpe_set_silence_detection()
265 typedef bool (* sttpe_support_silence_detection)(void);
268 * @brief Gets supporting recognition type.
270 * @return @c true to support recognition type, \n @c false not to support recognition type.
273 typedef bool (* sttpe_support_recognition_type)(const char* type);
276 * @brief Gets recording format of the engine.
278 * @param[out] types The format used by the recorder.
279 * @param[out] rate The sample rate used by the recorder.
280 * @param[out] channels The number of channels used by the recorder.
282 * @return 0 on success, otherwise a negative error value
283 * @retval #STTP_ERROR_NONE Successful
284 * @retval #STTP_ERROR_INVALID_STATE Not initialized
286 typedef int (* sttpe_get_recording_format)(sttp_audio_type_e* types, int* rate, int* channels);
289 * @brief Sets silence detection option.
291 * @param[in] value A value
293 * @return 0 on success, otherwise a negative error value
294 * @retval #STTP_ERROR_NONE Successful
295 * @retval #STTP_ERROR_INVALID_STATE Not initialized
296 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
298 typedef int (* sttpe_set_silence_detection)(bool value);
301 * @brief Gets whether application is agreed to get engine service.
303 * @param[in] appid Application ID
304 * @param[in] value A value
306 * @return 0 on success, otherwise a negative error value
307 * @retval #STTP_ERROR_NONE Successful
308 * @retval #STTP_ERROR_INVALID_STATE Not initialized
309 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
311 typedef int (* sttpe_check_app_agreed)(const char* appid, bool* value);
314 * @brief Retrieves result time info in recognition callback of daemon.
316 * @param[in] callback a callback function
317 * @param[in] user_data The user data to be passed to the callback function
319 * @return 0 on success, otherwise a negative error value
320 * @retval #STTP_ERROR_NONE Successful
321 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
322 * @retval #STTP_ERROR_INVALID_STATE Not initialized
324 * @pre sttpe_result_cb() will be invoke this function.
325 * @post This function invokes sttpe_result_time_cb() repeatedly for getting result time information.
327 * @see sttpe_result_time_cb()
329 typedef int (* sttpe_foreach_result_time)(void* time_info, sttpe_result_time_cb callback, void* user_data);
332 * @brief Start recognition.
334 * @param[in] language A language.
335 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
336 * @param[in] user_data The user data to be passed to the callback function.
338 * @return 0 on success, otherwise a negative error value
339 * @retval #STTP_ERROR_NONE Successful
340 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
341 * @retval #STTP_ERROR_INVALID_STATE Invalid state
342 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
343 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
344 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
346 * @pre The engine is not in recognition processing.
348 * @see sttpe_set_recording_data()
350 * @see sttpe_cancel()
352 typedef int (* sttpe_start)(const char* language, const char* type, void *user_data);
355 * @brief Sets recording data for speech recognition from recorder.
357 * @remark This function should be returned immediately after recording data copy.
359 * @param[in] data A recording data
360 * @param[in] length A length of recording data
362 * @return 0 on success, otherwise a negative error value
363 * @retval #STTP_ERROR_NONE Successful
364 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
365 * @retval #STTP_ERROR_INVALID_STATE Invalid state
366 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
368 * @pre sttpe_start() should succeed.
369 * @post If the engine supports partial result, it will invoke sttpe_result_cb().
372 * @see sttpe_cancel()
375 typedef int (* sttpe_set_recording_data)(const void* data, unsigned int length);
378 * @brief Stops to set recording data.
380 * @return 0 on success, otherwise a negative error value
381 * @retval #STTP_ERROR_NONE Successful
382 * @retval #STTP_ERROR_INVALID_STATE Invalid state
383 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
384 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
386 * @pre sttpe_start() should succeed.
387 * @post After processing of the engine, sttpe_result_cb() is called.
390 * @see sttpe_set_recording_data()
391 * @see sttpe_result_cb()
392 * @see sttpe_cancel()
394 typedef int (* sttpe_stop)(void);
397 * @brief Cancels the recognition process.
399 * @return 0 on success, otherwise a negative error value.
400 * @retval #STTP_ERROR_NONE Successful.
401 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
402 * @pre STT engine is in recognition processing or recording.
407 typedef int (* sttpe_cancel)(void);
410 * @brief Start recognition of file.
412 * @param[in] language A language.
413 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
414 * @param[in] filepath A filepath for recognition.
415 * @param[in] audio_type A audio type of file.
416 * @param[in] sample_rate A sample rate of file.
417 * @param[in] user_data The user data to be passed to the callback function.
419 * @return 0 on success, otherwise a negative error value
420 * @retval #STTP_ERROR_NONE Successful
421 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
422 * @retval #STTP_ERROR_INVALID_STATE Invalid state
423 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
424 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
425 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
427 * @pre The engine is not in recognition processing.
429 * @see sttpe_cancel_file()
431 typedef int (* sttpe_start_file)(const char* language, const char* type, const char* filepath,
432 sttp_audio_type_e audio_type, int sample_rate, void *user_data);
435 * @brief Cancels the recognition process of file.
437 * @return 0 on success, otherwise a negative error value.
438 * @retval #STTP_ERROR_NONE Successful.
439 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
440 * @pre STT engine is in recognition processing.
442 * @see sttpe_start_file()
444 typedef int (* sttpe_cancel_file)(void);
447 * @brief A structure of the engine functions.
450 int size; /**< Size of structure */
451 int version; /**< Version */
453 sttpe_initialize initialize; /**< Initialize engine */
454 sttpe_deinitialize deinitialize; /**< Shutdown engine */
456 /* Get engine information */
457 sttpe_foreach_supported_langs foreach_langs; /**< Foreach language list */
458 sttpe_is_valid_language is_valid_lang; /**< Check language */
459 sttpe_support_silence_detection support_silence; /**< Get silence detection support */
460 sttpe_support_recognition_type support_recognition_type; /**< Get recognition type support */
461 sttpe_get_recording_format get_audio_format; /**< Get audio format */
462 sttpe_foreach_result_time foreach_result_time; /**< Foreach result time */
464 /* Set engine information */
465 sttpe_set_silence_detection set_silence_detection; /**< Set silence detection */
467 /* Check app agreement */
468 sttpe_check_app_agreed check_app_agreed; /**< Get app agreement */
470 /* Control recognition */
471 sttpe_start start; /**< Start recognition */
472 sttpe_set_recording_data set_recording; /**< Set recording data */
473 sttpe_stop stop; /**< Shutdown function */
474 sttpe_cancel cancel; /**< Cancel recognition */
476 /* Control file recognition */
477 sttpe_start_file start_file; /**< Start recognition */
478 sttpe_cancel_file cancel_file; /**< Cancel recognition */
482 * @brief A structure of the daemon functions.
485 int size; /**< size */
486 int version; /**< version */
491 * @brief Loads the engine.
493 * @param[in] pdfuncs The daemon functions
494 * @param[out] pefuncs The engine functions
496 * @return This function returns zero on success, or negative with error code on failure
497 * @retval #STTP_ERROR_NONE Successful
498 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
499 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
501 * @pre The sttp_get_engine_info() should be successful.
502 * @post The daemon calls engine functions of sttpe_funcs_s.
504 * @see sttp_get_engine_info()
505 * @see sttp_unload_engine()
507 int sttp_load_engine(sttpd_funcs_s* pdfuncs, sttpe_funcs_s* pefuncs);
510 * @brief Unloads this engine by the daemon.
512 * @pre The sttp_load_engine() should be successful.
514 * @see sttp_load_engine()
516 void sttp_unload_engine(void);
519 * @brief Called to get the engine base information.
521 * @param[in] engine_uuid The engine id
522 * @param[in] engine_name The engine name
523 * @param[in] engine_setting The setting name
524 * @param[in] use_network @c true to need network @c false not to need network.
525 * @param[in] user_data The User data passed from sttp_get_engine_info()
527 * @pre sttp_get_engine_info() will invoke this callback.
529 * @see sttp_get_engine_info()
531 typedef void (*sttpe_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* engine_setting,
532 bool use_network, void* user_data);
535 * @brief Gets the engine base information before the engine is loaded by the daemon.
537 * @param[in] callback Callback function
538 * @param[in] user_data User data to be passed to the callback function
540 * @return This function returns zero on success, or negative with error code on failure
541 * @retval #STTP_ERROR_NONE Successful
542 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
543 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
545 * @post This function invokes sttpe_engine_info_cb() for getting engine information.
547 * @see sttpe_engine_info_cb()
548 * @see sttp_load_engine()
550 int sttp_get_engine_info(sttpe_engine_info_cb callback, void* user_data);
560 #endif /* __STTP_H__ */