2 * Copyright (c) 2011-2014 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_UIX_STT_DOC_H__
19 #define __TIZEN_UIX_STT_DOC_H__
22 * @defgroup CAPI_UIX_STT_MODULE STT
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @brief The @ref CAPI_UIX_STT_MODULE API provides functions to recognize the speech.
26 * @section CAPI_UIX_STT_MODULE_HEADER Required Header
29 * @section CAPI_UIX_STT_MODULE_OVERVIEW Overview
30 * A main function of Speech-To-Text (below STT) API recognizes sound data recorded by users.
31 * After choosing a language, applications will start recording and recognizing.
32 * After recording, the applications will receive the recognized result.
34 * To use of STT, use the following steps:<br>
35 * 1. Create a handle <br>
36 * 2. Register callback functions for notifications <br>
37 * 3. Prepare stt-daemon asynchronously <br>
38 * 4. Start recording for recognition <br>
39 * 5. Stop recording <br>
40 * 6. Get result after processing <br>
41 * 7. Destroy a handle <br>
43 * The STT has a client-server for the service of multi-applications.
44 * The STT daemon as a server always works in the background for the STT service.
45 * If the daemon is not working, client library will invoke it and client will communicate with it.
46 * The daemon has engines and the recorder so client does not have the recorder itself.
47 * Only the client request commands to the daemon for the service.
49 * @section CAPI_STT_MODULE_STATE_DIAGRAM State Diagram
50 * The following diagram shows the life cycle and the states of the STT.
52 * @image html capi_uix_stt_state_diagram.png "State diagram"
54 * @section CAPI_STT_MODULE_STATE_TRANSITIONS State Transitions
64 * <td>stt_prepare()</td>
70 * <td>stt_start()</td>
83 * <td>stt_cancel()</td>
84 * <td>Recording or Processing</td>
90 * @section CAPI_STT_MODULE_STATE_DEPENDENT_FUNCTION_FUNCTION_CALLS State Dependent Function Calls
91 * The following table shows state-dependent function calls. It is forbidden to call functions listed below in wrong states.
92 * Violation of this rule may result in an unpredictable behavior.
97 * <th>VALID STATES</th>
98 * <th>DESCRIPTION</th>
101 * <td>stt_create()</td>
103 * <td>All functions must be called after stt_create().</td>
106 * <td>stt_destroy()</td>
107 * <td>Created, Ready, Recording, Processing</td>
111 * <td>stt_prepare()</td>
113 * <td>This function works asynchronously. If daemon fork is failed, application gets the error callback.</td>
116 * <td>stt_unprepare()</td>
121 * <td>stt_foreach_supported_engines()</td>
126 * <td>stt_get_engine()</td>
131 * <td>stt_set_engine()</td>
136 * <td>stt_foreach_supported_languages()</td>
137 * <td>Created, Ready, Recording, Processing</td>
141 * <td>stt_get_default_language()</td>
142 * <td>Created, Ready, Recording, Processing</td>
146 * <td>stt_get_state()</td>
147 * <td>Created, Ready, Recording, Processing</td>
151 * <td>stt_is_recognition_type_supported()</td>
156 * <td>stt_set_silence_detection()</td>
161 * <td>stt_set_start_sound()<br>stt_unset_start_sound()<br>stt_set_stop_sound()<br>stt_unset_stop_sound()</td>
166 * <td>stt_start()</td>
171 * <td>stt_stop()</td>
176 * <td>stt_cancel()</td>
177 * <td>Recording, Processing</td>
181 * <td>stt_get_recording_volume()</td>
186 * <td>stt_foreach_detailed_result()</td>
187 * <td>Processing</td>
188 * <td>This must be called in stt_recognition_result_cb()</td>
191 * <td>stt_set_recognition_result_cb()<br>stt_unset_recognition_result_cb()<br>
192 * stt_set_state_changed_cb()<br>stt_unset_state_changed_cb()<br>stt_set_error_cb()<br>stt_unset_error_cb()<br>
193 * stt_set_default_language_changed_cb()<br>stt_unset_default_language_changed_cb()
196 * <td>All callback function should be registered / unregistered in Created state</td>
200 * @section CAPI_UIX_STT_MODULE_FEATURE Related Features
201 * This API is related with the following features:<br>
202 * - http://tizen.org/feature/speech.recognition<br>
203 * - http://tizen.org/feature/microphone<br>
205 * It is recommended to design feature related codes in your application for reliability.<br>
206 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.<br>
207 * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.<br>
208 * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
212 #endif /* __TIZEN_UIX_STT_DOC_H__ */