涂鸦国内语音 SDK 接口说明

更新时间：2024-11-20 08:51:19下载pdf

本文介绍涂鸦国内语音 SDK 接口详细信息。

名词解释

名词	解释
设备	指可供人们在生产中长期使用，并在反复使用中基本保持原有实物形态和功能的生产资料和物质资料的总称。在涂鸦平台，设备概指产品，和硬件具有同等含义。
SoC	为 System on Chip 的缩写，表示系统级芯片。如果产品采用了 SoC 设计，并且硬件本身没有搭载 MCU，则开发者可以将控制程序写入 SoC 或联网模组中。
联网模组	联网模组是一个可以集成到目标电子系统的元器件，联网是指连接到网络。联网模组就是将嵌入式系统连接到网络的电路模组。涂鸦智能提供以下几类模组，用来实现连接功能，但是连接的方式不同：Wi-Fi 模组、GPRS 模组、蓝牙 Mesh 模组、Wi-Fi & BLE 双模模组、Zigbee 模组、Sub-G 模组、NB-IoT 模组
DP	DP 为 Data Point 的缩写，即数据点，偶尔被称为 DP 点，表示智能设备所具备的功能点。涂鸦智能将每个功能点抽象成数据点，数据点定义成不同的类型，例如布尔、枚举、数值等。数据点具备读写属性。例如，一个两路的开关，可以抽象成两个数据点，每个数据点类型为布尔型，可取值为 True 或 False。数据点可读写，读表示获取开关目前的值，写表示改变开关目前的值。
DP ID	指定通信协议下 DP 事件的 ID。
Device ID	指设备 ID, 即设备的识别码。

组件模型

概述

国内语音 SDK 提供唤醒、录音、云端交互、串口控制等功能，开发者可在其基础上实现基于涂鸦平台的 IoT 产品应用开发，并将其产品进行语音入口赋能，实现对产品自身的语音控制，亦可实现对其他 Powered by Tuya 智能设备的语音控制。

涂鸦国内语音 SDK 接口说明

数据结构

DP 点枚举值，不同 DPID 对应不同的功能:

    TY_SYSTEM_DP_MEDIA_VOLUME = 203,    //音量
    TY_SYSTEM_DP_MEDIA_MIC = 204,       //麦克风
    TY_SYSTEM_DP_MEDIA_PLAYER = 205,    //播放/暂停
    TY_SYSTEM_DP_MEDIA_BT_PLAYER = 206, //蓝牙播放开关
    TY_SYSTEM_DP_MEDIA_ALAMRM = 207,    //本地闹钟
    TY_SYSTEM_DP_MEDIA_MISC_CTL = 208,  //语音控制组合
}TY_SYSTEM_DP_ME

播放器的播放状态：分为空闲、播放中、暂停状态闲、播放中、暂停状态

    PLAYER_IDEL = 0,
    PLAYER_PLAYING,
    PLAYER_PAUSE,
}PLAYER_STATE_E;

对播放器的操作：分为播放、暂停、续播、停止播放

    PLAYER_OPERATE_PALY = 0,
    PLAYER_OPERATE_PAUSE,
    PLAYER_OPERATE_RESUME,
    PLAYER_OPERATE_STOP,
}PLAYER_OPERATE_E;

当前播放器播放的音频类型：无、TTS、AUDIO、提示音、定制提示音

    PLAYER_TYPE_NONE = 0,
    PALYER_TYPE_TTS,
    PALYER_TYPE_AUDIO,
    PALYER_TYPE_TONE,
    PLAYER_TYPE_TONE_CUSTOM,
}PALYER_TYPE_E;

提示音枚举值：

    TONE_TYPE_AWAKE = 0,			唤醒词
    TONE_TYPE_NET_CONFIG,		我已进入配网状态...
    TONE_TYPE_MIC_CLOSE,		已关闭麦克风
    TONE_TYPE_MIC_OPEN,			已开启麦克风
    TONE_TYPE_NET_DISABLE,		无法连接互联网...
    TONE_TYPE_NET_DELAY,			网络太慢了...
    TONE_TYPE_STARTUP,			连上网提示音...
    TONE_TYPE_VOLUME,			音量调节提示音...
    TONE_TYPE_RING,				闹钟提示音...
    TONE_TYPE_AWAKE_MULTI,		
    TONE_TYPE_NET_CONFIG_SKYWORTH,
    TONE_TYPE_MAX
}TONE_TYPE_E;

提示音配置参数：

    UINT_T addr;
    UINT_T length;
    UCHAR_T priority;//数值越大，优先级越高
    TY_MEDIA_ENCODE_T decode_type;
}TONE_CONFIG_S;

唤醒配置时间结构体，单位:ms

    UINT_T force_record_tm;                     //最短录音时间
    UINT_T record_timeout_tm;                   //最长录音时间
    UINT_T recognition_timeout;                 //最长解析时间
}TY_VOICE_TRIGGER_TIMER_CFG_S;

对话轮次：

    VOI_FIRST_TALK = 0,                         //第一轮对话
    VOI_MULTI_TALK = 1,                        //多轮对话
}VOI_TALK_E;

唤醒状态：

    TRIGGER_IDEL = 0,                            	//空闲
    TRIGGER_MIC_CLOSE,                          //MIC 关闭(唤醒屏蔽)
    TRIGGER_WAKEUP,                             //唤醒
    TRIGGER_RECORDING,                          //录音
    TRIGGER_ANALYZE,                             //解析
    TRIGGER_ANALYZE_OK,                          //识别并执行成功
    TRIGGER_ANALYZE_FAIL,                        //识别失败或未执行
}TRIGGER_STATUS_E;

解码类型：

{
    audio_decoder_invalid,
    audio_decoder_m4a,
    audio_decoder_mp3,
    audio_decoder_opus,
}TY_AUDIO_DECODER_TYPE_E;

解码启动需要的参数：

{
    CHAR_T                          decoder_description[10];
    ty_decoder_hal_attr_change_cb   hal_attr_change_cb;
    ty_decoder_hal_output_cb        hal_output_cb;
    UINT_T                          output_buffer_length;
    UINT_T                          sample_rate_limit;
    UINT_T                          channels_limit;
}TY_AUDIO_DECODER_START_PARAM_S;

SDK 初始化参数结构体：

    TY_TRIGGER_STATUS_CB trigger_status_cb;
}TY_VOICE_COM_SDK_PARAMS;

适配层类型枚举值：

    VOICE_ADAPT_INTF_WAKEUP,
    VOICE_ADAPT_INTF_PLAYER,
    VOICE_ADAPT_ALL_INTF_NUMS
}VOICE_ADAPT_INTF_TYPE_E;

适配层 pcm 操作结构体

    OPERATE_RET (*init)         (VOID);
    OPERATE_RET (*open)         (BOOL_T dir);
    OPERATE_RET (*close)        (VOID);
    INT_T       (*read)         (VOID *data, INT_T count);
    INT_T       (*write)        (CONST VOID *data, INT_T count);
    OPERATE_RET (*control)      (INT_T cmd, VOID *args);
}TUYA_VOICE_ADAPT_PLAYER_INTF_S;

pcm_control 参数 cmd 的枚举选项：

    TUYA_PCM_READ_BUFF_INIT,    //read_buff init
    TUYA_PCM_VOL_SET,           //设置音量
    TUYA_PCM_VOL_GET,           //获取音量
    TUYA_PCM_RATE_SET,          //设置码率
    TUYA_PCM_ANALYZE,           //PCM 数据解析
}TUYA_PCM_CRTL_E;

唤醒组件初始化接口结构体选项：

    OPERATE_RET (*init)         (VOID);
    OPERATE_RET (*open)         (BOOL_T dir);
    OPERATE_RET (*close)        (VOID);
    INT_T       (*read)         (VOID *data, INT_T count);
    INT_T       (*write)        (CONST VOID *data, INT_T count);
    OPERATE_RET (*control)      (INT_T cmd, VOID *args);
}TUYA_VOICE_ADAPT_PLAYER_INTF_S;

接口描述

回调注册/销毁模块

函数名	功能概述	参数	返回
OPERATE_RET tuya_callback_framework_new_queue(TY_CALL_HANDLER **pHeader)	新建回调机	TY_CALL_HANDLER **pHeader：二级头指针（理解为链表）	OPRT_OK：成功；其他：失败
VOID tuya_callback_framework_free_queue(TY_CALL_HANDLER **handler)	释放回调机	TY_CALL_HANDLER **handler：二级头指针（理解为链表）	VOID
OPERATE_RET tuya_callback_framework_register_cb(TY_CALL_HANDLER handler, CALLBACK_FUNC_TYPE callback)	注册回调函数	TY_CALL_HANDLER handler：一级指针（创建时只需要创建一级指针即可）；CALLBACK_FUNC_TYPE callback：函数指针	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_callback_framework_unregister_cb(TY_CALL_HANDLER handler, CALLBACK_FUNC_TYPE callback)`	注销回调函数	TY_CALL_HANDLER handler：一级指针（创建时只需要创建一级指针即可）；CALLBACK_FUNC_TYPE callback：函数指针	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_callback_framework_cb_push(TY_CALL_HANDLER handler, VOID *params)`	推送回调函数	TY_CALL_HANDLER handler：一级指针（创建时只需要创建一级指针即可）；VOID *params：回调函数的参数	OPRT_OK：成功；其他：失败

推送回调函数参数为整形：

    do{                                                      \
        type tmp_value = value;                             \
        tuya_callback_framework_cb_push(handle, &tmp_value); \
    }while(0)

推送回调函数参数为指针：

define tuya_callback_framework_cb_push_pointer(handle, pointer) tuya_callback_framework_cb_push(handle, pointer)

使用流程

下载组件后在需要的地方#include tuya_callback_framework.h"。
在增加回调时，先调用tuya_callback_framework_new_queue新建回调机，再调用tuya_callback_framework_register_cb注册回调函数。
在删除回调时，先调用tuya_callback_framework_unregister_cb注销回调函数，再调用tuya_callback_framework_free_queue释放回调机。

示例：

参考 demo:

typedef VOID (*DEMO_CALLBACK_FUNC_TYPE)(VOID *params);
typedef struct {    int 	demo_value;    int	*demo_ pointer;}DEMO_S;
DEMO_S	demo_s;
DEMO_HANDLER *demo_handler；
DEMO_CALLBACK_FUNC_TYPE demo_callback_func;

增加回调：

tuya_callback_framework_register_cb(demo_handler, demo_callback_func);

触发回调：

tuya_callback_framework_cb_push_pointer(demo_handler, &demo_s);

注销回调：
tuya_callback_framework_unregister_cb(demo_handler, demo_callback_func);

解码器模块

函数名	功能概述	参数	返回
OPERATE_RET tuya_audio_decoder_start(TY_AUDIO_DECODER_TYPE_E decoder_type,TY_AUDIO_DECODER_START_PARAM_S p_start_param, TY_AUDIO_DECODER_CTX p_ctx)	开始解码	TY_AUDIO_DECODER_TYPE_E decoder_type：解码类型 TY_AUDIO_DECODER_START_PARAM_S p_start_param：解码启动需要的参数 TY_AUDIO_DECODER_CTX p_ctx：解码器指针	OPRT_OK：成功；其他：失败

SDK 初始化模块

功能说明

用于初始化服务，包含 SDK 初始化、云媒体初始化、唤醒算法初始化、消噪算法初始化、语音上传初始化和 DP 系统初始化。

使用流程

在需要的地方包含文件 .h 文件。
#include "tuya_voice_com_sdk_api.h"。

调用 tuya_voice_com_sdk_init(） 进行初始化操作。

函数名	功能概述	参数	返回	备注
OPERATE_RET tuya_voice_com_sdk_init(TY_VOICE_COM_SDK_PARAMS* ty_voice_com_sdk_params)	初始化	TY_VOICE_COM_SDK_PARAMS* ty_voice_com_sdk_params：初始化 sdk 的参数	OPRT_OK：成功；其他：失败	示例：TY_VOICE_COM_SDK_PARAMS ty_voice_com_sdk_params = {0}; tuya_voice_com_sdk_init(&ty_voice_com_sdk_params);

语音适配模块

| 函数名|功能概述|参数|返回|备注|
|:-----|:-----|:-----|:-----|:-----|:-----|
|OPERATE_RET tuya_voice_adapt_reg_intf(VOICE_ADAPT_INTF_TYPE_E type, VOID* intf_ptr)| 该接口给开发环境各类型的系统接口注册使用|

VOICE_ADAPT_INTF_TYPE_E type：适配的接口类型；

VOID* intf_ptr：播放器相关函数指针|

OPRT_OK：成功；

OPRT_OK：成功；

Dir：输入输出路径

TRUE：输入；

FALSE：输出|

OPRT_OK：成功；

OPRT_OK：成功；

data：读取的数据

pcm_write data：写入的数据；

Cmd：指令

（TUYA_PCM_CRTL_E）Args：待传入的参数|

OPRT_OK：成功；

其他：失败|-|

DP 系统模块

函数名	功能概述	参数	返回	备注
OPERATE_RET tuya_voice_cloud_media_init(VOID)	云媒体初始化	空	OPRT_OK：成功；其他：失败	用于 sdk_init 接口中，属于云媒体初始化步骤
OPERATE_RET tuya_voice_cloud_next_audio(VOID)	播放下一曲	空	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_cloud_pre_audio(VOID)	播放上一曲	空	OPRT_OK：成功；其他：失败	-
VOID tuya_voice_cloud_player_suspend_or_stop(VOID)	判断播放器需要挂起还是停止	空	空	-
OPERATE_RET tuya_voice_system_dp_handler_init(VOID)	DP 系统初始化停止	空	OPRT_OK：成功；其他：失败	用于 sdk_init 接口中，属于 DP 系统初始化步骤
VOID tuya_voice_system_dp_report(VOID)	系统 DP 上报	空	空	播放状态只有在播放 tts 或 AUDIO 时才会更新上报状态，播放本地音频时不上报
VOID tuya_voice_system_ring_start(VOID)	闹铃开始	空	空	-
VOID tuya_voice_system_ring_stop(BOOL_T b_stopPlay)	闹铃结束	BOOL_T b_stopPlay：一般为 true，表示续播 AUDIO	空	调用该接口，停止闹铃
VOID alarm_test(VOID)	模拟闹钟	空	空	调用该接口，直接走 dp 响应逻辑，启动闹铃

播放控制模块

函数名	功能概述	参数	返回	备注
tuya_voice_player_tts_play()	播放 TTS 音频	VOID	OPRT_OK：成功；其他：失败开始播报 TTS 音频
tuya_voice_player_audio_play()	播放 AUDIO 音频	VOID	-	OPRT_OK：成功；其他：失败
tuya_voice_player_tone_play(type)	播放本地 tone 音频	type：提示音类型	OPRT_OK：成功；其他：失败	-
tuya_voice_player_tone_custom_play(tone_config)	播放自定义本地 tone 音频	tone_config：提示音类型	OPRT_OK：成功；其他：失败	-
tuya_voice_player_stop()	功能概述	停止播放	空	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_player_relese_audio(VOID)	解除 AUDIO 的挂起/暂停状态，直接停止 AUDIO	空	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_suspend(VOID)	挂起播放器（停止 TTS/TONE，暂停 AUDIO）	空	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_continue(VOID)	恢复播放器	空	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_pause(VOID)	暂停操作（停止 TTS/TONE，暂停 AUDIO）	空	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_resume(VOID)	继续操作	空	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_set_tone_config(TONE_TYPE_E tone_type, TONE_CONFIG_S *tone_config)	设置 tone 配置	TONE_TYPE_E tone_type：提示音序号； TONE_CONFIG_S *tone_config：提示音配置参数	OPRT_OK：成功；其他：失败	-
VOID tuya_voice_player_clear_queue_and_stop(TY_AUDIO_DECODER_CTX *decoder_ctx, PALYER_TYPE_E player_type, PLAYER_OPERATE_E player_operate)	清空 PCM 队列停止播放器	TY_AUDIO_DECODER_CTX *decoder_ctx：解码指针； PALYER_TYPE_E player_type：当前播放器播放的音频类型； PLAYER_OPERATE_E player_operate：对播放器的操作	OPRT_OK：成功；其他：失败	示例：typedef PVOID_T TY_AUDIO_DECODER_CTX;TY_AUDIO_DECODER_CTX *decoder_ctx = NULL; PALYER_TYPE_E player_type;tuya_voice_player_clear_queue_and_stop(decoder_ctx, player_type, PLAYER_OPERATE_STOP);
OPERATE_RET tuya_voice_player_set_status(PALYER_TYPE_E player_type, PLAYER_OPERATE_E play_operate, VOID *params)	设置播放器状态	PALYER_TYPE_E player_type：当前播放器播放的音频类型 PLAYER_OPERATE_E play_operate：对播放器的操作 VOID *params：操作时所带的参数，一般为 NULL	OPRT_OK：成功；其他：失败	-
PLAYER_STATE_E tuya_voice_player_get_status(VOID)	获取播放器状态	空	PLAYER_STATE_E 播放器状态对应的枚举值	不区分 Tone/TTS/AUDIO，只区分播放状态
PALYER_TYPE_E tuya_voice_player_get_playing_type(VOID)	获取播放器状态	空	PALYER_TYPE_E 播放器类型对应的枚举值	获取当前播放音频的类型
VOID tuya_voice_player_set_vol(UCHAR_T vol_val)	设置播放器音量，范围 0~100，设置小于 0 按 0，大于 100 按 100 计算	vol_val：音量值	空	-
UCHAR_T tuya_voice_player_get_vol(VOID)	获取播放器音量	空	音量值大小	-
OPERATE_RET tuya_voice_player_tell(UINT_T p_offset, INOUT UINT_T p_totallen)	获取播放进度	UINT_T p_offset：偏移量； INOUT UINT_T p_totallen：总长	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_seek(UINT_T offset)	定位播放	offset：偏移量	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_write_data(PVOID_T hal_ctx, BYTE_T p_buf, UINT_T buf_len, UINT_T p_remain, BOOL_T finish,TY_COMM_MEDIA_S *p_com_type, IN CONST TY_PLAY_CTX ctx, PVOID_T private_data);	流数据 write 回调	offset：偏移量	OPRT_OK：成功；其他：失败	-
VOID tuya_voice_player_media_event_cb(IN TY_PLAY_CTX ctx, IN CONST MEDIA_PLAY_EVENT_E event, IN PVOID_T private_data, IN PALYER_TYPE_E player_type, TY_AUDIO_DECODER_CTX *decoder_ctx)	播放器事件	空	空	-
OPERATE_RET tuya_voice_player_state_cb_add_register(CALLBACK_FUNC_TYPE callback_func)	增加播放器状态回调	CALLBACK_FUNC_TYPE callback_func：函数指针	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_state_cb_unregister(CALLBACK_FUNC_TYPE callback_func)	注销播放器状态回调	CALLBACK_FUNC_TYPE callback_func：函数指针	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_set_vol_cb_add_register(CALLBACK_FUNC_TYPE callback_func)	增加调节音量回调	CALLBACK_FUNC_TYPE callback_func：函数指针	OPRT_OK：成功；其他：失败	-
OPERATE_RET tuya_voice_player_set_vol_cb_unregister(CALLBACK_FUNC_TYPE callback_func)	注销调节音量回调	CALLBACK_FUNC_TYPE callback_func：函数指针	OPRT_OK：成功；其他：失败	-
VOID tuya_voice_player_set_pcm_status(INT_T pcm_status)	设置 PCM 当前 opening 状态	INT_T pcm_status： TRUE：打开 FALSE：关闭	空	-
VOPERATE_RET tuya_voice_player_get_pcm_status(VOID)	获取 PCM 当前 opening 状态	空	OPERATE_RET： TRUE：打开 FALSE：关闭	-

录音模块

|函数名|功能概述|参数|返回|
|:-----|:-----|:-----|:-----|:-----|
| OPERATE_RET tuya_voice_record_init(VOID)|录音组件初始化|空|

OPRT_OK：成功；

TRUE：有 vad 信号；

FALSEL：无 vad 信号|

唤醒模块

函数名	功能概述	参数	返回
OPERATE_RET tuya_voice_trigger_init(VOID *wakpup_work_cfg)	语音唤醒组件初始化	VOID *wakpup_work_cfg：一般为 NULL	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_wake_up(VOI_TALK_E talk_type)	唤醒信号，由外部调用	VOI_TALK_E talk_type：对话轮次	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_record_cb(const UCHAR_T *buffer, UINT_T size)	录音数据回调，由外部调用	Buffer：录音处理后的 buff； Size：本次处理的 buff 大小	OPRT_OK：成功；其他：失败
OPERATE_RETtuya_voice_trigger_set_talk_params(TY_VOICE_TRIGGER_TIMER_CFG_S sFirst_talk_tm, TY_VOICE_TRIGGER_TIMER_CFG_S sMulti_talk_tm)	设置交互配置	sFirst_talk_tm：首次唤醒各个录音时间参数； sMulti_talk_tm：多次唤醒各个录音时间参数	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_set_mask(BOOL_T mask)	设置唤醒屏蔽	Mask：为 TRUE 时设置唤醒屏蔽；为 FALSE 时解除唤醒屏蔽	OPRT_OK：成功；其他：失败
BOOL_T tuya_voice_trigger_get_mask(VOID)	获取当前唤醒屏蔽的状态	空	TRUE：当前处于唤醒屏蔽状态; FALSE：当前处于非唤醒屏蔽状态
TRIGGER_STATUS_E tuya_voice_trigger_get_status(VOID)	获取当前 trigger 状态	空	返回 TRIGGER_STATUS_E 的状态枚举值
VOID tuya_voice_trigger_force_record_auto(VOID)	强制进入自动录音模式	空	空
VOID tuya_voice_trigger_force_record_manual_begin(VOID)	强制进入自动录音模式	空	空
VOID tuya_voice_trigger_force_record_manual_end(VOID)	强制退出手动录音模式	空	空
OPERATE_RET tuya_voice_trigger_edge_cb_add_register(CALLBACK_FUNC_TYPE callback_func)	增加唤醒前/后回调	callback_func：函数指针	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_edge_cb_unregister(CALLBACK_FUNC_TYPE callback_func)	注销唤醒前/后回调	callback_func：函数指针	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_state_cb_add_register(CALLBACK_FUNC_TYPE callback_func)	增加唤醒状态回调	callback_func：函数指针	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_state_cb_unregister(CALLBACK_FUNC_TYPE callback_func)	注销唤醒状态回调	callback_func：函数指针	OPRT_OK：成功；其他：失败
OOPERATE_RET tuya_voice_trigger_mask_cb_add_register(CALLBACK_FUNC_TYPE callback_func)	增加屏蔽唤醒回调	callback_func：函数指针	OPRT_OK：成功；其他：失败
OPERATE_RET tuya_voice_trigger_mask_cb_unregister(CALLBACK_FUNC_TYPE callback_func)	注销屏蔽唤醒回调	callback_func：函数指针	OPRT_OK：成功；其他：失败

语音上传模块

函数名	功能概述	参数	返回
OPERATE_RET voice_upload_ctrl_init(voice_upload_type type,upload_finished_cb finished_cb)	语音上传线程初始化	voice_upload_type type：一般传 VOICE_UPLOAD_MQTT； upload_finished_cb finished_cb：一般为 NULL	OPRT_OK：成功；其他：失败