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.
18 #ifndef __TIZEN_UIX_STT_DOC_H__
19 #define __TIZEN_UIX_STT_DOC_H__
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @defgroup CAPI_UIX_STT_MODULE STT
25 * @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.
33 * To use of STT, use the following steps:<br>
34 * 1. Create a handle <br>
35 * 2. Register callback functions for notifications <br>
36 * 3. Prepare stt-service asynchronously <br>
37 * 4. Start recording for recognition <br>
38 * 5. Stop recording <br>
39 * 6. Get result after processing <br>
40 * 7. Destroy a handle <br>
41 * The STT has a client-server for the service of multi-applications.
42 * The STT service always works in the background as a server.
43 * If the service is not working, client library will invoke it and client will communicate with it.
44 * The service has engines and the recorder so client does not have the recorder itself.
45 * Only the client request commands to the STT service for using STT.
47 * @section CAPI_STT_MODULE_STATE_DIAGRAM State Diagram
48 * The following diagram shows the life cycle and the states of the STT.
50 * @image html capi_uix_stt_state_diagram.png "State diagram"
52 * @section CAPI_STT_MODULE_STATE_TRANSITIONS State Transitions
61 * <td>stt_prepare()</td>
67 * <td>stt_start()</td>
80 * <td>stt_cancel()</td>
81 * <td>Recording or Processing</td>
87 * @section CAPI_STT_MODULE_STATE_DEPENDENT_FUNCTION_FUNCTION_CALLS State Dependent Function Calls
88 * The following table shows state-dependent function calls. It is forbidden to call functions listed below in wrong states.
89 * Violation of this rule may result in an unpredictable behavior.
93 * <th>VALID STATES</th>
94 * <th>DESCRIPTION</th>
97 * <td>stt_create()</td>
99 * <td>All functions must be called after stt_create().</td>
102 * <td>stt_destroy()</td>
103 * <td>Created, Ready, Recording, Processing</td>
107 * <td>stt_prepare()</td>
109 * <td>This function works asynchronously. If the STT service fork is failed, application gets the error callback.</td>
112 * <td>stt_unprepare()</td>
117 * <td>stt_foreach_supported_engines()</td>
122 * <td>stt_get_engine()</td>
127 * <td>stt_set_engine()</td>
132 * <td>stt_foreach_supported_languages()</td>
133 * <td>Created, Ready, Recording, Processing</td>
137 * <td>stt_get_default_language()</td>
138 * <td>Created, Ready, Recording, Processing</td>
142 * <td>stt_get_state()</td>
143 * <td>Created, Ready, Recording, Processing</td>
147 * <td>stt_is_recognition_type_supported()</td>
152 * <td>stt_set_silence_detection()</td>
157 * <td>stt_set_start_sound()<br>stt_unset_start_sound()<br>stt_set_stop_sound()<br>stt_unset_stop_sound()</td>
162 * <td>stt_set_credential()</td>
163 * <td>Created, Ready</td>
167 * <td>stt_set_private_data()<br>stt_get_private_data()</td>
172 * <td>stt_get_error_message()</td>
173 * <td>Created, Ready, Recording, Processing</td>
174 * <td>This function should be called during STT error callback.</td>
177 * <td>stt_start()</td>
182 * <td>stt_stop()</td>
187 * <td>stt_cancel()</td>
188 * <td>Recording, Processing</td>
192 * <td>stt_get_recording_volume()</td>
197 * <td>stt_foreach_detailed_result()</td>
198 * <td>Processing</td>
199 * <td>This must be called in stt_recognition_result_cb().</td>
202 * <td>stt_set_recognition_result_cb()<br>stt_unset_recognition_result_cb()<br>
203 * stt_set_state_changed_cb()<br>stt_unset_state_changed_cb()<br>stt_set_error_cb()<br>stt_unset_error_cb()<br>
204 * stt_set_default_language_changed_cb()<br>stt_unset_default_language_changed_cb()<br>
205 * stt_set_engine_changed_cb()<br>stt_unset_engine_changed_cb()
208 * <td>All callback function should be registered / unregistered in Created state.</td>
212 * @section CAPI_UIX_STT_MODULE_FEATURE Related Features
213 * This API is related with the following features:<br>
214 * - http://tizen.org/feature/speech.recognition<br>
215 * - http://tizen.org/feature/microphone<br>
216 * It is recommended to design feature related codes in your application for reliability.<br>
217 * 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>
218 * 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>
219 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
223 #endif /* __TIZEN_UIX_STT_DOC_H__ */