STT Engine

---

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.
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.
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 Documentation

#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_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_NONE	Successful.
STTE_ERROR_INVALID_STATE	Invalid 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]	appid	The Application ID
[out]	is_agreed	A 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_NONE	Successful
STTE_ERROR_INVALID_STATE	Not initialized
STTE_ERROR_NOT_SUPPORTED_FEATURE	Not 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_NONE	Successful
STTE_ERROR_INVALID_STATE	Not 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_info	The time information
[in]	callback	The callback function
[in]	user_data	The 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_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_INVALID_STATE	Not 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]	callback	The callback function
[in]	user_data	The 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_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_INVALID_STATE	Not 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_uuid	UUID of engine
[out]	engine_name	Name of engine
[out]	engine_setting	The engine setting application(ui app)'s app ID
[out]	use_network	A 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_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_OPERATION_FAILED	Operation 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]	types	The format used by the recorder
[out]	rate	The sample rate used by the recorder
[out]	channels	The number of channels used by the recorder

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_STATE	Not 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_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_INVALID_STATE	Already initialized
STTE_ERROR_OPERATION_FAILED	Operation 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]	language	The 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_valid	A 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_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid 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]	key	The key field of private data
[out]	data	The data field of private data

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_OPERATION_FAILED	Operation 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]	key	The key field of private data
[in]	data	The data field of private data

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_OPERATION_FAILED	Operation 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]	index	The result index
[in]	event	The token event
[in]	text	The result text
[in]	start_time	The time started speaking the result text
[in]	end_time	The time finished speaking the result text
[in]	user_data	The 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]	data	The recording data
[in]	length	The length of recording data

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_INVALID_STATE	Invalid state
STTE_ERROR_OPERATION_FAILED	Operation 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_set

A 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_NONE	Successful
STTE_ERROR_INVALID_STATE	Not initialized
STTE_ERROR_NOT_SUPPORTED_FEATURE	Not 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]	language	The 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]	type	The recognition type. (e.g. STTE_RECOGNITION_TYPE_FREE)
[in]	appid	The Application ID
[in]	credential	The credential granted to the application
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_INVALID_STATE	Invalid state
STTE_ERROR_INVALID_LANGUAGE	Invalid language
STTE_ERROR_OPERATION_FAILED	Operation failure
STTE_ERROR_NETWORK_DOWN	Out 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_NONE	Successful
STTE_ERROR_INVALID_STATE	Invalid state
STTE_ERROR_OPERATION_FAILED	Operation failure
STTE_ERROR_NETWORK_DOWN	Out 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]	type	The type for recognition (e.g. STTE_RECOGNITION_TYPE_FREE)
[out]	is_supported	A 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_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid 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]	language	The 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_data	The 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]	argc	The argument count(original)
[in]	argv	The argument(original)
[in]	callback	The structure of engine request callback function

Returns:

This function returns zero on success, or negative with error code on failure

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_PERMISSION_DENIED	Permission denied
STTE_ERROR_NOT_SUPPORTED	Not supported
STTE_ERROR_OPERATION_FAILED	Operation 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]	error	The error reason
[in]	msg	The error message

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_PERMISSION_DENIED	Permission denied
STTE_ERROR_NOT_SUPPORTED	Not supported
STTE_ERROR_OPERATION_FAILED	Operation 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]	event	The result event
[in]	type	The recognition type (e.g. STTE_RECOGNITION_TYPE_FREE, STTE_RECOGNITION_TYPE_FREE_PARTIAL)
[in]	result	Result texts
[in]	result_count	Result text count
[in]	msg	Engine message (e.g. STTE_RESULT_MESSAGE_NONE, STTE_RESULT_MESSAGE_ERROR_TOO_SHORT)
[in]	time_info	The time information
[in]	user_data	The user data passed from stte_start_cb()

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_PERMISSION_DENIED	Permission denied
STTE_ERROR_NOT_SUPPORTED	Not supported
STTE_ERROR_OPERATION_FAILED	Operation 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]	status	The status of speech (e.g. STTE_SPEECH_STATUS_START_POINT_DETECTED or STTE_SPEECH_STATUS_END_POINT_DETECTED)
[in]	user_data	The user data passed from the start function.

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_PERMISSION_DENIED	Permission denied
STTE_ERROR_NOT_SUPPORTED	Not supported
STTE_ERROR_OPERATION_FAILED	Operation 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_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_func

stte_private_data_requested event callback function

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_PERMISSION_DENIED	Permission denied
STTE_ERROR_NOT_SUPPORTED	Not supported
STTE_ERROR_OPERATION_FAILED	Operation 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_func

stte_private_data_set event callback function

Returns:

0 on success, otherwise a negative error value

Return values:

STTE_ERROR_NONE	Successful
STTE_ERROR_INVALID_PARAMETER	Invalid parameter
STTE_ERROR_PERMISSION_DENIED	Permission denied
STTE_ERROR_NOT_SUPPORTED	Not supported
STTE_ERROR_OPERATION_FAILED	Operation failure

Precondition:

The stte_main() function should be invoked before this function is called.

See also:

stte_private_data_set_cb()