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__
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @defgroup CAPI_UIX_TTSE_MODULE TTS Engine
25 * @brief The @ref CAPI_UIX_TTSE_MODULE APIs provide functions to operate Text-To-Speech Engine.
26 * @section CAPI_UIX_TTSE_MODULE_HEADER Required Header
29 * @section CAPI_UIX_TTSE_MODULE_OVERVIEW Overview
30 * Text-To-Speech Engine (below TTSE) is an engine for synthesizing voice from text and playing synthesized sound data.
31 * 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.
32 * According to the indispensability of TTSE services, there are two ways to provide them to the users. <br>
33 * <b>A. Required TTSE services</b> <br>
34 * These services are indispensable to operate TTSE. Therefore, the TTSE developers MUST implement callback functions corresponding to the required TTSE services.
35 * The following is a list of the callback functions. <br>
39 * <th>DESCRIPTION</th>
42 * <td>ttse_get_info_cb()</td>
43 * <td>Called when the engine service user requests the basic information of TTS engine.</td>
46 * <td>ttse_initialize_cb()</td>
47 * <td>Called when the engine service user initializes TTS engine.</td>
50 * <td>ttse_deinitialize_cb()</td>
51 * <td>Called when the engine service user deinitializes TTS engine.</td>
54 * <td>ttse_is_valid_voice_cb()</td>
55 * <td>Called when the engine service user checks whether the voice is valid or not in TTS engine.</td>
58 * <td>ttse_foreach_supported_voices_cb()</td>
59 * <td>Called when the engine service user gets the whole supported voice list.</td>
62 * <td>ttse_set_pitch_cb()</td>
63 * <td>Called when the engine service user sets the default pitch of TTS engine.</td>
66 * <td>ttse_load_voice_cb()</td>
67 * <td>Called when the engine service user requests to load the corresponding voice type for the first time.</td>
70 * <td>ttse_unload_voice_cb()</td>
71 * <td>Called when the engine service user requests to unload the corresponding voice type or to stop using voice.</td>
74 * <td>ttse_start_synthesis_cb()</td>
75 * <td>Called when the engine service user starts to synthesize a voice, asynchronously.</td>
78 * <td>ttse_cancel_synthesis_cb()</td>
79 * <td>Called when the engine service user cancels to synthesize a voice.</td>
82 * <td>ttse_check_app_agreed_cb()</td>
83 * <td>Called when the engine service user requests for TTS engine to check whether the application agreed the usage of TTS engine.</td>
86 * <td>ttse_need_app_credential_cb()</td>
87 * <td>Called when the engine service user checks whether TTS engine needs the application's credential.</td>
90 * 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()'.
91 * To operate TTSE, the following steps should be used: <br>
92 * 1. Create a structure 'ttse_request_callback_s'
93 * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
94 * If the callback function returns an unstated value, TTS framework will handle it as #TTSE_ERROR_OPERATION_FAILED.) <br>
95 * 3. Register callback functions using 'ttse_main()'. (The registered callback functions will be invoked when the TTSE service users request the TTSE services.) <br>
96 * 4. Use 'service_app_main()' for working TTSE. <br>
97 * <b>B. Optional TTSE services</b> <br>
98 * Unlike the required TTSE services, these services are optional to operate TTSE. The followings are optional TTSE services. <br>
99 * - receive/provide the private data <br>
100 * If the TTSE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
104 * <th>DESCRIPTION</th>
105 * <th>CORRESPONDING CALLBACK</th>
108 * <td>ttse_set_private_data_set_cb()</td>
109 * <td>Sets a callback function for receiving the private data from the engine service user.</td>
110 * <td>ttse_private_data_set_cb()</td>
113 * <td>ttse_set_private_data_requested_cb()</td>
114 * <td>Sets a callback function for providing the private data to the engine service user.</td>
115 * <td>ttse_private_data_requested_cb()</td>
118 * Using the above APIs, the TTSE developers can register the optional callback functions respectively.
119 * (For normal operation, put those APIs before 'service_app_main()' starts.)
120 * 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>
124 * <th>DESCRIPTION</th>
127 * <td>ttse_get_speed_range()</td>
128 * <td>Gets the speed range from Tizen platform.</td>
131 * <td>ttse_get_pitch_range()</td>
132 * <td>Gets the pitch range from Tizen platform.</td>
135 * <td>ttse_send_result()</td>
136 * <td>Sends the synthesized result to the engine service user.</td>
139 * <td>ttse_send_error()</td>
140 * <td>Sends the error to the engine service user.</td>
144 * @section CAPI_UIX_TTSE_MODULE_FEATURE Related Features
145 * This API is related with the following features:<br>
146 * - http://tizen.org/feature/speech.synthesis<br>
147 * It is recommended to design feature related codes in your application for reliability.<br>
148 * 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>
149 * 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>
150 * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
154 #endif /* __TIZEN_UIX_TTS_ENGINE_DOC_H__ */