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_TTS_ENGINE_DOC_H__
19 #define __TIZEN_UIX_TTS_ENGINE_DOC_H__
22 * @ingroup CAPI_UIX_FRAMEWORK
23 * @defgroup CAPI_UIX_TTSE_MODULE TTS Engine
24 * @brief The @ref CAPI_UIX_TTSE_MODULE APIs provide functions to operate Text-To-Speech Engine.
27 * @section CAPI_UIX_TTSE_MODULE_HEADER Required Header
31 * @section CAPI_UIX_TTSE_MODULE_OVERVIEW Overview
32 * Text-To-Speech Engine (below TTSE) is an engine for synthesizing voice from text and playing synthesized sound data.
33 * Using the @ref CAPI_UIX_TTSE_MODULE APIs, TTSE developers can provide TTSE service users, who want to apply TTSE, with functions necessary to operate the engine.
34 * According to the indispensability of TTSE services, there are two ways to provide them to the users. <br>
36 * <b>A. Required TTSE services</b> <br>
37 * These services are indispensable to operate TTSE. Therefore, the TTSE developers MUST implement callback functions corresponding to the required TTSE services.
38 * The following is a list of the callback functions. <br>
43 * <th>DESCRIPTION</th>
46 * <td>ttse_get_info_cb()</td>
47 * <td>Called when the engine service user requests the basic information of TTS engine.</td>
50 * <td>ttse_initialize_cb()</td>
51 * <td>Called when the engine service user initializes TTS engine.</td>
54 * <td>ttse_deinitialize_cb()</td>
55 * <td>Called when the engine service user deinitializes TTS engine.</td>
58 * <td>ttse_is_valid_voice_cb()</td>
59 * <td>Called when the engine service user checks whether the voice is valid or not in TTS engine.</td>
62 * <td>ttse_foreach_supported_voices_cb()</td>
63 * <td>Called when the engine service user gets the whole supported voice list.</td>
66 * <td>ttse_set_pitch_cb()</td>
67 * <td>Called when the engine service user sets the default pitch of TTS engine.</td>
70 * <td>ttse_load_voice_cb()</td>
71 * <td>Called when the engine service user requests to load the corresponding voice type for the first time.</td>
74 * <td>ttse_unload_voice_cb()</td>
75 * <td>Called when the engine service user requests to unload the corresponding voice type or to stop using voice.</td>
78 * <td>ttse_start_synthesis_cb()</td>
79 * <td>Called when the engine service user starts to synthesize a voice, asynchronously.</td>
82 * <td>ttse_cancel_synthesis_cb()</td>
83 * <td>Called when the engine service user cancels to synthesize a voice.</td>
86 * <td>ttse_check_app_agreed_cb()</td>
87 * <td>Called when the engine service user requests for TTS engine to check whether the application agreed the usage of TTS engine.</td>
90 * <td>ttse_need_app_credential_cb()</td>
91 * <td>Called when the engine service user checks whether TTS engine needs the application's credential.</td>
95 * The TTSE developers can register the above callback functions at a time with using a structure 'ttse_request_callback_s' and an API 'ttse_main()'.
96 * To operate TTSE, the following steps should be used: <br>
97 * 1. Create a structure 'ttse_request_callback_s'
98 * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
99 * If the callback function returns an unstated value, TTS framework will handle it as #TTSE_ERROR_OPERATION_FAILED.) <br>
100 * 3. Register callback functions using 'ttse_main()'. (The registered callback functions will be invoked when the TTSE service users request the TTSE services.) <br>
101 * 4. Use 'service_app_main()' for working TTSE. <br>
103 * <b>B. Optional TTSE services</b> <br>
104 * Unlike the required TTSE services, these services are optional to operate TTSE. The followings are optional TTSE services. <br>
105 * - receive/provide the private data <br>
107 * If the TTSE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
111 * <th>DESCRIPTION</th>
112 * <th>CORRESPONDING CALLBACK</th>
115 * <td>ttse_set_private_data_set_cb()</td>
116 * <td>Sets a callback function for receiving the private data from the engine service user.</td>
117 * <td>ttse_private_data_set_cb()</td>
120 * <td>ttse_set_private_data_requested_cb()</td>
121 * <td>Sets a callback function for providing the private data to the engine service user.</td>
122 * <td>ttse_private_data_requested_cb()</td>
126 * Using the above APIs, the TTSE developers can register the optional callback functions respectively.
127 * (For normal operation, put those APIs before 'service_app_main()' starts.)
129 * Unlike callback functions, the following APIs are functions for getting and sending data. The TTSE developers can use these APIs when they implement TTSE services: <br>
133 * <th>DESCRIPTION</th>
136 * <td>ttse_get_speed_range()</td>
137 * <td>Gets the speed range from Tizen platform.</td>
140 * <td>ttse_get_pitch_range()</td>
141 * <td>Gets the pitch range from Tizen platform.</td>
144 * <td>ttse_send_result()</td>
145 * <td>Sends the synthesized result to the engine service user.</td>
148 * <td>ttse_send_error()</td>
149 * <td>Sends the error to the engine service user.</td>
154 * @section CAPI_UIX_TTSE_MODULE_FEATURE Related Features
155 * This API is related with the following features:<br>
156 * - http://tizen.org/feature/speech.synthesis<br>
158 * It is recommended to design feature related codes in your application for reliability.<br>
159 * 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>
160 * 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>
161 * 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>
165 #endif /* __TIZEN_UIX_TTS_ENGINE_DOC_H__ */