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_DOC_H__
19 #define __TIZEN_UIX_TTS_DOC_H__
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @defgroup CAPI_UIX_TTS_MODULE TTS
25 * @brief The @ref CAPI_UIX_TTS_MODULE API provides functions for synthesizing voice from text and playing synthesized sound data.
26 * @section CAPI_UIX_TTS_MODULE_HEADER Required Header
29 * @section CAPI_UIX_TTS_MODULE_OVERVIEW Overview
30 * You can use Text-To-Speech (TTS) API to read sound data transformed by the engine from input texts.
31 * Applications can add input-text to queue for reading continuously and control the player that can play, pause, and stop sound data synthesized from text.
32 * To use TTS, follow these steps:<br>
33 * 1. Create a handle <br>
34 * 2. Register callback functions for notifications <br>
35 * 3. Prepare tts-daemon asynchronously <br>
36 * 4. Add text to queue for speech <br>
37 * 5. Start synthesizing voice from text and play synthesized sound data <br>
38 * 6. Pause the player <br>
39 * 7. Resume the player <br>
40 * 8. Stop the player <br>
41 * 9. Destroy a handle <br>
42 * The TTS API also notifies you (by callback mechanism) when the state of TTS is changed,
43 * utterance is started and completed, default voice is changed or an error occurred.
44 * An application should register callback functions: tts_state_changed_cb(), tts_utterance_started_cb(),
45 * tts_utterance_completed_cb(), tts_default_voice_changed_cb(), tts_error_cb(), tts_engine_changed_cb().
47 * @section CAPI_UIX_TTS_MODULE_STATE_DIAGRAM State Diagram
48 * The following diagram shows the life cycle and the states of the TTS.
49 * This state diagram shows that the state can be changed from 'None' to 'Created' by calling the tts_create() function.
50 * Similarly, you can know the relation between the states and API functions.
51 * You need to know the current state before calling the API, because the TTS API is based on state machine.
52 * The current state can be known from the state changed callback.
54 * @image html capi_uix_tts_state_diagram.png "State diagram"
56 * @section CAPI_UIX_TTS_MODULE_STATE_TRANSITIONS State Transitions
57 * The following table shows previous state and post state of main function.
58 * It can be known what precondition is and which synchronous type is.
59 * Please check both previous state and post state from the table carefully.
60 * In case of tts_prepare() function, state doesn't be changed at once, but asynchronously.
61 * From the above state diagram, you can see dotted line as asynchronous api.
62 * In this case, the state changed callback is only way to know state transition as ready.
71 * <td>tts_prepare()</td>
78 * <td>Ready, Paused</td>
84 * <td>Ready, Playing, Paused</td>
89 * <td>tts_pause()</td>
96 * @section CAPI_UIX_TTS_MODULE_STATE_DEPENDENT_FUNCTION_CALLS State Dependent Function Calls
97 * The following table shows state-dependent function calls.
98 * It is forbidden to call functions listed below in wrong states.
99 * Violation of this rule may result in an unpredictable behavior.
103 * <th>VALID STATES</th>
104 * <th>DESCRIPTION</th>
107 * <td>tts_create()</td>
109 * <td>All functions must be called after tts_create()</td>
112 * <td>tts_destroy()</td>
113 * <td>Created, Ready, Playing, Paused</td>
117 * <td>tts_set_mode()</td>
119 * <td>The application should set mode to use TTS for screen reader or notification like driving mode.</td>
122 * <td>tts_get_mode()</td>
127 * <td>tts_prepare()</td>
129 * <td>This function works asynchronously. If daemon fork is failed, application gets the error callback.</td>
132 * <td>tts_unprepare()</td>
137 * <td>tts_foreach_supported_voices()</td>
138 * <td>Created, Ready, Playing, Paused</td>
142 * <td>tts_get_default_voice()</td>
143 * <td>Created, Ready, Playing, Paused</td>
147 * <td>tts_get_state()</td>
148 * <td>Created, Ready, Playing, Paused</td>
152 * <td>tts_get_max_text_size()</td>
157 * <td>tts_get_speed_range()</td>
162 * <td>tts_set_credential()</td>
163 * <td>Created, Ready</td>
167 * <td>tts_set_private_data()<br>tts_get_private_data()</td>
172 * <td>tts_get_error_message()</td>
173 * <td>Created, Ready, Recording, Processing</td>
174 * <td>This function should be called during TTS error callback.</td>
177 * <td>tts_add_text()</td>
178 * <td>Ready, Playing, Paused</td>
182 * <td>tts_play()</td>
183 * <td>Ready, Paused</td>
187 * <td>tts_stop()</td>
188 * <td>Ready, Playing, Paused</td>
192 * <td>tts_pause()</td>
198 * tts_set_state_changed_cb()<br>
199 * tts_unset_state_changed_cb()<br>
200 * tts_set_utterance_started_cb()<br>
201 * tts_unset_utterance_started_cb()<br>
202 * tts_set_utterance_completed_cb()<br>
203 * tts_unset_utterance_completed_cb()<br>
204 * tts_set_default_voice_changed_cb()<br>
205 * tts_unset_default_voice_changed_cb()<br>
206 * tts_set_error_cb()<br>
207 * tts_unset_error_cb()<br>
208 * tts_set_engine_changed_cb()<br>
209 * tts_unset_engine_changed_cb()</td>
211 * <td> All callback function should be registered in Created state </td>
215 * @section CAPI_UIX_TTS_MODULE_FEATURE Related Features
216 * This API is related with the following features:<br>
217 * - http://tizen.org/feature/speech.synthesis<br>
218 * It is recommended to design feature related codes in your application for reliability.<br>
219 * 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>
220 * 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>
221 * 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>
225 #endif /* __TIZEN_UIX_TTS_DOC_H__ */