doc/uix_stt_doc.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 __TIZEN_UIX_STT_DOC_H__
  19 #define __TIZEN_UIX_STT_DOC_H__
  20
  21
  22 /**
  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
  27  * \#include <stt.h>
  28  *
  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.
  46  *
  47  * @section CAPI_STT_MODULE_STATE_DIAGRAM State Diagram
  48  * The following diagram shows the life cycle and the states of the STT.
  49  *
  50  * @image html capi_uix_stt_state_diagram.png "State diagram"
  51  *
  52  * @section CAPI_STT_MODULE_STATE_TRANSITIONS State Transitions
  53  * <table>
  54  * <tr>
  55  * <th>FUNCTION</th>
  56  * <th>PRE-STATE</th>
  57  * <th>POST-STATE</th>
  58  * <th>SYNC TYPE</th>
  59  * </tr>
  60  * <tr>
  61  * <td>stt_prepare()</td>
  62  * <td>Created</td>
  63  * <td>Ready</td>
  64  * <td>ASYNC</td>
  65  * </tr>
  66  * <tr>
  67  * <td>stt_start()</td>
  68  * <td>Ready</td>
  69  * <td>Recording</td>
  70  * <td>ASYNC</td>
  71  * </tr>
  72  * <tr>
  73  * <td>stt_stop()</td>
  74  * <td>Recording</td>
  75  * <td>Processing</td>
  76  * <td>ASYNC</td>
  77  * </tr>
  78  * </tr>
  79  * <tr>
  80  * <td>stt_cancel()</td>
  81  * <td>Recording or Processing</td>
  82  * <td>Ready</td>
  83  * <td>ASYNC</td>
  84  * </tr>
  85  * </table>
  86  *
  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.
  90  * <table>
  91  * <tr>
  92  * <th>FUNCTION</th>
  93  * <th>VALID STATES</th>
  94  * <th>DESCRIPTION</th>
  95  * </tr>
  96  * <tr>
  97  * <td>stt_create()</td>
  98  * <td>None</td>
  99  * <td>All functions must be called after stt_create().</td>
 100  * </tr>
 101  * <tr>
 102  * <td>stt_destroy()</td>
 103  * <td>Created, Ready, Recording, Processing</td>
 104  * <td></td>
 105  * </tr>
 106  * <tr>
 107  * <td>stt_prepare()</td>
 108  * <td>Created</td>
 109  * <td>This function works asynchronously. If the STT service fork is failed, application gets the error callback.</td>
 110  * </tr>
 111  * <tr>
 112  * <td>stt_unprepare()</td>
 113  * <td>Ready</td>
 114  * <td></td>
 115  * </tr>
 116  * <tr>
 117  * <td>stt_foreach_supported_engines()</td>
 118  * <td>Created</td>
 119  * <td></td>
 120  * </tr>
 121  * <tr>
 122  * <td>stt_get_engine()</td>
 123  * <td>Created</td>
 124  * <td></td>
 125  * </tr>
 126  * <tr>
 127  * <td>stt_set_engine()</td>
 128  * <td>Created</td>
 129  * <td></td>
 130  * </tr>
 131  * <tr>
 132  * <td>stt_foreach_supported_languages()</td>
 133  * <td>Created, Ready, Recording, Processing</td>
 134  * <td></td>
 135  * </tr>
 136  * <tr>
 137  * <td>stt_get_default_language()</td>
 138  * <td>Created, Ready, Recording, Processing</td>
 139  * <td></td>
 140  * </tr>
 141  * <tr>
 142  * <td>stt_get_state()</td>
 143  * <td>Created, Ready, Recording, Processing</td>
 144  * <td></td>
 145  * </tr>
 146  * <tr>
 147  * <td>stt_is_recognition_type_supported()</td>
 148  * <td>Ready</td>
 149  * <td></td>
 150  * </tr>
 151  * <tr>
 152  * <td>stt_set_silence_detection()</td>
 153  * <td>Ready</td>
 154  * <td></td>
 155  * </tr>
 156  * <tr>
 157  * <td>stt_set_start_sound()<br>stt_unset_start_sound()<br>stt_set_stop_sound()<br>stt_unset_stop_sound()</td>
 158  * <td>Ready</td>
 159  * <td></td>
 160  * </tr>
 161  * <tr>
 162  * <td>stt_set_credential()</td>
 163  * <td>Created, Ready</td>
 164  * <td></td>
 165  * </tr>
 166  * <tr>
 167  * <td>stt_set_private_data()<br>stt_get_private_data()</td>
 168  * <td>Ready</td>
 169  * <td></td>
 170  * </tr>
 171  * <tr>
 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>
 175  * </tr>
 176  * <tr>
 177  * <td>stt_start()</td>
 178  * <td>Ready</td>
 179  * <td></td>
 180  * </tr>
 181  * <tr>
 182  * <td>stt_stop()</td>
 183  * <td>Recording</td>
 184  * <td></td>
 185  * </tr>
 186  * <tr>
 187  * <td>stt_cancel()</td>
 188  * <td>Recording, Processing</td>
 189  * <td></td>
 190  * </tr>
 191  * <tr>
 192  * <td>stt_get_recording_volume()</td>
 193  * <td>Recording</td>
 194  * <td></td>
 195  * </tr>
 196  * <tr>
 197  * <td>stt_foreach_detailed_result()</td>
 198  * <td>Processing</td>
 199  * <td>This must be called in stt_recognition_result_cb().</td>
 200  * </tr>
 201  * <tr>
 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()
 206  * </td>
 207  * <td>Created</td>
 208  * <td>All callback function should be registered / unregistered in Created state.</td>
 209  * </tr>
 210  * </table>
 211  *
 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/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
 220  */
 221
 222
 223 #endif /* __TIZEN_UIX_STT_DOC_H__ */
 224