Custom Voice

Last Updated on : 2024-01-11 10:04:48download

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 audio 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


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


 * \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 audio file, which can be based on the cloud parameters or customized.
max_voice_num The maximum number of audio files that can be stored, used in tandem with VOICE_LIST_S.


 * \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 list

 * \fn OPERATE_RET tuya_ipc_get_voice_list  
 * \brief get voice list
 * \param[inout] voice_list is the voice list, voice list is array which has max_voice_num elements
 * \param[in] upgrade, update the latest voice list immediately if 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

 * \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

 * \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. Then, wait for MQTT to be connected for time synchronization before initializing and starting up.

Initialize and start Tuya SDK
Wait for MQTT to connect
Initialize custom voice with

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


  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 IoT Development Platform.

Log output

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

  • Initialization succeeds

    Custom Voice
  • Get voice list

    Custom Voice
  • Download voice list

    Custom Voice


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 audio file

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