Custom Voice

This topic describes the custom voice feature that enables the device to download the pre-recorded voice files from the cloud through the mobile app.

How it works

The device downloads voice files from the cloud to local storage. In this process, the device interacts with the mobile app and cloud to request the list of voice files and download them.

Related files

tuya_ipc_voice.h

Data structure

This feature requires the following data structures.

Voice list

typedef struct
{
    BOOL_T valid;
    BOOL_T isPreset;
    CHAR_T name[VOICE_NAME_LEN+1];
    CHAR_T filename[VOICE_FILENAME_LEN+1];
    INT_T  id;
    UINT_T size;
    UINT_T duration;
} VOICE_LIST_S;

Voice download callback

/**
 * \brief callback to process downloading voice data
 * \param[in] data is voice data
 * \param[in] len is voice data length
 * \param[in] pri_data is pointer set in tuya_ipc_voice_download_start api
 * \return OPERATE_RET
 */
typedef OPERATE_RET (*GET_VOICE_DATA_CB)(IN BYTE_T *data, IN UINT_T len, IN PVOID_T pri_data);

/**
  * \brief callback when download finished
 * \param[in] download_result > 0: download succeeded
 *            download_result == 0: download is stopped by tuya_ipc_voice_download_stop api
 *            dowaload_result < 0: download failed
 * \param[in] pri_data is pointer set in tuya_ipc_voice_download_start api
 * \return VOID
 */
typedef VOID (*VOICE_NOTIFY_CB)(IN INT_T download_result, IN PVOID_T pri_data);

API description

Initialization

/**
 * \fn OPERATE_RET tuya_ipc_voice_init  
 * \brief initialize voice
 * \param[in] code is voice code
 * \param[in] max_voice_num is max voice number in voice list
 * \return OPERATE_RET
 */
OPERATE_RET tuya_ipc_voice_init(IN CHAR_T *code, IN UINT_T max_voice_num);

Parameter description

Parameter	Description
code	The prefix of the downloaded voice file, which can be based on the cloud parameters or customized.
max_voice_num	The maximum number of voice files that can be stored, used in tandem with VOICE_LIST_S.

Deinitialization

/**
 * \fn VOID tuya_ipc_voice_uninit  
 * \brief uninitialize voice
 * \return VOID
 */
VOID tuya_ipc_voice_uninit(VOID);

Stop the download and exit the internal thread.

Get voice code

/**
 * \fn OPERATE_RET tuya_ipc_get_voice_code  
 * \brief get voice code
 * \param[inout] voice_code, is the voice code
 * \param[inout] code_len, voice code string len
 * \return OPERATE_RET
 */
OPERATE_RET tuya_ipc_get_voice_code(INOUT CHAR_T *voice_code, INOUT INT_T* code_len);

The voice code can only be obtained from the cloud when the device is connected to the internet.

Get voice list

/**
 * \fn OPERATE_RET tuya_ipc_get_voice_list  
 * \brief get voice list
 * \param[inout] voice_list is the voice list, voice list is an array which has max_voice_num elements
 * \param[in] upgrade, update the latest voice list immediately if the upgrade is TRUE
 * \return OPERATE_RET
 */
OPERATE_RET tuya_ipc_get_voice_list(INOUT VOICE_LIST_S *voice_list, BOOL_T upgrade);

Parameter description

Parameter	Description
voice_list	The input and output parameters. The linked list will be populated with file information retrieved from the cloud. Each file corresponds to an element in the linked list and contains information that can be used for parameter passing during voice download, such as an ID.
upgrade	Specifies whether to update to the latest voice list.

Download voice file

/**
 * \fn OPERATE_RET tuya_ipc_voice_download_start
 * \brief start downloading voice
 * \param[in] code is voice code
 * \param[in] id is voice id for each voice file
 * \param[in] get_voice_cb is voice file downloading callback function
 * \param[in] voice_notify_cb is voice file download finished callback function
 * \param[in] priv_data is pointer passed to get_voice_cb and voice_notify_cb callback function
 * \return OPERATE_RET
 */
OPERATE_RET tuya_ipc_voice_download_start(IN CHAR_T *code, IN INT_T id, IN GET_VOICE_DATA_CB get_voice_cb, IN VOICE_NOTIFY_CB voice_notify_cb, IN PVOID_T pri_data);

Parameter description

Parameter	Description
code	The code is identical to the one used during initialization.
id	The ID of the voice file to be downloaded.
get_voice_cb	The download callback, to be implemented by you. You can save the voice file in the callback.
voice_notify_cb	The download completion callback, to be implemented by you, is automatically invoked when the download is finished.
pri_data	The handle to parameter passing for the above callbacks.

Stop downloading voice file

/**
 * \fn VOID tuya_ipc_download_stop  
 * \brief stop downloading voice
 * \return VOID
 */
VOID tuya_ipc_voice_download_stop(VOID);

Terminate the ongoing download task.

Integration process

This feature depends on basic services such as networking and time. First, activate the device and bind it with the mobile app. Wait for MQTT to be connected for time synchronization. Then, as required by the upper-level business, obtain the voice code from the cloud or local records for initialization and startup. The following diagram shows the process:

After the voice feature is initialized, the device can get and download the voice file when needed.

Procedure

1. Record a voice using the mobile app. The device does not respond to this recording action. The mobile app uploads the voice recording to the cloud.
2. A voice is selected on the mobile app. The mobile app sends the selected voice ID to the device through DP data transmission. After receiving the ID, the device calls tuya_ipc_voice_download_start to download the voice file. The required DP is configured on the Tuya Developer Platform.

Log output

During debugging, it is recommended to set the log level to tuya_ipc_set_log_attr(4,NULL).

• Initialization succeeds

  

• Get voice list

  

• Download voice list

  

FAQs

Initialization failed

Check if the parameters are passed properly.

The retrieval of the file list failed, or there are only a few files

• Check if the parameters are valid.
• Check if the size of voice_list is acceptable.

Voice download failed

• Check if the file ID is valid and if the file exists in the cloud.
• Check if the code parameter is valid.
• Check the network status.
• Check the callbacks.

Unable to play the downloaded voice file

• Check if the size of the downloaded voice file matches the obtained information.
• The voice file is in .wav format. Check if the player supports this format.

Is it possible to start multiple tuya_ipc_voice_download_start tasks simultaneously?

Multitasking is not currently supported.