MI SSL API


1. 概述


1.1. 算法说明

SSL(Sound Source Localization)声源定位,用于定位声音来源的方向。


1.2. 关键词说明

  • Direction

    当两个麦克风距离(distance)为5cm时,下图描述音源方向(direction)来源的定义:


1.3. 注意

为方便调试和确认算法效果,需要用户应用自行实现替换算法参数和抓取音频数据的逻辑。


2. API 参考


2.1. 功能模块API

API名 功能
IaaSsl_GetBufferSize 获取Ssl算法运行需要的内存大小
IaaSsl_Init 初始化Ssl算法
IaaSsl_Config 配置Ssl算法
IaaSsl_Get_Config 获取Ssl算法当前的配置参数信息
IaaSsl_Run Ssl算法处理
IaaSsl_Get_Direction 获取Ssl算法处理的结果
IaaSsl_Reset 重新初始化Ssl算法
IaaSsl_Free 释放Ssl算法资源

2.2. IaaSsl_GetBufferSize

  • 功能

    获取Ssl算法运行所需要的内存大小。

  • 语法

    unsigned int IaaSsl_GetBufferSize(void);
    
  • 形参

    参数名称 描述 输入/输出
  • 返回值

    返回值为Ssl算法运行所需要的内存大小

  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    该接口仅返回需要的内存大小,申请和释放内存的动作需应用来处理。

  • 举例

    请参考IaaSsl_Run举例部分。


2.3. IaaSsl_Init

  • 功能

    初始化Ssl算法。

  • 语法

    SSL_HANDLE IaaSsl_Init(char* working_buffer,AudioSslInit* ssl_init);
    
  • 形参

    参数名称 描述 输入/输出
    working_buffer Ssl算法所使用的内存地址 输入
    ssl_init Ssl算法的初始化结构体指针 输入
  • 返回值

    返回值 结果
    非NULL 成功
    NULL 失败
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    无。

  • 举例

    请参考IaaSsl_Run举例部分。


2.4. IaaSsl_Config

  • 功能

    配置Ssl算法。

  • 语法

    ALGO_SSL_RET IaaSsl_Config(SSL_HANDLE handle,AudioSslConfig* ssl_config);
    
  • 形参

    参数名称 描述 输入/输出
    handle Ssl算法handle 输入
    ssl_config Ssl算法的配置结构体指针 输入
  • 返回值

    返回值 结果
    0 成功
    非0 失败,参照错误码
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    无。

  • 举例

    请参考IaaSsl_Run举例部分。


2.5. IaaSsl_Get_Config

  • 功能

    获取Ssl算法当前的配置参数。

  • 语法

    ALGO_SSL_RET IaaSsl_Get_Config(SSL_HANDLE handle,AudioSslConfig *ssl_config);
    
  • 形参

    参数名称 描述 输入/输出
    handle Ssl算法handle 输入
    ssl_config Ssl算法的配置结构体指针 输出
  • 返回值

    返回值 结果
    0 成功
    非0 失败,参照错误码
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    无。

  • 举例

    请参考IaaSsl_Run举例部分。


2.6. IaaSsl_Run

  • 功能

    Ssl算法处理

  • 语法

    ALGO_SSL_RET IaaSsl_Run(SSL_HANDLE handle,short* microphone_input, int *delay_sample);
    
  • 形参

    参数名称 描述 输入/输出
    handle Ssl算法handle 输入
    microphone_input 待进行声源定位的数据指针 输入
    delay_sample 麦克风双声道的延迟样本数。此值建议当bf_mode开启时再拿作使用。 输出
  • 返回值

    返回值 结果
    0 成功
    非0 失败,参照错误码
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    • microphone_input指向的数据应以采样点为最小单位,按照L,R,L,R…的格式摆放。数据长度必须和IaaSsl_Init中设定的point_number(即多少个采样点进行一个声源定位处理)相对应。假设point number设定为128,则每个frame需读取128*2的点样本数,因为SSL的microphone_input必定为双声道。
  • 举例

    #include <stdio.h>
    #include <stdlib.h>
    
    #include "AudioSslProcess.h"
    
    /*  0:Fixed input file  1:User input file   */
    #define IN_PARAMETER 1
    
    int main(int argc, char *argv[])
    {
        AudioSslInit ssl_init;
        AudioSslConfig ssl_config;
        /**************User change section start**********************/
        /* The user modifies as needed,for example:5, 6(Unit: cm) */
        ssl_init.mic_distance = 5;
        /* The user modifies as needed,for example:128, ... */
        ssl_init.point_number = 128;
        /* The user modifies as needed */
        ssl_init.sample_rate = 48000;
        /* The user modifies as needed */
        ssl_init.bf_mode = 0;
        /* The user modifies as needed */
        ssl_config.temperature = 25;
        /* The user modifies as needed */
        ssl_config.noise_gate_dbfs = -40;
        /* The user modifies as needed */
        ssl_config.direction_frame_num = 100;
        /**************User change section end**********************/
        unsigned int workingBufferSize;
        SSL_HANDLE handle;
        ALGO_SSL_RET ret = ALGO_SSL_RET_SUCCESS;
        int delay_sample = 0;
        int direction;
        int counter = 0;
        int frame_number = ssl_config.direction_frame_num;
        short input[1024];
        char *workingBufferAddress = NULL;
        FILE* fpIn;  //input file
        char src_file[128] = {0};
    
    #if IN_PARAMETER
        if(argc < 2)
        {
            printf("Please enter the correct parameters!\n");
            return -1;
        }
        sscanf(argv[1], "%s", src_file);
    #else
        sprintf(src_file, "%s", "./mic34_gain1_ssong_continue.wav");
    #endif
    
        fpIn = fopen(src_file, "rb");
        if(NULL == fpIn)
        {
            printf("fopen in_file failed !\n");
            return -1;
        }
        printf("\nfopen in_file success !\n");
        //(1)IaaSsl_GetBufferSize
        workingBufferSize = IaaSsl_GetBufferSize();
        workingBufferAddress = (char *)malloc(sizeof(char) * workingBufferSize);
        if(NULL == workingBufferAddress)
        {
            printf("malloc SSL workingBuffer failed !\n");
            return -1;
        }
        printf("malloc SSL workingBuffer success !\n");
        //(2)IaaSsl_Init
        handle = IaaSsl_Init(workingBufferAddress, &ssl_init);
        if(NULL == handle)
        {
            printf("SSL:IaaSsl_Init  failed !\n");
            return -1;
        }
        printf("SSL:IaaSsl_Init  success !\n");
        //(3)IaaSsl_Config
        ret = IaaSsl_Config(handle, &ssl_config);
        if(ALGO_SSL_RET_SUCCESS != ret)
        {
            printf("SSL:IaaSsl_Config  failed !, ret = %d\n", ret);
            return -1;
        }
        printf("SSL:IaaSsl_Config  success !\n");
        ret = IaaSsl_Get_Config(handle, &ssl_config);
        if(ALGO_SSL_RET_SUCCESS != ret)
        {
            printf("IaaSsl_Get_Config failed !, ret = %d\n", ret);
        }
        printf("IaaSsl_Get_Config succeed !\n");
        printf("ssl_config.temperature = %u\n", ssl_config.temperature);
        printf("ssl_config.noise_gate_dbfs = %d\n", ssl_config.noise_gate_dbfs);
        printf("ssl_config.direction_frame_num = %d\n", ssl_config.direction_frame_num);
    #if 1
        /*Consider whether the input file has a header*/
        fread(input, sizeof(char), 44, fpIn); // Remove the 44 bytes header
    #endif
        while(1)
        {
            /*2 is the number of channels*/
            ret = fread(input, sizeof(short), ssl_init.point_number * 2, fpIn);
            if(ret != ssl_init.point_number * 2)
            {
                printf("break:endReadSize = The remaining size = %d.\n", ret);
                break;
            }
            //(4)IaaSsl_Run
            ret = IaaSsl_Run(handle, input, &delay_sample);
            if(ALGO_SSL_RET_SUCCESS != ret)
            {
                printf("SSL:IaaSsl_Run  failed !, ret = %d\n", ret);
            }
            counter ++;
            if(counter == frame_number && ssl_init.bf_mode == 0)
            {
                //(5)IaaSsl_Get_Direction
                ret = IaaSsl_Get_Direction(handle, &direction);
                if(ALGO_SSL_RET_SUCCESS != ret)
                {
                    printf("SSL:IaaSsl_Get_Direction  failed !, ret = %d\n", ret);
                }
                printf("The current direction:%d \n", direction);
                handle = IaaSsl_Reset(handle, &ssl_init);
                if(NULL == handle)
                {
                    printf("SSL:IaaSsl_Reset failed !\n");
                    return -1;
                }
                ret = IaaSsl_Config(handle, &ssl_config);
                if(ALGO_SSL_RET_SUCCESS != ret)
                {
                    printf("SSL:IaaSsl_Config failed !, ret = %d\n", ret);
                    return -1;
                }
                counter = 0;
            }
        }
        printf("Explain:If the current direction is not \
        in the -90~90 range, consult the API documentation.\n");
        //(6)IaaSsl_Free
        ret = IaaSsl_Free(handle);
        if(ALGO_SSL_RET_SUCCESS != ret)
        {
            printf("IaaSsl_Free failed !, ret = %d\n", ret);
        }
        free(workingBufferAddress);
        fclose(fpIn);
        printf("SSL end !\n");
        return 0;
    }
    

2.7. IaaSsl_Get_Direction

  • 功能

    获取Ssl算法的处理结果

  • 语法

    ALGO_SSL_RET IaaSsl_Get_Direction(SSL_HANDLE handle, int* direction);
    
  • 形参

    参数名称 描述 输入/输出
    handle Ssl算法handle 输入
    direction 此数值介于-90~90之间。当数值为-112时,若返回值为成功,则有两种可能,其一为音量低于noise_gate_dbfs,另一则为数据量不够,无法计算出可信的方向。若返回值不为0,则依错误码修正。 输出
  • 返回值

    返回值 结果
    0 成功
    非0 失败,参照错误码
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    无。

  • 举例

    请参考IaaSsl_Run举例部分。


2.8. IaaSsl_Reset

  • 功能

    重新初始化Ssl算法。

  • 语法

    SSL_HANDLE IaaSsl_Reset(SSL_HANDLE working_buffer,AudioSslInit* ssl_init);
    
  • 形参

    参数名称 描述 输入/输出
    working_buffer Ssl算法运行的内存地址 输入
    ssl_init Ssl算法的初始化参数结构体指针 输入
  • 返回值

    返回值 结果
    0 成功
    非0 失败,参照错误码
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    无。

  • 举例

    请参考IaaSsl_Run举例部分。


2.9. IaaSsl_Free

  • 功能

    释放Ssl算法资源

  • 语法

    ALGO_SSL_RET IaaSsl_Free(SSL_HANDLE handle);
    
  • 形参

    参数名称 描述 输入/输出
    handle Src算法handle 输入
  • 返回值

    返回值 结果
    0 成功
    非0 失败,参照错误码
  • 依赖

    • 头文件: AudioSslProcess.h

    • 库文件: libSSL_LINUX.so/ libSSL_LINUX.a

  • 注意

    无。

  • 举例

    请参考IaaSsl_Run举例部分。


3. SSL 数据类型


3.1. SSL模块相关数据类型定义

数据类型 定义
AudioSslInit Ssl算法初始化参数结构体类型
AudioSslConfig Ssl算法配置参数结构体类型
SSL_HANDLE Ssl算法句柄类型

3.2. AudioSslInit

  • 说明

    定义Ssl算法的初始化参数类型。

  • 定义

    typedef struct
    
    {
    
        unsigned int point_number;
    
        unsigned int sample_rate;
    
        unsigned int mic_distance;
    
        unsigned int bf_mode;
    
    }AudioSslInit;
    
  • 成员

    成员名称 描述
    point_number Ssl算法处理一次的采样点数
    sample_rate 取样率,目前支持8k/16k/32k/48k
    mic_distance 两个mic的距离,单位为cm
    bf_mode 是否为beamforming模式
  • 注意事项

    • 若需delay_sample 则建议将bf_mode开启。
  • 相关数据类型及接口

    IaaSsl_Init

    IaaSsl_Reset


3.3. AudioSslConfig

  • 说明

    定义Ssl算法的配置参数结构体类型。

  • 定义

    typedef struct
    
    {
    
        unsigned int temperature;
    
        int noise_gate_dbfs;
    
        int direction_frame_num;
    
    }AudioSslConfig;
    
  • 成员

    成员名称 描述
    temperature 环境温度(摄氏度) 摄氏度=(5/9)*(华氏度-32) 步长为1
    noise_gate_dbfs 噪音增益门限值(dBfs) 注意:低于此值将会把该帧作为噪声部分处理,则不会进入方向的计算。 步长为1
    direction_frame_num 声源定位功能检测的帧数 步长为50 注意:进行声源定位检测的帧数,数值必须为50的倍数,声源定位处理的一帧数据为128个采样点。检测一次的时间 = s32DirectionFrameNum * 128 / 采样率。如:当前采样率为48K,s32DirectionFrameNum设置成300,则检测时间=300 * 128 / 48000 = 0.8(s)
  • 注意事项

    • 无。
  • 相关数据类型及接口

    IaaSsl_Config

    IaaSsl_Get_Config


3.4. SSL_HANDLE


4. 错误码

SSL API 错误码如下表所示:

表 4‑1 SSL API错误码

错误码 宏定义 描述
0x00000000 ALGO_ SSL _RET_SUCCESS SSL执行成功
0x10000101 ALGO_ SSL _RET_INIT_ERROR SSL初始化错误
0x10000102 ALGO_ SSL _RET_INVALID_CONFIG SSL Config无效
0x10000103 ALGO_ SSL _RET_INVALID_HANDLE SSL Handle无效
0x10000104 ALGO_ SSL _RET_INVALID_SAMPLERATE SSL采样率无效
0x10000105 ALGO_ SSL _RET_INVALID_POINTNUMBER SSL采样点数无效
0x10000106 ALGO_SSL_RET_INVALID_BFMODE SSL init 的bf_mode设置无效
0x10000107 ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE 延迟样本过大,请检查设定的距离和取样率
0x10000108 ALGO_ SSL _RET_INVALID_CALLING SSL呼叫API顺序错误
0x10000109 ALGO_ SSL _RET_API_CONFLICT 有其他API正在运行