Move functions about audio streaming to public header file

[platform/core/uifw/stt.git] / include / stt.h

diff --git a/include/stt.h b/include/stt.h
index f21c4bb..7734c1e 100755 (executable)
--- a/include/stt.h
+++ b/include/stt.h
@@ -206,6 +206,15 @@ typedef enum {
 
 
 /**
+* @brief Enumerations of audio type.
+* @since_tizen 8.0
+*/
+typedef enum {
+       STT_AUDIO_TYPE_RAW_S16 = 0,     /**< Signed 16-bit audio sample */
+       STT_AUDIO_TYPE_RAW_U8,          /**< Unsigned 8-bit audio sample */
+} stt_audio_type_e;
+
+/**
  * @brief A structure of STT handle.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
@@ -355,7 +364,7 @@ typedef void (*stt_speech_status_cb)(stt_h stt, stt_speech_status_e status, void
  * @privilege %http://tizen.org/privilege/recorder
  * @remarks If the function succeeds, @a stt handle must be released with stt_destroy().
  * @param[out] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
@@ -375,7 +384,7 @@ int stt_create(stt_h* stt);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -395,7 +404,7 @@ int stt_destroy(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to invoke
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Success
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -418,7 +427,7 @@ int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, v
  * @remarks If the function is success, @a engine_id must be released using free().
  * @param[in] stt The STT handle
  * @param[out] engine_id Engine ID
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Success
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -441,7 +450,7 @@ int stt_get_engine(stt_h stt, char** engine_id);
  * @remarks A privilege (%http://tizen.org/privilege/appmanager.launch) is necessary since 3.0.
  * @param[in] stt The STT handle
  * @param[in] engine_id Engine ID
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Success
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -465,7 +474,7 @@ int stt_set_engine(stt_h stt, const char* engine_id);
  *          However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
  * @param[in] stt The STT handle
  * @param[in] credential The app credential
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Success
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -488,7 +497,7 @@ int stt_set_credential(stt_h stt, const char* credential);
  * @param[in] stt The STT handle
  * @param[in] key The field name of private data
  * @param[in] data The data for set
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -511,7 +520,7 @@ int stt_set_private_data(stt_h stt, const char* key, const char* data);
  * @param[in] stt The STT handle
  * @param[in] key The field name of private data
  * @param[out] data The data field of private data
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -530,7 +539,7 @@ int stt_get_private_data(stt_h stt, const char* key, char** data);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -551,7 +560,7 @@ int stt_prepare(stt_h stt);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -573,7 +582,7 @@ int stt_unprepare(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to invoke
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -599,7 +608,7 @@ int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callbac
  *          If the function succeeds, @a language must be released using free() when it is no longer required.
  * @param[in] stt The STT handle
  * @param[out] language The language
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -618,7 +627,7 @@ int stt_get_default_language(stt_h stt, char** language);
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
  * @param[out] state The current STT state
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -639,7 +648,7 @@ int stt_get_state(stt_h stt, stt_state_e* state);
  *          If the function succeeds, @a err_msg must be released using free() when it is no longer required.
  * @param[in] stt The STT handle
  * @param[out] err_msg The current error message
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -660,7 +669,7 @@ int stt_get_error_message(stt_h stt, char** err_msg);
  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
  * @param[out] support The result status @c true = supported,
  *                     @c false = not supported
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -680,7 +689,7 @@ int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
  * @param[in] type The option type
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -701,7 +710,7 @@ int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
  * @remarks Sound file type should be wav type.
  * @param[in] stt The STT handle
  * @param[in] filename The sound file path
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -720,7 +729,7 @@ int stt_set_start_sound(stt_h stt, const char* filename);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -741,7 +750,7 @@ int stt_unset_start_sound(stt_h stt);
  * @remarks Sound file type should be wav type.
  * @param[in] stt The STT handle
  * @param[in] filename The sound file path
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -760,7 +769,7 @@ int stt_set_stop_sound(stt_h stt, const char* filename);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -783,7 +792,7 @@ int stt_unset_stop_sound(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] language The language selected from stt_foreach_supported_languages()
  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -810,8 +819,9 @@ int stt_start(stt_h stt, const char* language, const char* type);
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
+ * @remarks This function can only stop recording started by stt_start().
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -826,6 +836,7 @@ int stt_start(stt_h stt, const char* language, const char* type);
  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
  *       If this function succeeds, the STT state will be #STT_STATE_PROCESSING.
  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_PROCESSING.
+ *       If you call this function after starting recording by stt_start_audio_streaming(), you will receive #STT_ERROR_OPERATION_FAILED.
  *       After processing of engine, stt_result_cb() is called.
  * @see stt_start()
  * @see stt_cancel()
@@ -842,7 +853,7 @@ int stt_stop(stt_h stt);
  * @remarks This function cancels recording and engine cancels recognition processing.
  *          After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -871,7 +882,7 @@ int stt_cancel(stt_h stt);
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
  * @param[out] volume Recording volume
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -895,7 +906,7 @@ int stt_get_recording_volume(stt_h stt, float* volume);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to invoke
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -918,7 +929,7 @@ int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* us
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -938,7 +949,7 @@ int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback,
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -959,7 +970,7 @@ int stt_unset_recognition_result_cb(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -979,7 +990,7 @@ int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* use
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1000,7 +1011,7 @@ int stt_unset_state_changed_cb(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1020,7 +1031,7 @@ int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1041,7 +1052,7 @@ int stt_unset_error_cb(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1061,7 +1072,7 @@ int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1080,7 +1091,7 @@ int stt_unset_default_language_changed_cb(stt_h stt);
  * @param[in] stt The STT handle
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1097,7 +1108,7 @@ int stt_set_engine_changed_cb(stt_h stt, stt_engine_changed_cb callback, void* u
  * @brief Unsets the callback function.
  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  * @param[in] stt The STT handle
- * @return @c 0 on success, 
+ * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STT_ERROR_NONE Successful
  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
@@ -1150,6 +1161,109 @@ int stt_set_speech_status_cb(stt_h stt, stt_speech_status_cb callback, void* use
 int stt_unset_speech_status_cb(stt_h stt);
 
 
+/**
+ * @brief Starts audio streaming and recognition asynchronously.
+ * @since_tizen 8.0
+ * @remarks This function starts audio streaming in the STT service.
+ *          This work continues until stt_stop_audio_streaming(), stt_cancel() or silence detected by engine.
+ * @param[in] stt The STT handle
+ * @param[in] language The language selected from stt_foreach_supported_languages() (e.g. #NULL(Automatic), 'en_US')
+ * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #STT_ERROR_NONE Successful
+ * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
+ * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #STT_ERROR_INVALID_STATE Invalid state
+ * @retval #STT_ERROR_OPERATION_FAILED Operation failure
+ * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
+ * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
+ * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
+ * @pre The state should be #STT_STATE_READY.
+ * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
+ *       If this function succeeds, the STT state will be #STT_STATE_RECORDING.
+ *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_RECORDING.
+ * @see stt_stop_audio_streaming()
+ * @see stt_send_audio_streaming()
+ * @see stt_cancel()
+ * @see stt_state_changed_cb()
+*/
+int stt_start_audio_streaming(stt_h stt, const char* language, const char* type);
+
+
+/**
+ * @brief Sends audio data to STT engine.
+ * @since_tizen 8.0
+ * @remarks The audio format of @a data should satisfy the audio format from stt_get_audio_format().
+ * @param[in] stt The STT handle
+ * @param[in] data The raw PCM data
+ * @param[in] data_size The number of bytes of @a data
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #STT_ERROR_NONE Successful
+ * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
+ * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #STT_ERROR_INVALID_STATE Invalid state
+ * @retval #STT_ERROR_OPERATION_FAILED Operation failure
+ * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
+ * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
+ * @pre The state should be #STT_STATE_RECORDING.
+ * @post If you call this function after starting recording by stt_start(), you will receive #STT_ERROR_OPERATION_FAILED.
+ * @see stt_start_audio_streaming()
+ * @see stt_stop_audio_streaming()
+ * @see stt_cancel()
+ * @see stt_get_audio_format()
+*/
+int stt_send_audio_streaming(stt_h stt, const char* data, size_t data_size);
+
+
+/**
+ * @brief Finishes the audio streaming and starts recognition processing in engine asynchronously.
+ * @since_tizen 8.0
+ * @remarks This function can only stop recording started by stt_start_audio_streaming().
+ * @param[in] stt The STT handle
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #STT_ERROR_NONE Successful
+ * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
+ * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #STT_ERROR_INVALID_STATE Invalid state
+ * @retval #STT_ERROR_OPERATION_FAILED Operation failure
+ * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
+ * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
+ * @pre The state should be #STT_STATE_RECORDING.
+ * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
+ *       If this function succeeds, the STT state will be #STT_STATE_PROCESSING.
+ *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_PROCESSING.
+ *       If you call this function after starting recording by stt_start(), you will receive #STT_ERROR_OPERATION_FAILED.
+ *       After processing of engine, stt_result_cb() is called.
+ * @see stt_start_audio_streaming()
+ * @see stt_cancel()
+ * @see stt_state_changed_cb()
+*/
+int stt_stop_audio_streaming(stt_h stt);
+
+
+/**
+ * @brief Gets the recognizable audio format information.
+ * @since_tizen 8.0
+ * @param[in] stt The STT handle
+ * @param[out] type The audio type
+ * @param[out] rate The sample rates
+ * @param[out] num_of_channels The number of channels
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #STT_ERROR_NONE Successful
+ * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
+ * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #STT_ERROR_INVALID_STATE Invalid state
+ * @retval #STT_ERROR_OPERATION_FAILED Operation failure
+ * @pre The state should be #STT_STATE_READY.
+ * @see stt_send_audio_streaming()
+*/
+int stt_get_audio_format(stt_h stt, stt_audio_type_e* type, int* rate, int* num_of_channels);
+
+
 #ifdef __cplusplus
 }
 #endif