麦克风阵列Linux SDK
功能简介
麦克风阵列SDK基于科大讯飞MorfeiCore AIOT架构构建，利用从前端麦克风阵列采集的声音数据，通过麦克风阵列的空域滤波特性,和对唤醒人的角度定位，形成定向拾音波束，并对波束以外的噪声进行抑制，输出高质量的音频。本文主要描述阵列算法相关接口及调用流程，用于指导开发人员快速进行阵列算法集成。
#名词解释
表 1-1 名词解释
| 名词 | 说明 |
|---|---|
| 语音唤醒 | 将待唤醒的机器（低功耗状态）或应用，用带唤醒词的语音进行唤醒。 |
| 波束 | 麦克风阵列在录音时会形成拾音波束，对波束以外的噪声进行抑制，即对特定空间范围内的声音进行拾音。关于拾音波束以及和麦克之间关系的详细介绍参考《麦克风设计参考》。 |
| CAE | CAE：Circular Array Enhancement |
#授权说明
授权方式目前只支持云端授权方式。
云端授权方式：使用云端授权方式，设备需要具备联网能力。在启动麦克风阵列服务前设备需要联网，否则SDK无法通过网络获取授权，SDK能力将无法使用。在购买SDK开发包后，科大讯飞为每台设备分配productid （每个产品唯一）和deviceid（每台设备唯一），开发者在启动麦克风阵列服务时通过相应接口将productid和deviceid传入SDK。
#相关约定说明
文档中使用的符号约定：
表 1-2 约定说明
| 符号 | 含义 |
|---|---|
| [in] | 表明该参数是调用时赋值的参数——输入参数 |
| [out] | 该参数在函数返回时被赋值——输出参数 |
| [in/out] | 该参数在函数调用时作为输入、函数返回时作为输出参数 |
#麦克风阵列SDK接口说明
#接口调用流程
麦克风阵列接口基本功能使用，调用流程包括以下几个步骤（图2-1）：
（1） 启动MorfeiCore服务
（2） 初始化麦克风阵列引擎
（3） 创建引擎实例
（4） 注册引擎回调函数
（5） 写入多通道音频
（6） 通过回调函数输出降噪音频\唤醒结果
（7） 引擎实例资源释放
（8） 引擎逆初始化
（9） 停止MorfeiCore服务
图 2-1 麦克风阵列引擎工作流程
#MorfeiCore 接口函数列表
表 2-1 MorfeiCore 函数列表
| 函数名称 | 功能简介 |
|---|---|
| morfeicore_start | 初始化MorfeiCore 服务 |
| morfeicore_stop | 逆初始化MorfeiCore 服务 |
| morfeicore_getversion | 获取MorfeiCore版本号 |
#CAE 接口函数列表
表 2-2 CAE函数列表
| 函数名称 | 功能简介 |
|---|---|
| CAEInit | 初始化CAE引擎 |
| CAENew | 创建CAE引擎实例 |
| CAEGetVersion | 获取CAE引擎版本号 |
| CAELoadResource | 加载CAE资源 |
| CAESetListener | 设置CAE回调接口 |
| CAEGetParam | 获取CAE实例参数 |
| CAESetParam | 设置CAE实例参数 |
| CAEAudioWrite | 写入多通道录音数据 |
| CAEReset | 重置一个CAE实例 |
| CAEDestroy | 销毁CAE引擎实例 |
| CAEUnInit | 逆初始化CAE引擎 |
#返回值说明
对于开发接口，如果调用成功，返回值为int型的接口都会返回0，否则返回错误代码，错误代码参见aiot_errors.h。
#MorfeiCore函数调用
#morfeicore_start
函数原型
int morfeicore_start(const char *params, morfeicore_status_cb_t status_cb, void *user_data);
功能说明
初始化MorfeiCore服务，若同时使用基于MorfeiCore服务的其他SDK，则此函数只需调用一次。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| params[in] | 参数字符串 |
| status_cb[in] | 状态回调函数 |
| user_data[in] | 用户数据 |
status回调接口声明
typedef int ( *morfeicore_status_cb_t)( int type, int status, int param1, const void *param2, void *user_data);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| type [out] | 数据类型 |
| status [out] | 状态信息 |
| param1[out] | 保留参数 |
| param2[out] | 保留参数 |
| user_data[out] | 用户数据 |
#morfeicore_stop
函数原型
int morfeicore_stop(void);
功能说明
逆初始化MorfeiCore服务。
返回值
如果函数调用成功返回0，失败返回错误码。
#morfeicore_ getversion
函数原型
const char* morfeicore_getversion(void);
功能说明
获取MorfeiCore 版本号。
返回值
如果函数调用成功返回引擎版本号。
#CAE函数调用
#CAEInit
函数原型
int CAEInit(const char *param)
功能说明
初始化CAE引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| param[in] | 保留 |
#CAEUnInit
函数原型
int CAEUnInit()
功能说明
逆初始化CAE引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
#CAEGetVersion
函数原型
char* CAEGetVersion()
功能说明
获取CAE引擎版本号。
返回值
如果函数调用成功返回引擎版本号。
#CAENew
函数原型
int CAENew(CAE_HANDLE *handle, const char* respath, void *reserved)
功能说明
创建CAE引擎实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in/out] | 对象句柄 |
| respath[in] | 资源路径 |
| reserved | 保留 |
#CAEDestory
函数原型
int CAEDestory(CAE_HANDLE handle)
功能说明
销毁CAE引擎实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |
#CAESetListener
函数原型
int CAESetListener(CAE_HANDLE handle, void *userdata, const int cbtype, void* listener)
功能说明
设置CAE回调接口。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |
| cbtype[in] | 回调函数的类型，区分是那种回调函数 0:唤醒信息回调接，回调类型cae_ivw_cb 1:输出一路降噪后音频回调接口，回调类型cae_ivw_cb |
| listener[in] | 回调函数指针 |
| userdata[in] | 用户数据 |
唤醒成功回调接口声明
typedef void (*cae_ivw_cb)( short angle, short beam, char* keyword, float power, short score, void *userdata, void *reserved);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| angle [in] | 声源角度 |
| beam [in] | 唤醒波束 |
| keyword [in] | 唤醒词 |
| power [in] | 唤醒能量值 |
| score [in] | 唤醒得分 |
| userdata [in] | 用户数据 |
| reserved[in] | 保留 |
处理后音频输出回调接口声明
typedef void (*cae_audio_cb)( const char *audiodata, unsigned int audiolen, void *userdata, void *reserved);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| audiodata [in] | 音频缓存首地址（16K、16bit的单声道PCM音频数据） |
| audiolen [in] | 音频长度 |
| userdata [in] | 用户数据 |
| reserved | 保留 |
#CAEGetParam
函数原型
int CAEGetParam (CAE_HANDLE handle, const char* param, char* value, unsigned int *valuelen)
功能说明
获取CAE实例参数。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |
| name[in] | 参数名称 |
| value[in/out] | 获取的参数内容 |
| valuelen[in/out] | 传入value指针的空间长度，传出获取的参数长度 |
#CAESetParam
函数原型
int CAESetParam(CAE_HANDLE handle, const char* param, void* value, unsigned int valuelen);
功能说明
设置CAE实例参数。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |
| param[in] | 参数名 1.“reg_beam”:设置波束； 2.“channel_num”:设置mic和ref序号。 |
| value[in] | 参数值 1.指定一个波束传入，具体2麦可传入[0,1,2]，6麦传入[0,1,2,3,4,5]； 2.以6麦为例，其值可为“625184730”，前6个字符是mic序号，后三个730是参考序号，且只有通道7和3有效,第三路参考做保留使用。 |
| valuelen[in] | 参数长度 |
#CAEAudioWrite
函数原型
int CAEAudioWrite(CAE_HANDLE handle, const char *audiodata, unsigned int audiolen)
功能说明
写入多路音频数据。多路音频数据具体要求请参考《科大讯飞麦克风阵列SDK录音数据要求》文档说明。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |
| audiodata[in] | 音频数据地址 |
| audiolen [in] | 传入音频长度，字节为单位 |
#CAELoadResource
函数原型
int CAELoadResource(CAE_HANDLE handle, const char* respath)
功能说明
加载CAE资源。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |
| respath[in] | 资源路径 |
#CAEReset
函数原型
int CAEReset(CAE_HANDLE handle)
功能说明
重置一个CAE实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| handle[in] | 由CAENew创建的对象句柄 |