Tizen Native API  5.5
Functions | Typedefs | Defines
STT Engine
UIX

The STT Engine APIs provide functions to operate Speech-To-Text Engine.

Required Header

#include <stte.h>

Overview

Speech-To-Text Engine (below STTE) is an engine for recording speech and resulting in texts of speech recognition. Using the STT Engine APIs, STTE developers can provide STTE service users, who want to apply STTE, with functions necessary to operate the engine. According to the indispensability of STTE services, there are two ways to provide them to the users.
A. Required STTE services
These services are indispensable to operate STTE. Therefore, the STTE developers MUST implement callback functions corresponding to the required STTE services. The following is a list of the callback functions.

FUNCTION DESCRIPTION
stte_get_info_cb() Called when the engine service user requests the basic information of STT engine.
stte_initialize_cb() Called when the engine service user initializes STT engine.
stte_deinitialize_cb() Called when the engine service user deinitializes STT engine.
stte_is_valid_language_cb() Called when the engine service user checks whether the corresponding language is valid or not.
stte_foreach_supported_langs_cb() Called when the engine service user gets the whole supported language list.
stte_support_silence_detection_cb() Called when the engine service user checks whether STT engine supports silence detection.
stte_set_silence_detection_cb() Called when the engine service user sets the silence detection.
stte_support_recognition_type_cb() Called when the engine service user checks whether STT engine supports the corresponding recognition type.
stte_get_recording_format_cb() Called when the engine service user gets the proper recording format of STT engine.
stte_set_recording_data_cb() Called when the engine service user sets and sends the recording data for speech recognition.
stte_foreach_result_time_cb() Called when the engine service user gets the result time information(stamp).
stte_start_cb() Called when the engine service user starts to recognize the recording data.
stte_stop_cb() Called when the engine service user stops to recognize the recording data.
stte_cancel_cb() Called when the engine service user cancels to recognize the recording data.
stte_check_app_agreed_cb() Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.
stte_need_app_credential_cb() Called when the engine service user checks whether STT engine needs the application's credential.

The STTE developers can register the above callback functions at a time with using a structure 'stte_request_callback_s' and an API 'stte_main()'. To operate STTE, the following steps should be used:
1. Create a structure 'stte_request_callback_s'.
2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction. If the callback function returns an unstated value, STT framework will handle it as STTE_ERROR_OPERATION_FAILED.)
3. Register callback functions using 'stte_main()'. (The registered callback functions will be called when the STTE service users request the STTE services.)
4. Use 'service_app_main()' for working STTE.
B. Optional STTE services
Unlike the required STTE services, these services are optional to operate STTE. The followings are optional STTE services.

  • receive/provide the private data
    If the STTE developers want to provide the above services, use the following APIs and implement the corresponding callback functions:
    FUNCTION DESCRIPTION CORRESPONDING CALLBACK
    stte_set_private_data_set_cb() Sets a callback function for receiving the private data from the engine service user. stte_private_data_set_cb()
    stte_set_private_data_requested_cb() Sets a callback function for providing the private data to the engine service user. stte_private_data_requested_cb()

    Using the above APIs, the STTE developers can register the optional callback functions respectively. (For normal operation, put those APIs before 'service_app_main()' starts.) Unlike callback functions, the following APIs are functions for getting and sending data. The STTE developers can use these APIs when they implement STTE services:
    FUNCTION DESCRIPTION
    stte_send_result() Sends the recognition result to the engine service user.
    stte_send_error() Sends the error to the engine service user.
    stte_send_speech_status() Sends the speech status to the engine service user when STT engine notifies the change of the speech status.

Related Features

This API is related with the following features:

  • http://tizen.org/feature/speech.recognition
  • http://tizen.org/feature/microphone
    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.

Functions

int stte_main (int argc, char **argv, stte_request_callback_s *callback)
 Main function for Speech-To-Text (STT) engine.
int stte_send_result (stte_result_event_e event, const char *type, const char **result, int result_count, const char *msg, void *time_info, void *user_data)
 Sends the recognition result to the engine service user.
int stte_send_error (stte_error_e error, const char *msg)
 Sends the error to the engine service user.
int stte_send_speech_status (stte_speech_status_e status, void *user_data)
 Sends the speech status to the engine service user when STT engine notifies the change of the speech status.
int stte_set_private_data_set_cb (stte_private_data_set_cb callback_func)
 Sets a callback function for setting the private data.
int stte_set_private_data_requested_cb (stte_private_data_requested_cb callback_func)
 Sets a callback function for requesting the private data.
int stte_set_audio_type_set_cb (stte_audio_type_cb callback_func, void *user_data)
 Sets a callback function for setting the audio type.
int stte_unset_audio_type_set_cb (void)
 Unsets a callback function for setting the audio type.

Typedefs

typedef bool(* stte_result_time_cb )(int index, stte_result_time_event_e event, const char *text, long start_time, long end_time, void *user_data)
 Called when STT engine provides the time stamp of result to the engine service user.
typedef bool(* stte_supported_language_cb )(const char *language, void *user_data)
 Called when STT engine informs the engine service user about whole supported language list.
typedef int(* stte_initialize_cb )(void)
 Called when the engine service user initializes STT engine.
typedef int(* stte_deinitialize_cb )(void)
 Called when the engine service user deinitializes STT engine.
typedef int(* stte_foreach_supported_langs_cb )(stte_supported_language_cb callback, void *user_data)
 Called when the engine service user gets the whole supported language list.
typedef int(* stte_is_valid_language_cb )(const char *language, bool *is_valid)
 Called when the engine service user checks whether the corresponding language is valid or not in STT engine.
typedef bool(* stte_support_silence_detection_cb )(void)
 Called when the engine service user checks whether STT engine supports silence detection.
typedef int(* stte_support_recognition_type_cb )(const char *type, bool *is_supported)
 Called when the engine service user checks whether STT engine supports the corresponding recognition type.
typedef int(* stte_get_recording_format_cb )(stte_audio_type_e *types, int *rate, int *channels)
 Called when the engine service user gets the proper recording format of STT engine.
typedef int(* stte_set_silence_detection_cb )(bool is_set)
 Called when the engine service user sets the silence detection.
typedef int(* stte_check_app_agreed_cb )(const char *appid, bool *is_agreed)
 Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.
typedef bool(* stte_need_app_credential_cb )(void)
 Called when the engine service user checks whether STT engine needs the application's credential.
typedef int(* stte_foreach_result_time_cb )(void *time_info, stte_result_time_cb callback, void *user_data)
 Called when the engine service user gets the result time information(stamp).
typedef int(* stte_start_cb )(const char *language, const char *type, const char *appid, const char *credential, void *user_data)
 Called when the engine service user starts to recognize the recording data.
typedef int(* stte_set_recording_data_cb )(const void *data, unsigned int length)
 Called when the engine service user sets and sends the recording data for speech recognition.
typedef int(* stte_stop_cb )(void)
 Called when the engine service user stops to recognize the recording data.
typedef int(* stte_cancel_cb )(void)
 Called when the engine service user cancels to recognize the recording data.
typedef int(* stte_get_info_cb )(char **engine_uuid, char **engine_name, char **engine_setting, bool *use_network)
 Called when the engine service user requests the basic information of STT engine.
typedef int(* stte_private_data_set_cb )(const char *key, const char *data)
 Called when STT engine receives the private data from the engine service user.
typedef int(* stte_private_data_requested_cb )(const char *key, char **data)
 Called when STT engine provides the engine service user with the private data.
typedef int(* stte_audio_type_cb )(const char *audio_type, void *user_data)
 Called when the engine service user sets audio recording type.

Defines

#define STTE_RECOGNITION_TYPE_FREE   "stt.recognition.type.FREE"
 Definition for free form dictation and default type.
#define STTE_RECOGNITION_TYPE_FREE_PARTIAL   "stt.recognition.type.FREE.PARTIAL"
 Definition for free form dictation continuously.
#define STTE_RESULT_MESSAGE_NONE   "stt.result.message.none"
 Definition for None message.
#define STTE_RESULT_MESSAGE_ERROR_TOO_SOON   "stt.result.message.error.too.soon"
 Definition for failed recognition because the speech started too soon.
#define STTE_RESULT_MESSAGE_ERROR_TOO_SHORT   "stt.result.message.error.too.short"
 Definition for failed recognition because the speech started too short.
#define STTE_RESULT_MESSAGE_ERROR_TOO_LONG   "stt.result.message.error.too.long"
 Definition for failed recognition because the speech started too long.
#define STTE_RESULT_MESSAGE_ERROR_TOO_QUIET   "stt.result.message.error.too.quiet"
 Definition for failed recognition because the speech started too quiet to listen.
#define STTE_RESULT_MESSAGE_ERROR_TOO_LOUD   "stt.result.message.error.too.loud"
 Definition for failed recognition because the speech started too loud to listen.
#define STTE_RESULT_MESSAGE_ERROR_TOO_FAST   "stt.result.message.error.too.fast"
 Definition for failed recognition because the speech started too fast to listen.
#define STTE_AUDIO_ID_BLUETOOTH   "STT_AUDIO_ID_BLUETOOTH"
 Definition of audio ID that means audio source from bluetooth.
#define STTE_AUDIO_ID_WIFI   "STT_AUDIO_ID_WIFI"
 Definition of audio ID that means audio source from wifi.

Define Documentation

#define STTE_AUDIO_ID_BLUETOOTH   "STT_AUDIO_ID_BLUETOOTH"

Definition of audio ID that means audio source from bluetooth.

Since :
5.5
#define STTE_AUDIO_ID_WIFI   "STT_AUDIO_ID_WIFI"

Definition of audio ID that means audio source from wifi.

Since :
5.5
#define STTE_RECOGNITION_TYPE_FREE   "stt.recognition.type.FREE"

Definition for free form dictation and default type.

Since :
3.0
#define STTE_RECOGNITION_TYPE_FREE_PARTIAL   "stt.recognition.type.FREE.PARTIAL"

Definition for free form dictation continuously.

Since :
3.0
#define STTE_RESULT_MESSAGE_ERROR_TOO_FAST   "stt.result.message.error.too.fast"

Definition for failed recognition because the speech started too fast to listen.

Since :
3.0
#define STTE_RESULT_MESSAGE_ERROR_TOO_LONG   "stt.result.message.error.too.long"

Definition for failed recognition because the speech started too long.

Since :
3.0
#define STTE_RESULT_MESSAGE_ERROR_TOO_LOUD   "stt.result.message.error.too.loud"

Definition for failed recognition because the speech started too loud to listen.

Since :
3.0
#define STTE_RESULT_MESSAGE_ERROR_TOO_QUIET   "stt.result.message.error.too.quiet"

Definition for failed recognition because the speech started too quiet to listen.

Since :
3.0
#define STTE_RESULT_MESSAGE_ERROR_TOO_SHORT   "stt.result.message.error.too.short"

Definition for failed recognition because the speech started too short.

Since :
3.0
#define STTE_RESULT_MESSAGE_ERROR_TOO_SOON   "stt.result.message.error.too.soon"

Definition for failed recognition because the speech started too soon.

Since :
3.0
#define STTE_RESULT_MESSAGE_NONE   "stt.result.message.none"

Definition for None message.

Since :
3.0

Typedef Documentation

typedef int(* stte_audio_type_cb)(const char *audio_type, void *user_data)

Called when the engine service user sets audio recording type.

Since :
5.5
Remarks:
The audio_type can be used only in the callback. To use outside, make a copy.
Parameters:
[in]audio_typeCurrent audio type (e.g. STTE_AUDIO_ID_BLUETOOTH or STTE_AUDIO_ID_WIFI)
[in]user_datauser_data The user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_OPERATION_FAILEDOperation failure
typedef int(* stte_cancel_cb)(void)

Called when the engine service user cancels to recognize the recording data.

This callback function is called by the engine service user to cancel to recognize the recording data. Also, when starting the recorder is failed, this function is called.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful.
STTE_ERROR_INVALID_STATEInvalid state.
Precondition:
STT engine is in recognition processing or recording.
See also:
stte_start_cb()
stte_stop_cb()
typedef int(* stte_check_app_agreed_cb)(const char *appid, bool *is_agreed)

Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.

This callback function is called when the engine service user requests for STT engine to check the application's agreement about using the engine. According to the need, the engine developer can provide some user interfaces to check the agreement.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). If the STT engine developer wants not to check the agreement, the developer has need to return proper values as is_agreed in accordance with the intention. true if the developer regards that every application agreed the usage of the engine, false if the developer regards that every application disagreed. NOTE that, however, there may be any legal issue unless the developer checks the agreement. Therefore, we suggest that the engine developers should provide a function to check the agreement.
Parameters:
[in]appidThe Application ID
[out]is_agreedA variable for checking whether the application agreed to use STT engine or not. true to agree, false to disagree
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_STATENot initialized
STTE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
typedef int(* stte_deinitialize_cb)(void)

Called when the engine service user deinitializes STT engine.

This callback function is called by the engine service user to request for STT engine to be deinitialized.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). NOTE that the engine may be terminated automatically. When this callback function is invoked, the release of resources is necessary.
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_STATENot initialized
See also:
stte_initialize_cb()
typedef int(* stte_foreach_result_time_cb)(void *time_info, stte_result_time_cb callback, void *user_data)

Called when the engine service user gets the result time information(stamp).

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). In this function, the engine service user's callback function 'stte_result_time_cb()' is invoked repeatedly for sending the time information to the engine service user, and user_data must be transferred to 'stte_result_time_cb()'. If 'stte_result_time_cb()' returns false, it should be stopped to call 'stte_result_time_cb()'. time_info is transferred from stte_send_result(). The type of time_info is up to the STT engine developer.
Parameters:
[in]time_infoThe time information
[in]callbackThe callback function
[in]user_dataThe user data which must be passed to the callback function 'stte_result_time_cb()'
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_INVALID_STATENot initialized
Precondition:
stte_send_result() will invoke this function.
Postcondition:
This function invokes stte_result_time_cb() repeatedly for getting result time information.
See also:
stte_result_time_cb()
typedef int(* stte_foreach_supported_langs_cb)(stte_supported_language_cb callback, void *user_data)

Called when the engine service user gets the whole supported language list.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). In this function, the engine service user's callback function 'stte_supported_language_cb()' is invoked repeatedly for getting all supported languages, and user_data must be transferred to 'stte_supported_language_cb()'. If 'stte_supported_language_cb()' returns false, it should be stopped to call 'stte_supported_language_cb()'.
Parameters:
[in]callbackThe callback function
[in]user_dataThe user data which must be passed to the callback function 'stte_supported_language_cb()'
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_INVALID_STATENot initialized
Postcondition:
This callback function invokes stte_supported_language_cb() repeatedly for getting supported languages.
See also:
stte_supported_language_cb()
typedef int(* stte_get_info_cb)(char **engine_uuid, char **engine_name, char **engine_setting, bool *use_network)

Called when the engine service user requests the basic information of STT engine.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). The allocated engine_uuid, engine_name, and engine_setting will be released internally. In order to upload the engine at Tizen Appstore, both a service app and a ui app are necessary. Therefore, engine_setting must be transferred to the engine service user.
Parameters:
[out]engine_uuidUUID of engine
[out]engine_nameName of engine
[out]engine_settingThe engine setting application(ui app)'s app ID
[out]use_networkA variable for checking whether the network is used or not
Returns:
0 on success, otherwise a negative error code on failure
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_OPERATION_FAILEDOperation failure
typedef int(* stte_get_recording_format_cb)(stte_audio_type_e *types, int *rate, int *channels)

Called when the engine service user gets the proper recording format of STT engine.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). The recording format is used for creating the recorder.
Parameters:
[out]typesThe format used by the recorder
[out]rateThe sample rate used by the recorder
[out]channelsThe number of channels used by the recorder
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_STATENot initialized
typedef int(* stte_initialize_cb)(void)

Called when the engine service user initializes STT engine.

This callback function is called by the engine service user to request for STT engine to be started.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_INVALID_STATEAlready initialized
STTE_ERROR_OPERATION_FAILEDOperation failure
See also:
stte_deinitialize_cb()
typedef int(* stte_is_valid_language_cb)(const char *language, bool *is_valid)

Called when the engine service user checks whether the corresponding language is valid or not in STT engine.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Parameters:
[in]languageThe language is 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]is_validA variable for checking whether the corresponding language is valid or not. true to be valid, false to be invalid
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
See also:
stte_foreach_supported_languages_cb()
typedef bool(* stte_need_app_credential_cb)(void)

Called when the engine service user checks whether STT engine needs the application's credential.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Returns:
true if STT engine needs the application's credential, otherwise false
typedef int(* stte_private_data_requested_cb)(const char *key, char **data)

Called when STT engine provides the engine service user with the private data.

This callback function is called when the engine service user gets the private data from STT engine.

Since :
3.0
Remarks:
This callback function is optional and is registered using stte_set_private_data_requested_cb().
Parameters:
[out]keyThe key field of private data
[out]dataThe data field of private data
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_OPERATION_FAILEDOperation failure
See also:
stte_private_data_set_cb()
stte_set_private_data_requested_cb()
typedef int(* stte_private_data_set_cb)(const char *key, const char *data)

Called when STT engine receives the private data from the engine service user.

This callback function is called when the engine service user sends the private data to STT engine.

Since :
3.0
Remarks:
This callback function is optional and is registered using stte_set_private_data_set_cb().
Parameters:
[in]keyThe key field of private data
[in]dataThe data field of private data
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_OPERATION_FAILEDOperation failure
See also:
stte_private_data_requested_cb()
stte_set_private_data_set_cb()
typedef bool(* stte_result_time_cb)(int index, stte_result_time_event_e event, const char *text, long start_time, long end_time, void *user_data)

Called when STT engine provides the time stamp of result to the engine service user.

This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.

Since :
3.0
Remarks:
This callback function is called in stte_foreach_result_time_cb() for adding time information. user_data must be transferred from stte_foreach_result_time_cb().
Parameters:
[in]indexThe result index
[in]eventThe token event
[in]textThe result text
[in]start_timeThe time started speaking the result text
[in]end_timeThe time finished speaking the result text
[in]user_dataThe user data passed from stte_foreach_result_time_cb()
Returns:
true to continue with the next iteration of the loop false to break out of the loop
Precondition:
stte_send_result() should be called.
See also:
stte_send_result()
stte_foreach_result_time_cb()
typedef int(* stte_set_recording_data_cb)(const void *data, unsigned int length)

Called when the engine service user sets and sends the recording data for speech recognition.

This callback function is called by the engine service user to send the recording data to STT engine. The engine receives the recording data and uses for speech recognition.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). Also, this function should be returned immediately after recording data copy.
Parameters:
[in]dataThe recording data
[in]lengthThe length of recording data
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_INVALID_STATEInvalid state
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
stte_start_cb() should succeed.
Postcondition:
If the engine supports partial result, stte_send_result() should be invoked.
See also:
stte_start_cb()
stte_cancel_cb()
stte_stop_cb()
typedef int(* stte_set_silence_detection_cb)(bool is_set)

Called when the engine service user sets the silence detection.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). If the engine service user sets this option as 'TRUE', STT engine will detect the silence (EPD) and send the callback event about it.
Parameters:
[in]is_setA variable for setting the silence detection. true to detect the silence, false not to detect the silence
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_STATENot initialized
STTE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
typedef int(* stte_start_cb)(const char *language, const char *type, const char *appid, const char *credential, void *user_data)

Called when the engine service user starts to recognize the recording data.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main(). In this callback function, STT engine must transfer the recognition result and user_data to the engine service user using stte_send_result(). Also, if STT engine needs the application's credential, it sets the credential granted to the application.
Parameters:
[in]languageThe language is 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]typeThe recognition type. (e.g. STTE_RECOGNITION_TYPE_FREE)
[in]appidThe Application ID
[in]credentialThe credential granted to the application
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_INVALID_STATEInvalid state
STTE_ERROR_INVALID_LANGUAGEInvalid language
STTE_ERROR_OPERATION_FAILEDOperation failure
STTE_ERROR_NETWORK_DOWNOut of network
Precondition:
The engine is not in recognition processing.
See also:
stte_set_recording_data_cb()
stte_stop_cb()
stte_cancel_cb()
stte_need_app_credential_cb()
typedef int(* stte_stop_cb)(void)

Called when the engine service user stops to recognize the recording data.

This callback function is called by the engine service user to stop recording and to get the recognition result.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_STATEInvalid state
STTE_ERROR_OPERATION_FAILEDOperation failure
STTE_ERROR_NETWORK_DOWNOut of network
Precondition:
stte_start_cb() should succeed.
Postcondition:
After processing of the engine, stte_send_result() must be called.
See also:
stte_start_cb()
stte_set_recording_data_cb()
stte_cancel_cb()
stte_send_result()
typedef int(* stte_support_recognition_type_cb)(const char *type, bool *is_supported)

Called when the engine service user checks whether STT engine supports the corresponding recognition type.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Parameters:
[in]typeThe type for recognition (e.g. STTE_RECOGNITION_TYPE_FREE)
[out]is_supportedA variable for checking whether STT engine supports the corresponding recognition type. true to support recognition type, false not to support recognition type
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
typedef bool(* stte_support_silence_detection_cb)(void)

Called when the engine service user checks whether STT engine supports silence detection.

Since :
3.0
Remarks:
This callback function is mandatory and must be registered using stte_main().
Returns:
true to support silence detection, false not to support silence detection
See also:
stte_set_silence_detection_cb()
typedef bool(* stte_supported_language_cb)(const char *language, void *user_data)

Called when STT engine informs the engine service user about whole supported language list.

This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.

Since :
3.0
Remarks:
This callback function is called in stte_foreach_supported_langs_cb() to inform the whole supported language list. user_data must be transferred from stte_foreach_supported_langs_cb().
Parameters:
[in]languageThe language is 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]user_dataThe user data passed from stte_foreach_supported_langs_cb()
Returns:
true to continue with the next iteration of the loop false to break out of the loop
Precondition:
stte_foreach_supported_langs_cb() will invoke this callback function.
See also:
stte_foreach_supported_langs_cb()

Enumeration Type Documentation

enum stte_audio_type_e

Enumeration for audio type.

Since :
3.0
Enumerator:
STTE_AUDIO_TYPE_PCM_S16_LE 

Signed 16bit audio type, Little endian

STTE_AUDIO_TYPE_PCM_U8 

Unsigned 8bit audio type

enum stte_error_e

Enumeration for error codes.

Since :
3.0
Enumerator:
STTE_ERROR_NONE 

Successful

STTE_ERROR_OUT_OF_MEMORY 

Out of Memory

STTE_ERROR_IO_ERROR 

I/O error

STTE_ERROR_INVALID_PARAMETER 

Invalid parameter

STTE_ERROR_NETWORK_DOWN 

Network down(Out of network)

STTE_ERROR_INVALID_STATE 

Invalid state

STTE_ERROR_INVALID_LANGUAGE 

Invalid language

STTE_ERROR_OPERATION_FAILED 

Operation failed

STTE_ERROR_NOT_SUPPORTED_FEATURE 

Not supported feature

STTE_ERROR_NOT_SUPPORTED 

Not supported

STTE_ERROR_PERMISSION_DENIED 

Permission denied

STTE_ERROR_RECORDING_TIMED_OUT 

Recording timed out

enum stte_result_event_e

Enumeration for callback event.

Since :
3.0
Enumerator:
STTE_RESULT_EVENT_FINAL_RESULT 

Event when either the full matched or the final result is delivered

STTE_RESULT_EVENT_PARTIAL_RESULT 

Event when the partial matched result is delivered

STTE_RESULT_EVENT_ERROR 

Event when the recognition has failed

enum stte_result_time_event_e

Enumeration for result time callback event.

Since :
3.0
Enumerator:
STTE_RESULT_TIME_EVENT_BEGINNING 

Event when the token is beginning type

STTE_RESULT_TIME_EVENT_MIDDLE 

Event when the token is middle type

STTE_RESULT_TIME_EVENT_END 

Event when the token is end type

enum stte_speech_status_e

Enumeration for speech status.

Since :
3.0
Enumerator:
STTE_SPEECH_STATUS_BEGINNING_POINT_DETECTED 

Beginning point of speech is detected

STTE_SPEECH_STATUS_END_POINT_DETECTED 

End point of speech is detected

Function Documentation

int stte_main ( int  argc,
char **  argv,
stte_request_callback_s *  callback 
)

Main function for Speech-To-Text (STT) engine.

This function is the main function for operating STT engine.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The service_app_main() should be used for working the engine after this function.
Parameters:
[in]argcThe argument count(original)
[in]argvThe argument(original)
[in]callbackThe structure of engine request callback function
Returns:
This function returns zero on success, or negative with error code on failure
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_PERMISSION_DENIEDPermission denied
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
See also:
stte_request_callback_s 
#include <stte.h>

// Required callback functions - MUST BE IMPLEMENTED
static int sttengine_get_info_cb(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
static int sttengine_initialize_cb(void);
static int sttengine_deinitialize_cb(void);
static int sttengine_is_valid_language_cb(const char* language, bool* is_valid);
static int sttengine_foreach_supported_langs_cb(stte_supported_language_cb callback, void* user_data);
static bool sttengine_support_silence_detection_cb(void);
static int sttengine_set_silence_detection_cb(bool is_set);
static int sttengine_support_recognition_type_cb(const char* type, bool* is_supported);
static int sttengine_get_recording_format_cb(stte_audio_type_e* types, int* rate, int* channels);
static int sttengine_set_recording_data_cb(const void* data, unsigned int length);
static int sttengine_foreach_result_time_cb(void* time_info, stte_result_time_cb callback, void* user_data);
static int sttengine_start_cb(const char* language, const char* type, const char* appid, const char* credential, void *user_data);
static int sttengine_stop_cb(void);
static int sttengine_cancel_cb(void);
static int sttengine_check_app_agreed_cb(const char* appid, bool* is_agreed);
static bool sttengine_need_app_credential_cb(void);

// Optional callback function
static int sttengine_private_data_set_cb(const char* key, const char* data);

int main(int argc, char* argv[])
{
    // 1. Create a structure 'stte_request_callback_s'
    stte_request_callback_s engine_callback = { 0, };

    engine_callback.size = sizeof(stte_request_callback_s);
    engine_callback.version = 1;
    engine_callback.get_info = sttengine_get_info_cb;

    engine_callback.initialize = sttengine_initialize_cb;
    engine_callback.deinitialize = sttengine_deinitialize_cb;

    engine_callback.foreach_langs = sttengine_foreach_supported_langs_cb;
    engine_callback.is_valid_lang = sttengine_is_valid_language_cb;
    engine_callback.support_silence = sttengine_support_silence_detection_cb;
    engine_callback.support_recognition_type = sttengine_support_recognition_type_cb;

    engine_callback.get_audio_format = sttengine_get_recording_format_cb;
    engine_callback.foreach_result_time = sttengine_foreach_result_time_cb;

    engine_callback.set_silence_detection = sttengine_set_silence_detection_cb;

    engine_callback.start = sttengine_start_cb;
    engine_callback.set_recording = sttengine_set_recording_data_cb;
    engine_callback.stop = sttengine_stop_cb;
    engine_callback.cancel = sttengine_cancel_cb;

    engine_callback.check_app_agreed = sttengine_check_app_agreed_cb;
    engine_callback.need_app_credential = sttengine_need_app_credential_cb;

    // 2. Run 'stte_main()'
    if (0 != stte_main(argc, argv, &engine_callback)) {
        return -1;
    }

    // Optional
    stte_set_private_data_set_cb(sttengine_private_data_set_cb);

    // 3. Set event callbacks for service app and Run 'service_app_main()'
    char ad[50] = { 0, };

    service_app_lifecycle_callback_s event_callback;
    app_event_handler_h handlers[5] = { NULL, };

    event_callback.create = service_app_create;
    event_callback.terminate = service_app_terminate;
    event_callback.app_control = service_app_control;

    service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
    service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
    service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
    service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);

    return service_app_main(argc, argv, &event_callback, ad);
}
int stte_send_error ( stte_error_e  error,
const char *  msg 
)

Sends the error to the engine service user.

The following error codes can be delivered. STTE_ERROR_NONE, STTE_ERROR_OUT_OF_MEMORY, STTE_ERROR_IO_ERROR, STTE_ERROR_INVALID_PARAMETER, STTE_ERROR_NETWORK_DOWN, STTE_ERROR_INVALID_STATE, STTE_ERROR_INVALID_LANGUAGE, STTE_ERROR_OPERATION_FAILED, STTE_ERROR_NOT_SUPPORTED_FEATURE, STTE_ERROR_NOT_SUPPORTED, STTE_ERROR_PERMISSION_DENIED, STTE_ERROR_RECORDING_TIMED_OUT.

Since :
3.0
Parameters:
[in]errorThe error reason
[in]msgThe error message
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_PERMISSION_DENIEDPermission denied
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called.
int stte_send_result ( stte_result_event_e  event,
const char *  type,
const char **  result,
int  result_count,
const char *  msg,
void *  time_info,
void *  user_data 
)

Sends the recognition result to the engine service user.

Since :
3.0
Remarks:
This API is used in stte_set_recording_data_cb() and stte_stop_cb(), when STT engine sends the recognition result to the engine service user. This function is called in the following situations; 1) after stte_stop_cb() is called, 2) the end point of speech is detected from recording, or 3) partial result is occurred. The recognition result and user_data must be transferred to the engine service user through this function. Also, time_info must be transferred to stte_foreach_result_time_cb(). The type of time_info is up to the STT engine developer.
Parameters:
[in]eventThe result event
[in]typeThe recognition type (e.g. STTE_RECOGNITION_TYPE_FREE, STTE_RECOGNITION_TYPE_FREE_PARTIAL)
[in]resultResult texts
[in]result_countResult text count
[in]msgEngine message (e.g. STTE_RESULT_MESSAGE_NONE, STTE_RESULT_MESSAGE_ERROR_TOO_SHORT)
[in]time_infoThe time information
[in]user_dataThe user data passed from stte_start_cb()
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_PERMISSION_DENIEDPermission denied
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called. stte_stop_cb() will invoke this function.
Postcondition:
This function invokes stte_foreach_result_time_cb().
See also:
stte_start_cb()
stte_set_recording_data_cb()
stte_stop_cb()
stte_foreach_result_time_cb()
int stte_send_speech_status ( stte_speech_status_e  status,
void *  user_data 
)

Sends the speech status to the engine service user when STT engine notifies the change of the speech status.

Since :
3.0
Remarks:
This API is invoked when STT engine wants to notify the change of the speech status anytime. NOTE that this API can be invoked for recognizing the speech.
Parameters:
[in]statusThe status of speech (e.g. STTE_SPEECH_STATUS_START_POINT_DETECTED or STTE_SPEECH_STATUS_END_POINT_DETECTED)
[in]user_dataThe user data passed from the start function.
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_PERMISSION_DENIEDPermission denied
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called. stte_start_cb() and stte_set_recording_data_cb() will invoke this function.
See also:
stte_start_cb()
stte_set_recording_data_cb()
int stte_set_audio_type_set_cb ( stte_audio_type_cb  callback_func,
void *  user_data 
)

Sets a callback function for setting the audio type.

Since :
5.5
Remarks:
The stte_audio_type_cb() function is called when STT framework sets audio type to the STT engine.
Parameters:
[in]callback_funcstte_audio_type_set event callback function
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called.
See also:
stte_audio_type_cb()
stte_unset_audio_type_set_cb()
int stte_set_private_data_requested_cb ( stte_private_data_requested_cb  callback_func)

Sets a callback function for requesting the private data.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The stte_private_data_requested_cb() function is called when the engine service user gets the private data from STT engine.
Parameters:
[in]callback_funcstte_private_data_requested event callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_PERMISSION_DENIEDPermission denied
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called.
See also:
stte_private_data_requested_cb()
int stte_set_private_data_set_cb ( stte_private_data_set_cb  callback_func)

Sets a callback function for setting the private data.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The stte_private_data_set_cb() function is called when the engine service user sends the private data.
Parameters:
[in]callback_funcstte_private_data_set event callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_INVALID_PARAMETERInvalid parameter
STTE_ERROR_PERMISSION_DENIEDPermission denied
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called.
See also:
stte_private_data_set_cb()
int stte_unset_audio_type_set_cb ( void  )

Unsets a callback function for setting the audio type.

Since :
5.5
Returns:
0 on success, otherwise a negative error value
Return values:
STTE_ERROR_NONESuccessful
STTE_ERROR_NOT_SUPPORTEDNot supported
STTE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The stte_main() function should be invoked before this function is called.
See also:
stte_set_audio_type_set_cb()