SSTAR_MIX算法使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0.0	Initial release	11/12/2020
1.1.1	Modify some APIs	09/27/2021
1.1.2	Modify stepSize range	04/28/2022
2.0.0	New version	11/29/2022
2.1.0	Support 8 channels at most	09/26/2023
2.2.0	Add API: IaaMix_Reset. Add Data type: MIX_INPUT_TYPE MIX_MODE and in AudioMixConfig_t. Remove API:IaaMix_GetInputSamples, IaaMix_setCallbackFunc. Update Error Code and constraints.	03/12/2024

1. 概述¶

1.1. 算法说明¶

混音(MIX)是将多路音频信号数据混成一路音频信号的算法，目前最大支持8路音频输入。

1.2. 注意¶

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

2. API 参考¶

2.1. 功能模块API¶

API名	功能
IaaMix_GetBufferSize	获取MIX算法运行需要的内存大小
IaaMix_Init	初始化MIX算法
IaaMix_SetConfig	配置MIX算法参数
IaaMix_GetConfig	获取MIX算法参数
IaaMix_Run	MIX算法处理
IaaMix_Reset	重新初始化MIX算法
IaaMix_Free	释放MIX算法资源

2.2. IaaMix_GetBufferSize¶

功能

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

语法

unsigned int IaaMix_GetBufferSize(void);

返回值

返回值为MIX算法运行所需要的内存大小
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
注意

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

请参考IaaMix_Run举例部分。

2.3. IaaMix_Init¶

功能

初始化MIX算法

语法

MIX_HANDLE IaaMix_Init(char* workBufAddress, AudioMixInit_t *mixInit);

形参

参数名称描述输入/输出

workBufAddress MIX算法使用的内存地址输入

mixInit MIX算法的初始化结构体指针输入
返回值

返回值结果

handle 成功

NULL 失败
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
注意
- 采样位宽只支持16bit 并且每帧长度为128点
- 使用立体声输入时，最大支持4路
举例

请参考IaaMix_Run举例部分。

2.4. IaaMix_SetConfig¶

功能

配置MIX算法参数。

语法

ALGO_MIX_RET IaaMix_SetConfig(MIX_HANDLE handle, AudioMixConfig_t *mixConfig);

形参

参数名称描述输入/输出

handle MIX算法的句柄类型输入

mixConfig MIX算法的配置结构体指针输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
举例

请参考IaaMix_Run举例部分。

2.5. IaaMix_GetConfig¶

功能

获取MIX算法参数。

语法

ALGO_MIX_RET IaaMix_GetConfig(MIX_HANDLE handle, AudioMixConfig_t *mixConfig);

形参

参数名称描述输入/输出

handle MIX算法的句柄类型输入

mixConfig MIX算法的配置结构体指针输入/输出
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
举例

请参考IaaMix_Run举例部分。

2.6. IaaMix_Run¶

功能

MIX算法处理

语法

ALGO_MIX_RET IaaMix_Run(MIX_HANDLE handle, short *input, short *output);

形参

参数名称描述输入/输出

handle MIX算法的句柄类型输入

input 输入数据输入

output 输出数据输出
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
注意
- 每个通道的采样率和采样位宽应该一致

举例

#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <sys/time.h>
#include <sys/ioctl.h>
#include <stdlib.h>

#include "AudioMixProcess.h"
#define USE_MALLOC   (1)
#define FILE_NUMBER (2)
#define CHN_MAX (8)

typedef unsigned char               uint8;
typedef unsigned short              uint16;
typedef unsigned long               uint32;

float AVERAGE_RUN(int a)
{
    static unsigned int num = 0;
    static float avg = 0;
    if(num == 0) avg = 0;
    num++;
    avg = avg + ((float)a - avg) / ((float)num);
    return avg;
}
unsigned int _OsCounterGetMs(void)
{
    struct  timeval t1;
    gettimeofday(&t1,NULL);
    unsigned int T = ( (1000000 * t1.tv_sec)+ t1.tv_usec ) / 1000;
    return T;
}

int main(int argc, char **argv) {

    char infileName[FILE_NUMBER][512];
    char outfileName[512];
    short input[CHN_MAX*128];
    short output[128];
    FILE *in[FILE_NUMBER];
    FILE *out;
    int i;
    float avg = 0;
    int counter = 0;
    unsigned int T0,T1;
#if USE_MALLOC
    char *working_buf_ptr;
#else
    char working_buf_ptr [1024*500];
#endif

    int ret;
    MIX_HANDLE handle;
    AudioMixInit_t mixInit;
    AudioMixConfig_t mixConfig;

    /*********************User change section start*******************/
    mixInit.bitWidth = 16;
    mixInit.frameLength = 128;
    mixInit.sampleRate = 8000;
    mixInit.inputNumber = FILE_NUMBER;
    mixInit.inputType = MIX_INPUT_MONO;
    mixConfig.stepSize = 2;
    mixConfig.mode = MIX_SAMPLE_TO_SAMPLE;
    int gain_array[8]={2,0,0,0,1,0,1,2};
    for(i=0; i<FILE_NUMBER; i++)
    {
        mixConfig.chnGain[i] = gain_array[i];
    }
    /*********************User change section end*******************/

#if USE_MALLOC
    working_buf_ptr = (char*)malloc(IaaMix_GetBufferSize());
#endif

    handle = IaaMix_Init((char*)working_buf_ptr, &mixInit);
    if (handle == NULL)
    {
        printf("MIX init error !\n");
        return -1;
    }
    ret = IaaMix_SetConfig(handle, &mixConfig);
    for(i=0; i<FILE_NUMBER; i++)
    {
        sprintf(infileName[i],"./../sample/data/chn%d.wav", i);
        in[i] = fopen(infileName[i], "rb");
        if(!in[i])
        {
            printf("the input file %s could not be open\n",infileName[i]);
            return -1;
        }
    }

    sprintf(outfileName,"%s", "./SstarMixOut.wav");
    out = fopen(outfileName, "wb");
    if(!out)
    {
        printf("the output file %s could not be open\n",outfileName);
        return -1;
    }

    for (i=0;i<FILE_NUMBER;i++)
    {
        fread(input, sizeof(char), 44, in[i]);
    }
    fwrite(input, sizeof(char),44, out); // write 44 bytes output

    while(fread(input, sizeof(short), mixInit.frameLength*(int)(mixInit.inputType), in[0]))
    {
        counter++;
        for(i=1; i<FILE_NUMBER; i++)
        {
            fread(&(input[i*mixInit.frameLength*(int)(mixInit.inputType)]), sizeof(short), mixInit.frameLength*(int)(mixInit.inputType), in[i]);
        }
        T0  = (long)_OsCounterGetMs();
        ret = IaaMix_Run(handle, input, output);
        T1  = (long)_OsCounterGetMs();
        avg += (T1 - T0);
        if(ret != 0)
        {
            printf("Error occured in Mix\n");
            break;
        }

        fwrite(output, sizeof(short), mixInit.frameLength*(int)(mixInit.inputType), out);
    }
    IaaMix_Free(handle);
    avg /= counter;
    printf("AVG is %.2f ms\n",avg);

    for(i=0; i<FILE_NUMBER; i++)
    {
        fclose(in[i]);
    }
    fclose(out);

    free(working_buf_ptr);
    printf("Done\n");
    return 0;
}

2.7. IaaMix_Reset¶

功能

重新初始化MIX算法

语法

MIX_HANDLE IaaMix_Reset(char* workBufAddress, AudioMixInit_t *mixInit);

形参

参数名称描述输入/输出

workBufAddress MIX算法使用的内存地址输入

mixInit MIX算法的初始化结构体指针输入
返回值

返回值结果

handle 成功

NULL 失败
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
注意
- 采样位宽只支持16bit 并且每帧128点之输入
- 使用立体声输入时，最大支持4路
举例

请参考IaaMix_Run举例部分。

2.8. IaaMix_Free¶

功能

释放MIX算法的资源

语法

ALGO_MIX_RET IaaMix_Free(MIX_HANDLE handle);

形参

参数名称描述输入/输出

handle MIX算法的句柄类型输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a
注意
- 必须先调用IaaMix_Free，再释放供MIX算法所使用的内存。
举例

请参考IaaMix_Run举例部分。

3. MIX 数据类型¶

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

数据类型	定义
AudioMixInit_t	MIX算法初始化参数结构体类型
AudioMixConfig_t	MIX算法配置参数结构体类型
MIX_HANDLE	MIX算法句柄类型
MIX_INPUT_TYPE	MIX输入音频格式类型
MIX_MODE	MIX算法模式类型

3.2. AudioMixInit_t¶

说明

定义MIX算法的初始化参数结构体类型。

定义

typedef struct{

    int sampleRate;

    int bitWidth;

    int frameLength;

    int inputNumber;

    MIX_INPUT_TYPE inputType;

}AudioMixInit_t;

成员

成员名称	描述
sampleRate	语音采样率，支持8kHz~48kHz采样率
bitWidth	语音采样位宽，只支持16bit
frameLength	语音帧长度，仅支持 128点
inputNumber	输入数目，最大支持8路
inputType	MIX输入音频格式类型请参考 MIX_INPUT_TYPE

注意事项
- 采样位宽只支持16bit 并且每帧128点之输入
- 使用立体声输入时，最大支持4路
相关数据类型及接口

IaaMix_Init

3.3. AudioMixConfig_t¶

说明

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

定义

typedef struct{

    int stepSize;

    int chnGain[MIX_MAX_CHN_NUM];

    MIX_MODE mode;

}AudioMixConfig_t;

成员

成员名称	描述
stepSize	削顶时语音平滑步长，stepSize较大时，语音平滑度高；反之，语音平滑度低，取值范围：1~10
chnGain	每个通道的增益，为正值时，音量增大；为负值时，音量减小，取值范围：-80~80dB
mode	MIX算法模式类型请参考 MIX_MODE

注意事项
- 通道增益过大时会导致合成讯号过大而发生讯号剪裁(clipping)，用户须小心调整通道增益
相关数据类型及接口

IaaMix_SetConfig

IaaMix_GetConfig

3.4. MIX_HANDLE¶

说明

定义MIX算法句柄类型。
定义
```
typedef void* MIX_HANDLE;
```
注意事项

无
相关数据类型及接口

IaaMix_Init

IaaMix_SetConfig

IaaMix_GetConfig

IaaMix_Run

IaaMix_Reset

IaaMix_Free

3.5. MIX_INPUT_TYPE¶

说明

定义MIX输入音频格式类型

定义

typedef enum {

    MIX_INPUT_MONO       = 1,

    MIX_INPUT_STEREO     = 2,

}MIX_INPUT_TYPE;

成员

成员名称描述

MIX_INPUT_MONO MIX 输入音频格式为单声道

MIX_INPUT_STEREO MIX 输入音频格式为双声道
注意事项
- 当设定音频格式为双声道，最大支持4路，左右声道各自独立合成
- 不同输入无须交错排序
- 单声道合成举例 :给定不同输入单声道1[0~128], 单声道2[0~128]，则输入音频排序 :{ 单声道[0_{128],单声道[0}128]}
- 双声道合成举例 :给定不同输入双声道1[0~255], 双声道2[0~255]，则输入音频排序 :{ 双声道1[0~255], 双声道2[0~255]},其中双声道1[0~255], 双声道2[0~255] 内左右声道须交错排序
相关数据类型及接口

IaaMix_SetConfig

IaaMix_Reset

3.6. MIX_MODE¶

说明

定义MIX算法模式类型

定义

typedef enum {

    MIX_SAMPLE_TO_SAMPLE = 0,

    MIX_FRAME_TO_FRAME   = 1,

    MIX_DIRECT_ADD       = 2,

}MIX_MODE;

成员

成员名称描述

MIX_SAMPLE_TO_SAMPLE 点对点合成音频

MIX_FRAME_TO_FRAME 帧对帧合成音频

MIX_DIRECT_ADD 直接合成音频
注意事项
- MIX_SAMPLE_TO_SAMPLE: 当音频发生饱和时平滑程度较低，无延迟
- MIX_FRAME_TO_FRAME: 当音频发生饱和时平滑程度较高，但由于加窗而有128点之延迟
- MIX_DIRECT_ADD: 当音频发生饱和时，无平滑机制
相关数据类型及接口

IaaMix_SetConfig

4. 错误码¶

MIX API 错误码如表下所示：

错误码	宏定义	描述
0x00000000	ALGO_MIX_RET_SUCCESS	MIX运行成功
0x10000401	ALGO_MIX_RET_INVALID_LICENSE	LICENSE无效
0x10000402	ALGO_MIX_RET_INVALID_HANDLE	HANDLE无效
0x10000403	ALGO_MIX_RET_INVALID_SAMPLERATE	采样率不支持
0x10000404	ALGO_MIX_RET_INVALID_BITWIDTH	采样位数不支持
0x10000405	ALGO_MIX_RET_INVALID_FRAMELENGTH	语音帧长不支持
0x10000406	ALGO_MIX_RET_INVALID_CHN_NUM	通道数目不支持
0x10000407	ALGO_MIX_RET_INVALID_CHN_GAIN	通道音量增益不支持
0x10000408	ALGO_MIX_RET_INVALID_STEPSIZE	语音变化步长不支持
0x10000409	ALGO_MIX_RET_INVALID_INPUT_POINTER	MIX输入指标无效
0x10000410	ALGO_MIX_RET_INIT_ERROR	MIX初始化错误
0x10000411	ALGO_MIX_RET_INVALID_CALLING	MIX呼叫API顺序错误
0x10000412	ALGO_MIX_RET_INVALID_INPUT_TYPE	MIX输入音频格式错误
0x10000413	ALGO_MIX_RET_INVALID_MODE	MIX 模式错误

参数名称	描述	输入/输出
workBufAddress	MIX算法使用的内存地址	输入
mixInit	MIX算法的初始化结构体指针	输入

参数名称	描述	输入/输出
handle	MIX算法的句柄类型	输入
mixConfig	MIX算法的配置结构体指针	输入

成员名称	描述
MIX_INPUT_MONO	MIX 输入音频格式为单声道
MIX_INPUT_STEREO	MIX 输入音频格式为双声道

成员名称	描述
MIX_SAMPLE_TO_SAMPLE	点对点合成音频
MIX_FRAME_TO_FRAME	帧对帧合成音频
MIX_DIRECT_ADD	直接合成音频

返回值	结果
handle	成功
NULL	失败

返回值	结果
0	成功
非0	失败，参照错误码

返回值	结果
0	成功
非0	失败，参照错误码

返回值	结果
0	成功
非0	失败，参照错误码