doc/uix_tts_doc.h

   1 /*
   2  * Copyright (c) 2011-2014 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_TTS_DOC_H__
  19 #define __TIZEN_UIX_TTS_DOC_H__
  20
  21 /**
  22  * @defgroup CAPI_UIX_TTS_MODULE TTS
  23  * @ingroup CAPI_UIX_FRAMEWORK
  24  * @brief The @ref CAPI_UIX_TTS_MODULE API provides functions for synthesizing voice from text and playing synthesized sound data.
  25  *
  26  * @section CAPI_UIX_TTS_MODULE_HEADER Required Header
  27  *   \#include <tts.h>
  28  *
  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  *
  33  * To use TTS, follow these steps:<br>
  34  * 1. Create a handle <br>
  35  * 2. Register callback functions for notifications <br>
  36  * 3. Prepare tts-daemon asynchronously <br>
  37  * 4. Add text to queue for speech <br>
  38  * 5. Start synthesizing voice from text and play synthesized sound data <br>
  39  * 6. Pause the player <br>
  40  * 7. Resume the player <br>
  41  * 8. Stop the player <br>
  42  * 9. Destroy a handle <br>
  43  *
  44  * The TTS API also notifies you (by callback mechanism) when the state of TTS is changed,
  45  * utterance is started and completed, default voice is changed or an error occured.
  46  * An application should register callback functions: tts_state_changed_cb(), tts_utterance_started_cb(),
  47  * tts_utterance_completed_cb(), tts_default_voice_changed_cb(), tts_error_cb().
  48  *
  49  * @section CAPI_UIX_TTS_MODULE_STATE_DIAGRAM State Diagram
  50  * The following diagram shows the life cycle and the states of the TTS.
  51  * This state diagram shows that the state can be changed from 'None' to 'Created' by calling the tts_create() function.
  52  * Similarly, you can know the relation between the states and API functions.
  53  * You need to know the current state before calling the API, because the TTS API is based on state machine.
  54  * The current state can be known from the state changed callback.
  55  *
  56  * @image html capi_uix_tts_state_diagram.png "State diagram"
  57  *
  58  * @section CAPI_UIX_TTS_MODULE_STATE_TRANSITIONS State Transitions
  59  * The following table shows previous state and post state of main function.
  60  * It can be known what precondition is and which synchronous type is.
  61  * Please check both previous state and post state from the table carefully.
  62  * In case of tts_prepare() function, state doesn't be changed at once, but acynchronously.
  63  * From the above state diagram, you can see dotted line as asynchronous api.
  64  * In this case, the state changed callback is only way to know state transition as ready.
  65  *
  66  * <table>
  67  * <tr>
  68  * <th>FUNCTION</th>
  69  * <th>PRE-STATE</th>
  70  * <th>POST-STATE</th>
  71  * <th>SYNC TYPE</th>
  72  * </tr>
  73  * <tr>
  74  * <td>tts_prepare()</td>
  75  * <td>Created</td>
  76  * <td>Ready</td>
  77  * <td>ASYNC</td>
  78  * </tr>
  79  * <tr>
  80  * <td>tts_play()</td>
  81  * <td>Ready, Paused</td>
  82  * <td>Playing</td>
  83  * <td>SYNC</td>
  84  * </tr>
  85  * <tr>
  86  * <td>tts_stop()</td>
  87  * <td>Ready, Playing, Paused</td>
  88  * <td>Ready</td>
  89  * <td>SYNC</td>
  90  * </tr>
  91  * <tr>
  92  * <td>tts_pause()</td>
  93  * <td>Playing</td>
  94  * <td>Paused</td>
  95  * <td>SYNC</td>
  96  * </tr>
  97  * </table>
  98  *
  99  * @section CAPI_UIX_TTS_MODULE_STATE_DEPENDENT_FUNCTION_CALLS State Dependent Function Calls
 100  * The following table shows state-dependent function calls.
 101  * It is forbidden to call functions listed below in wrong states.
 102  * Violation of this rule may result in an unpredictable behavior.
 103  *
 104  * <table>
 105  * <tr>
 106  * <th>FUNCTION</th>
 107  * <th>VALID STATES</th>
 108  * <th>DESCRIPTION</th>
 109  * </tr>
 110  * <tr>
 111  * <td>tts_create()</td>
 112  * <td>None</td>
 113  * <td>All functions must be called after tts_create()</td>
 114  * </tr>
 115  * <tr>
 116  * <td>tts_destroy()</td>
 117  * <td>Created, Ready, Playing, Paused</td>
 118  * <td></td>
 119  * </tr>
 120  * <tr>
 121  * <td>tts_set_mode()</td>
 122  * <td>Created</td>
 123  * <td>The application should set mode to use TTS for screen reader or notification like driving mode.</td>
 124  * </tr>
 125  * <tr>
 126  * <td>tts_get_mode()</td>
 127  * <td>Created</td>
 128  * <td></td>
 129  * </tr>
 130  * <tr>
 131  * <td>tts_prepare()</td>
 132  * <td>Created</td>
 133  * <td>This function works asynchronously. If daemon fork is failed, application gets the error callback.</td>
 134  * </tr>
 135  * <tr>
 136  * <td>tts_unprepare()</td>
 137  * <td>Ready</td>
 138  * <td></td>
 139  * </tr>
 140  * <tr>
 141  * <td>tts_foreach_supported_voices()</td>
 142  * <td>Created, Ready, Playing, Paused</td>
 143  * <td></td>
 144  * </tr>
 145  * <tr>
 146  * <td>tts_get_default_voice()</td>
 147  * <td>Created, Ready, Playing, Paused</td>
 148  * <td></td>
 149  * </tr>
 150  * <tr>
 151  * <td>tts_get_state()</td>
 152  * <td>Created, Ready, Playing, Paused</td>
 153  * <td></td>
 154  * </tr>
 155  * <tr>
 156  * <td>tts_get_max_text_size()</td>
 157  * <td>Ready</td>
 158  * <td></td>
 159  * </tr>
 160  * <tr>
 161  * <td>tts_get_speed_range()</td>
 162  * <td>Ready</td>
 163  * <td></td>
 164  * </tr>
 165  * <tr>
 166  * <td>tts_add_text()</td>
 167  * <td>Ready, Playing, Paused</td>
 168  * <td></td>
 169  * </tr>
 170  * <tr>
 171  * <td>tts_play()</td>
 172  * <td>Ready, Paused</td>
 173  * <td></td>
 174  * </tr>
 175  * <tr>
 176  * <td>tts_stop()</td>
 177  * <td>Ready, Playing, Paused</td>
 178  * <td></td>
 179  * </tr>
 180  * <tr>
 181  * <td>tts_pause()</td>
 182  * <td>Playing</td>
 183  * <td></td>
 184  * </tr>
 185  * <tr>
 186  * <td>
 187  * tts_set_state_changed_cb()<br>
 188  * tts_unset_state_changed_cb()<br>
 189  * tts_set_utterance_started_cb()<br>
 190  * tts_unset_utterance_started_cb()<br>
 191  * tts_set_utterance_completed_cb()<br>
 192  * tts_unset_utterance_completed_cb()<br>
 193  * tts_set_default_voice_changed_cb()<br>
 194  * tts_unset_default_voice_changed_cb()<br>
 195  * tts_set_error_cb()<br>
 196  * tts_unset_error_cb()</td>
 197  * <td>Created</td>
 198  * <td> All callback function should be registered in Created state </td>
 199  * </tr>
 200  * </table>
 201  *
 202  * @section CAPI_UIX_TTS_MODULE_FEATURE Related Features
 203  * This API is related with the following features:<br>
 204  *  - http://tizen.org/feature/speech.synthesis<br>
 205  *
 206  * It is recommended to design feature related codes in your application for reliability.<br>
 207  * 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>
 208  * 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>
 209  * 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>
 210  *
 211  */
 212
 213 #endif /* __TIZEN_UIX_TTS_DOC_H__ */
 214