# 语音唤醒Linux SDK
# 功能简介
唤醒SDK基于科大讯飞MorfeiCore AIOT架构构建，唤醒引擎包括提取特征和解码两个部分，通过对输入特定帧长的音频提取特征，在进行解码网络处理判断唤醒状态并返回。本文主要描述唤醒算法相关接口及调用流程，用于指导开发人员快速进行唤醒算法集成。
# 名词解析
| 名词 | 说明 |
|---|---|
| 语音唤醒 | 将待唤醒的机器（低功耗状态）或应用，用带唤醒词的语音进行唤醒。 |
# 授权说明
唤醒SDK目前只支持云端授权方式。
云端授权方式：使用云端授权方式，设备需要具备联网能力。在启动唤醒服务前设备需要联网，否则SDK无法通过网络获取授权，SDK能力将无法使用。在购买SDK开发包后，科大讯飞为每台设备分配productid （每个产品唯一）和deviceid（每台设备唯一），开发者在启动麦克风阵列服务时通过相应接口将productid和deviceid传入SDK。
# 相关约定说明
文档中使用的符号约定：
| 符号 | 含义 |
|---|---|
| [in] | 表明该参数是调用时赋值的参数——输入参数 |
| [out] | 该参数在函数返回时被赋值——输出参数 |
| [in/out] | 该参数在函数调用时作为输入、函数返回时作为输出参数 |
# 唤醒SDK接口说明
# 接口调用流程
唤醒引擎流程包括以下几个步骤（图2-1）：
（1） 启动MorfeiCore服务
（2） 初始化引擎，初始化引擎内存函数
（3） 创建引擎实例
（4） 加载唤醒资源
（5） 注册唤醒引擎回调函数
（6） 写入唤醒音频
（7） 获得唤醒结果/获得唤醒回调
（8） 唤醒引擎重置
（9） 引擎资源释放
（10） 引擎逆初始化
（11） 停止MorfeiCore服务
# MorfeiCore接口函数列表
| 函数名称 | 功能简介 |
|---|---|
| morfeicore_start | 初始化MorFeiCore 服务 |
| morfeicore_stop | 逆初始化MorFeiCore 服务 |
| morfeicore_getversion | 获取MorFeiCore版本号 |
# IVW接口函数列表
| 函数名称 | 功能简介 |
|---|---|
| IVWInit | 初始化IVW引擎 |
| IVWNew | 创建IVW引擎实例 |
| IVWUnInit | 逆初始化IVW引擎 |
| IVWGetVersion | 获取IVW引擎版本号 |
| IVWLoadResource | 加载IVW资源 |
| IVWDestroy | 销毁IVW引擎实例 |
| IVWSetListener | 设置IVW回调接口 |
| IVWGetParam | 获取IVW实例参数 |
| IVWSetParam | 设置IVW实例参数 |
| IVWAudioWrite | 写入音频 |
| IVWReset | 重置一个IVW实例 |
| IVWGetResult | 获取IVW实例结果 |
# 返回值说明
对于开发接口，如果调用成功，返回值为int型的接口都会返回0，否则返回错误码，错误码详见aiot_errors.h。
# 函数调用
# IVWInit
函数原型
int IVWInit(struct AiotOS * param)
功能说明
初始化IVW引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| param[in] | 保留使用的结构体参数 |
# IVWUnInit
函数原型
int IVWUnInit()
功能说明
逆初始化IVW引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
# IVWGetVersion
函数原型
char* IVWGetVersion()
功能说明
获取IVW引擎版本号。
返回值
如果函数调用成功返回引擎版本号，例如：2.0.1001。
# IVWLoadResource
函数原型
int IVWLoadResource(const char * resouce, int length)
功能说明
加载IVW资源。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| resurce[in] | 唤醒引擎使用资源指针 |
| length[in] | 资源长度 |
# IVWNew
函数原型
int IVWNew(IVW_HANDLE* handle, const char * param, void *reserved)
功能说明
创建唤醒引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in/out] | 唤醒句柄 |
| param[in] | 唤醒引擎初始化参数 （ivw_type:low/high,ivw_num:yyy,appid:zzz） |
| reserved | 保留接口 |
# IVWDestory
函数原型
int IVWDestory(IVW_HANDLE handle)
功能说明
销毁IVW引擎实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
# IVWSetListener
函数原型
int IVWSetListener(IVW_HANDLE handle, const int cbtype, const void* listener, void* userdata)
功能说明
设置IVW回调接口。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
| cbtype[in] | 唤醒回调接口类型，区分是那种回调函数 （0:唤醒信息回调接口，回调类型PIVWCallBack） |
| listener[in] | 回调函数指针 |
| userdata[in] | 用户数据 |
回调类型
typedef int (*PIVWCallBack)(const char *param, void *userData);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| param [out] | 唤醒回调信息 |
| userdata [out] | 用户数据 |
# IVWGetParam
函数原型
int IVWGetParam(IVW_HANDLE handle, const char *name, char *value, int* length)
功能说明
获取IVW实例参数。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
| name[in] | 参数名称 |
| value[in/out] | 获取的参数内容 |
| length[in/out] | 获取的参数长度 |
# IVWSetParam
函数原型
int IVWSetParam(IVW_HANDLE handle, int paramtype, void* paramvalue, int length);
功能说明
设置实例参数。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
| paramtype[in] | 参数类型 |
| paramvalue[in] | 参数值 |
| length[in] | 参数长度 |
# IVWWriteAudio
函数原型
int IVWWriteAudio(IVW_HANDLE handle, const char* data, int length, int flag)
功能说明
写入唤醒音频。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
| data[in] | 音频数据地址（16k、16bit、单通道、pcm音频） |
| length[in] | 传入音频长度，字节为单位 |
| flag[in] | 当前数据状态标志 |
# IVWReset
函数原型
int IVWReset(IVW_HANDLE handle);
功能说明
重置一个唤醒实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
# IVWGetResult
函数原型
int IVWGetResult(IVW_HANDLE handle, char* result, int* length);
功能说明
获取实例结果。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 实例对象句柄指针 |
| result[in/out] | 唤醒结果 |
| length[in/out] | 唤醒结果长度 |
