SGS 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
2.3	Add API: IaaMix_GetJsonFileSize,IaaMix_InitReadFromJson,IaaMix_ConfigReadFromJson	12/06/2024
2.31	Update file description.	04/19/2025
2.32	Update stepSize and MIX_INPUT_TYPE description.	04/19/2025
2.33	Fix spelling error.	05/01/2025
2.34	Add and update description of Chapter 1	11/25/2025

1. 概述¶

1.1. 算法说明¶

混音(MIX)是将多个音频讯号根据不同的增益混合成一个音频信号的算法，目前最大支持8路音频输入 (8个单声道输入或4个双声道输入)。

关键词说明

MIX输入音频格式类型

输入档案讯号必须为单声道或双声道格式。不同输入档案的信道数必须相同。

注意

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

1.2. 基本结构¶

MIX需要输入 Buffer及输出 Buffer来进行处理。当MIX算法配置好内存，并完成参数初始化与设定后，将结果输出到输出 Buffer上。注意MIX 算法为多档案输入单档案输出系统，输入 Buffer 与输出 Buffer 长度并不同。

1.3. 功能介绍¶

将多个音频讯号根据不同的增益混合成一个音频信号。

1.4. 应用场景¶

MIX 常用于后制或一些门铃的提示音系统，将多个声音或背景声音透过不同增益进行混合提升聆听体验。

1.5. 芯片差异说明¶

在不同系列芯片，目前MIX算法效果上没有差异。

1.6. 实例介绍¶

使用MIX API获取MIX算法运行需要的内存大小、初始化MIX算法handle、配置参数至MIX算法handle、运行MIX算法与释放MIX算法资源。

举例

#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", "./MixOut.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. 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算法资源
IaaMix_GetJsonFileSize	MIX获取解析Json文件内容所需要的内存大小
IaaMix_InitReadFromJson	配置Json参数到MIX算法的初始化结构体指针
IaaMix_ConfigReadFromJson	配置Json参数到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算法的初始化结构体指针输入
返回值

返回值结果

非NULL 成功

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
注意
- 每个信道的取样频率和采样位宽应该一致。
举例

请参考1.6. 实例介绍

2.7. IaaMix_Reset¶

功能

重新初始化MIX算法

语法

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

形参

参数名称描述输入/输出

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

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

返回值结果

非NULL 成功

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举例部分。

2.9. IaaMix_GetJsonFileSize¶

功能

MIX获取解析Json文件内容所需要的内存大小。

语法

unsigned int IaaMix_GetJsonFileSize(char* jsonfile);

形参

参数名称描述输入/输出

jsonfile Json檔名输入
返回值

返回值为解析Json文件内容所需要的内存大小。
依赖
- 头文件: AudioMixProcess.h
- 库文件: libMIX_LINUX.so/ libMIX_LINUX.a

2.10. IaaMix_InitReadFromJson¶

功能

配置Json参数到MIX算法的初始化结构体指针。

语法

ALGO_MIX_RET IaaMix_InitReadFromJson(AudioMixInit_t* mixInit, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

形参

参数名称	描述	输入/输出
mixInit	MIX算法的初始化结构体指针	输入/输出
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

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

此API读取jsonfile内初始化设定至AudioMixInit_t结构体，提供给IaaMix_Init使用。

2.11. IaaMix_ConfigReadFromJson¶

功能

配置Json参数到MIX算法的配置结构体指针。

语法

ALGO_MIX_RET IaaMix_ConfigReadFromJson(AudioMixConfig_t* mixConfig, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

形参

参数名称	描述	输入/输出
mixConfig	MIX算法的配置结构体指针	输入/输出
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

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

此API读取jsonfile内初始化设定至AudioMixConfig_t结构体，提供给IaaMix_SetConfig使用。

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	取样频率，支持8/16/32/48kHz取样频率
bitWidth	位宽，只支持16bit
frameLength	每帧长度，仅支持 128点
inputNumber	输入档案数目，最大支持8路单声道，4路双声道
inputType	MIX输入音频格式类型请参考 MIX_INPUT_TYPE

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

IaaMix_Init

IaaMix_Reset

IaaMix_InitReadFromJson

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	不同档案的增益(dB值)，取值范围：-80~80dB
mode	MIX算法模式类型请参考 MIX_MODE

注意事项

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

IaaMix_SetConfig

IaaMix_GetConfig

IaaMix_ConfigReadFromJson

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. Error Code¶

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模式错误
0x10000414	ALGO_MIX_RET_INVALID_JSONFILE	MIX读取Json档失败

参数名称	描述	输入/输出
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	直接合成音频

返回值	结果
非NULL	成功
NULL	失败

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

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

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