Tizen Native API
|
Functions | |
int | tts_create (tts_h *tts) |
Creates a handle for TTS. | |
int | tts_destroy (tts_h tts) |
Destroys the handle and disconnects the daemon. | |
int | tts_set_mode (tts_h tts, tts_mode_e mode) |
Sets the TTS mode. | |
int | tts_get_mode (tts_h tts, tts_mode_e *mode) |
Gets the TTS mode. | |
int | tts_prepare (tts_h tts) |
Connects the daemon asynchronously. | |
int | tts_unprepare (tts_h tts) |
Disconnects the daemon. | |
int | tts_foreach_supported_voices (tts_h tts, tts_supported_voice_cb callback, void *user_data) |
Retrieves all supported voices of the current engine using callback function. | |
int | tts_get_default_voice (tts_h tts, char **language, int *voice_type) |
Gets the default voice set by the user. | |
int | tts_get_max_text_size (tts_h tts, unsigned int *size) |
Gets the maximum byte size for text. | |
int | tts_get_state (tts_h tts, tts_state_e *state) |
Gets the current state of TTS. | |
int | tts_get_speed_range (tts_h tts, int *min, int *normal, int *max) |
Gets the speed range. | |
int | tts_add_text (tts_h tts, const char *text, const char *language, int voice_type, int speed, int *utt_id) |
Adds a text to the queue. | |
int | tts_play (tts_h tts) |
Starts synthesizing voice from the text and plays the synthesized audio data. | |
int | tts_stop (tts_h tts) |
Stops playing the utterance and clears the queue. | |
int | tts_pause (tts_h tts) |
Pauses the currently playing utterance. | |
int | tts_set_state_changed_cb (tts_h tts, tts_state_changed_cb callback, void *user_data) |
Registers a callback function to be called when the TTS state changes. | |
int | tts_unset_state_changed_cb (tts_h tts) |
Unregisters the callback function. | |
int | tts_set_utterance_started_cb (tts_h tts, tts_utterance_started_cb callback, void *user_data) |
Registers a callback function to detect utterance start. | |
int | tts_unset_utterance_started_cb (tts_h tts) |
Unregisters the callback function. | |
int | tts_set_utterance_completed_cb (tts_h tts, tts_utterance_completed_cb callback, void *user_data) |
Registers a callback function to detect utterance completion. | |
int | tts_unset_utterance_completed_cb (tts_h tts) |
Unregisters the callback function. | |
int | tts_set_error_cb (tts_h tts, tts_error_cb callback, void *user_data) |
Registers a callback function to detect errors. | |
int | tts_unset_error_cb (tts_h tts) |
Unregisters the callback function. | |
int | tts_set_default_voice_changed_cb (tts_h tts, tts_default_voice_changed_cb callback, void *user_data) |
Registers a callback function to detect default voice change. | |
int | tts_unset_default_voice_changed_cb (tts_h tts) |
Unregisters the callback function. | |
Typedefs | |
typedef struct tts_s * | tts_h |
The TTS handle. | |
typedef void(* | tts_state_changed_cb )(tts_h tts, tts_state_e previous, tts_state_e current, void *user_data) |
Called when the state of TTS is changed. | |
typedef void(* | tts_utterance_started_cb )(tts_h tts, int utt_id, void *user_data) |
Called when utterance has started. | |
typedef void(* | tts_utterance_completed_cb )(tts_h tts, int utt_id, void *user_data) |
Called when utterance is finished. | |
typedef void(* | tts_error_cb )(tts_h tts, int utt_id, tts_error_e reason, void *user_data) |
Called when an error occurs. | |
typedef bool(* | tts_supported_voice_cb )(tts_h tts, const char *language, int voice_type, void *user_data) |
Called to retrieve the supported voice. | |
typedef void(* | tts_default_voice_changed_cb )(tts_h tts, const char *previous_language, int previous_voice_type, const char *current_language, int current_voice_type, void *user_data) |
Called when the default voice is changed. | |
Defines | |
#define | TTS_SPEED_AUTO 0 |
Definitions for automatic speaking speed. | |
#define | TTS_VOICE_TYPE_AUTO 0 |
Definitions for automatic voice type. | |
#define | TTS_VOICE_TYPE_MALE 1 |
Definitions for male voice type. | |
#define | TTS_VOICE_TYPE_FEMALE 2 |
Definitions for female voice type. | |
#define | TTS_VOICE_TYPE_CHILD 3 |
Definitions for child voice type. |
The TTS API provides functions for synthesizing voice from text and playing synthesized sound data.
#include <tts.h>
A main function of Text-To-Speech(below TTS) API reads sound data transformed by the engine using input texts. Applications can add input-text to queue for reading continuously and control a player that can play, pause, and stop sound data synthesized from text.
To use of TTS, use the following steps:
1. Create a handle
2. Register callback functions for notifications
3. Prepare tts-daemon asynchronously
4. Add text to queue for speech
5. Start synthesizing voice from text and play synthesized sound data
6. Pause the player
7. Resume the player
8. Stop the player
9. Destroy a handle
The TTS API also notifies you (by callback mechanism) when the state of TTS is changed, utterance is started and completed, default voice is changed or an error occured. An application should register callback functions: tts_state_changed_cb(), tts_utterance_started_cb(), tts_utterance_completed_cb(), tts_default_voice_changed_cb(), tts_error_cb().
The following diagram shows the life cycle and the states of the TTS.
FUNCTION | PRE-STATE | POST-STATE | SYNC TYPE |
---|---|---|---|
tts_prepare() | Created | Ready | ASYNC |
tts_play() | Ready, Paused | Playing | SYNC |
tts_stop() | Ready, Playing, Paused | Ready | SYNC |
tts_pause() | Playing | Paused | SYNC |
The following table shows state-dependent function calls. It is forbidden to call functions listed below in wrong states. Violation of this rule may result in an unpredictable behavior.
FUNCTION | VALID STATES | DESCRIPTION |
---|---|---|
tts_create() | None | All functions must be called after tts_create() |
tts_destroy() | Created, Ready, Playing, Paused | |
tts_set_mode() | Created | The application should set mode to use TTS for screen reader or notification like driving mode. |
tts_get_mode() | Created | |
tts_prepare() | Created | This function works asynchronously. If daemon fork is failed, application gets the error callback. |
tts_unprepare() | Ready | |
tts_foreach_supported_voices() | Created, Ready, Playing, Paused | |
tts_get_default_voice() | Created, Ready, Playing, Paused | |
tts_get_state() | Created, Ready, Playing, Paused | |
tts_get_max_text_size() | Ready | |
tts_get_speed_range() | Ready | |
tts_add_text() | Ready, Playing, Paused | |
tts_play() | Ready, Paused | |
tts_stop() | Ready, Playing, Paused | |
tts_pause() | Playing | |
tts_set_state_changed_cb() tts_unset_state_changed_cb() tts_set_utterance_started_cb() tts_unset_utterance_started_cb() tts_set_utterance_completed_cb() tts_unset_utterance_completed_cb() tts_set_default_voice_changed_cb() tts_unset_default_voice_changed_cb() tts_set_error_cb() tts_unset_error_cb() | Created | All callback function should be registered in Created state |
This API is related with the following features:
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
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.
More details on featuring your application can be found from Feature Element.
#define TTS_SPEED_AUTO 0 |
Definitions for automatic speaking speed.
#define TTS_VOICE_TYPE_AUTO 0 |
Definitions for automatic voice type.
#define TTS_VOICE_TYPE_CHILD 3 |
Definitions for child voice type.
#define TTS_VOICE_TYPE_FEMALE 2 |
Definitions for female voice type.
#define TTS_VOICE_TYPE_MALE 1 |
Definitions for male voice type.
typedef void(* tts_default_voice_changed_cb)(tts_h tts, const char *previous_language, int previous_voice_type, const char *current_language, int current_voice_type, void *user_data) |
Called when the default voice is changed.
[in] | tts | The TTS handle |
[in] | previous_language | The previous language |
[in] | previous_voice_type | The previous voice type |
[in] | current_language | The current language |
[in] | current_voice_type | The current voice type |
[in] | user_data | The user data passed from the callback registration function |
typedef void(* tts_error_cb)(tts_h tts, int utt_id, tts_error_e reason, void *user_data) |
Called when an error occurs.
[in] | tts | The TTS handle |
[in] | utt_id | The utterance ID passed from the add text function |
[in] | reason | The error code |
[in] | user_data | The user data passed from the callback registration function |
typedef struct tts_s* tts_h |
The TTS handle.
typedef void(* tts_state_changed_cb)(tts_h tts, tts_state_e previous, tts_state_e current, void *user_data) |
Called when the state of TTS is changed.
If the daemon must stop player because of changing engine and the daemon must pause player because of other requests, this callback function is called.
[in] | tts | The TTS handle |
[in] | previous | The previous state |
[in] | current | The current state |
[in] | user_data | The user data passed from the callback registration function |
typedef bool(* tts_supported_voice_cb)(tts_h tts, const char *language, int voice_type, void *user_data) |
Called to retrieve the supported voice.
[in] | tts | The TTS handle |
[in] | language | Language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English) |
[in] | voice_type | A voice type (e.g. TTS_VOICE_TYPE_MALE, TTS_VOICE_TYPE_FEMALE) |
[in] | user_data | The user data passed from the foreach function |
true
to continue with the next iteration of the loop, false
to break out of the loop typedef void(* tts_utterance_completed_cb)(tts_h tts, int utt_id, void *user_data) |
Called when utterance is finished.
[in] | tts | The TTS handle |
[in] | utt_id | The utterance ID passed from the add text function |
[in] | user_data | The user data passed from the callback registration function |
typedef void(* tts_utterance_started_cb)(tts_h tts, int utt_id, void *user_data) |
Called when utterance has started.
[in] | tts | The TTS handle |
[in] | utt_id | The utterance ID passed from the add text function |
[in] | user_data | The user data passed from the callback registration function |
enum tts_error_e |
Enumeration for error code.
enum tts_mode_e |
enum tts_state_e |
int tts_add_text | ( | tts_h | tts, |
const char * | text, | ||
const char * | language, | ||
int | voice_type, | ||
int | speed, | ||
int * | utt_id | ||
) |
Adds a text to the queue.
[in] | tts | The TTS handle |
[in] | text | An input text based utf8 |
[in] | language | The language selected from the tts_foreach_supported_voices() (e.g. 'NULL'(Automatic), 'en_US') |
[in] | voice_type | The voice type selected from the tts_foreach_supported_voices() (e.g. TTS_VOICE_TYPE_AUTO, TTS_VOICE_TYPE_FEMALE) |
[in] | speed | A speaking speed (e.g. TTS_SPEED_AUTO or the value from tts_get_speed_range()) |
[out] | utt_id | The utterance ID passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_INVALID_VOICE | Invalid voice about language, voice type |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_create | ( | tts_h * | tts | ) |
Creates a handle for TTS.
[out] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_OUT_OF_MEMORY | Out of memory |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_ENGINE_NOT_FOUND | Engine not found |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_destroy | ( | tts_h | tts | ) |
Destroys the handle and disconnects the daemon.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_foreach_supported_voices | ( | tts_h | tts, |
tts_supported_voice_cb | callback, | ||
void * | user_data | ||
) |
Retrieves all supported voices of the current engine using callback function.
[in] | tts | The TTS handle |
[in] | callback | The callback function to invoke |
[in] | user_data | The user data to be passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_ENGINE_NOT_FOUND | Engine not found |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_get_default_voice | ( | tts_h | tts, |
char ** | language, | ||
int * | voice_type | ||
) |
Gets the default voice set by the user.
[in] | tts | The TTS handle |
[out] | language | Language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English) |
[out] | voice_type | The voice type |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_ENGINE_NOT_FOUND | Engine not found |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_get_max_text_size | ( | tts_h | tts, |
unsigned int * | size | ||
) |
Gets the maximum byte size for text.
[in] | tts | The TTS handle |
[out] | size | The maximum byte size for text |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_get_mode | ( | tts_h | tts, |
tts_mode_e * | mode | ||
) |
Gets the TTS mode.
[in] | tts | The TTS handle |
[out] | mode | The mode |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_get_speed_range | ( | tts_h | tts, |
int * | min, | ||
int * | normal, | ||
int * | max | ||
) |
Gets the speed range.
[in] | tts | The TTS handle |
[out] | min | The minimun speed value |
[out] | normal | The normal speed value |
[out] | max | The maximum speed value |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_get_state | ( | tts_h | tts, |
tts_state_e * | state | ||
) |
Gets the current state of TTS.
[in] | tts | The TTS handle |
[out] | state | The current state of TTS |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
Pauses the currently playing utterance.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
Starts synthesizing voice from the text and plays the synthesized audio data.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_OUT_OF_NETWORK | Out of network |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_prepare | ( | tts_h | tts | ) |
Connects the daemon asynchronously.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_set_default_voice_changed_cb | ( | tts_h | tts, |
tts_default_voice_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to detect default voice change.
[in] | tts | The TTS handle |
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_set_error_cb | ( | tts_h | tts, |
tts_error_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to detect errors.
[in] | tts | The TTS handle |
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_set_mode | ( | tts_h | tts, |
tts_mode_e | mode | ||
) |
Sets the TTS mode.
[in] | tts | The TTS handle |
[in] | mode | The mode |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_set_state_changed_cb | ( | tts_h | tts, |
tts_state_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be called when the TTS state changes.
[in] | tts | The TTS handle |
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_set_utterance_completed_cb | ( | tts_h | tts, |
tts_utterance_completed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to detect utterance completion.
[in] | tts | The TTS handle |
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_set_utterance_started_cb | ( | tts_h | tts, |
tts_utterance_started_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to detect utterance start.
[in] | tts | The TTS handle |
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
Stops playing the utterance and clears the queue.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_OPERATION_FAILED | Operation failure |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_unprepare | ( | tts_h | tts | ) |
Disconnects the daemon.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_unset_default_voice_changed_cb | ( | tts_h | tts | ) |
Unregisters the callback function.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_unset_error_cb | ( | tts_h | tts | ) |
Unregisters the callback function.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_unset_state_changed_cb | ( | tts_h | tts | ) |
Unregisters the callback function.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_unset_utterance_completed_cb | ( | tts_h | tts | ) |
Unregisters the callback function.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |
int tts_unset_utterance_started_cb | ( | tts_h | tts | ) |
Unregisters the callback function.
[in] | tts | The TTS handle |
TTS_ERROR_NONE | Successful |
TTS_ERROR_INVALID_PARAMETER | Invalid parameter |
TTS_ERROR_INVALID_STATE | Invalid state |
TTS_ERROR_NOT_SUPPORTED | TTS NOT supported |