SGS MIX ALGORITHM USER GUIDE¶

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. OVERVIEW¶

1.1. Algorithm Introduction¶

Mixing (MIX) is an algorithm that mixes multiple audio signal data into one audio signal. Currently, it supports up to 8 audio inputs.

Keyword

MIX_INPUT_TYPE : Input data format type for MIX algorithm.

The format of audio files must be either mono or stereo. The format among different files for MIX algorithm must be same.

Note

In order to facilitate tuning and confirm the effect of the algorithm, users are required to implement their own logic for replacing algorithm parameters and capturing audio processing results.

1.2. Basic Structure¶

An input signal buffer and a output signal buffer are required for MIX algorithm to process. After the MIX algorithm allocates memory and completes parameter initialization and configuration, the input data buffer is processed by th MIX algorithm, and then written into the output data buffer. Notice that the length of input signal buffer and output buffer are not same because the MIX algorithm is a multiple input single output system.

1.3. Function Introduction¶

According to different gains for each audio signals, multiple audio signals are mixed into a single audio signal.

1.4. Application Scenarios¶

The Mix algorithm is commonly used post-production system or prompt system of doorbell. Multiple audio signals are mixed according to different gains to achieve better listening performance.

1.5. Chip Difference¶

Across different chip series, the MIX algorithm demonstrates consistent performance with no observable differences.

1.6. Examples Introduction¶

Use the MIX API to obtain the memory size required by the MIX algorithm, initialize the MIX algorithm handle, configure parameters to the MIX handle, execute the MIX algorithm, and release the MIX algorithm resources.

Example

#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 INTRODUCTION¶

2.1. Function Module API¶

API Name	Function
IaaMix_GetBufferSize	Get the memory size required to run MIX algorithm.
IaaMix_Init	Initialize MIX algorithm.
IaaMix_SetConfig	Set MIX algorithm parameters.
IaaMix_GetConfig	Get MIX algorithm parameters.
IaaMix_Run	Run MIX algorithm.
IaaMix_Reset	Reset MIX algorithm.
IaaMix_Free	Free the resource of MIX algorithm.
IaaMix_GetJsonFileSize	Get the memory size to parse the content of the Json file required by MIX algorithm
IaaMix_InitReadFromJson	Configure Json parameters to the init structure of the MIX algorithm
IaaMix_ConfigReadFromJson	Configure Json parameters to the config structure of the MIX algorithm

2.2. IaaMix_GetBufferSize¶

Function

Get the memory size required to run MIX algorithm.

Syntax

unsigned int IaaMix_GetBufferSize(void);

Return Value

The return value is the memory size required to run MIX algorithm.
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Note

The interface only returns the required memory size, the actions of allocating and releasing memory need to be processed by the application.
Example

Please refer to the example section of IaaMix_Run.

2.3. IaaMix_Init¶

Function

Initialize MIX algorithm.

Syntax

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

Parameter

Parameter Name Description Input/Output

workBufAddress The memory address used by MIX algorithm. Input

mixInit Pointer to the initialization structure of MIX algorithm. Input
Return Value

Return Value Result

Not NULL Successful.

NULL Failed.
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Note
- The sampling bit width only supports 16bit and the length of each frame is 128 points.
- When using stereo input, a maximum of 4 channels are supported.
Example

Please refer to the example section of IaaMix_Run.

2.4. IaaMix_SetConfig¶

Function

Set MIX algorithm parameters.

Syntax

ALGO_MIX_RET IaaMix_SetConfig(MIX_HANDLE handle, AudioMixConfig_t *mixConfig);

Parameter

Parameter name Description Input/Output

handle The handle of MIX algorithm. Input

mixConfig Configuration structure pointer of MIX algorithm. Input
Return Value

Return Value Result

0 Successful.

Non-Zero. Failed. Please refer to Error code
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Example

Please refer to the example section of IaaMix_Run.

2.5. IaaMix_GetConfig¶

Function

Get MIX algorithm parameters.

Syntax

ALGO_MIX_RET IaaMix_GetConfig(MIX_HANDLE handle, AudioMixConfig_t *mixConfig);

Parameter

Parameter name Description Input/Output

handle The handle of MIX algorithm Input.

mixConfig Configuration structure pointer of MIX algorithm. Input/Output
Return Value

Return Value Result

0 Successful.

Non-Zero. Failed. Please refer to Error code
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Example

Please refer to the example section of IaaMix_Run.

2.6. IaaMix_Run¶

Function

Run MIX algorithm.

Syntax

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

Parameter

Parameter Name Description Input/Output

handle The handle of MIX algorithm. Input

input Input data Input

output Output data Output
Return Value

Return Value Result

0 Successful.

Non-Zero. Failed. Please refer to Error code
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Note
- The sampling rate and sampling bitwidth of each channel should be the same.
Example

Please refer to 1.6. Examples Introduction.

2.7. IaaMix_Reset¶

Function

Reset MIX algorithm.

Syntax

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

Parameter

Parameter name Description Input/Output

workBufAddress Buffer address used by MIX algorithm Input

mixInit Initialization structure pointer of MIX algorithm Input
Return Value

Return Value Result

Not NULL Successful.

NULL Failed.
Dependency
- Header file: AudioMixProcess.h
- Library file: libMIX_LINUX.so/ libMIX_LINUX.a
Note
- The sampling bit width only supports 16-bit and 128-point input per frame.
- When using stereo input, a maximum of 4 channels are supported.
Example

Please refer to the example section of IaaMix_Run.

2.8. IaaMix_Free¶

Function

Free the resource of MIX algorithm.

Syntax

ALGO_MIX_RET IaaMix_Free(MIX_HANDLE handle);

Parameter

Parameter Name Description Input/Output

handle The handle of MIX algorithm. Input
Return Value

Return Value Result

0 Successful.

Non-Zero. Failed. Please refer to Error code
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Note

Please call IaaMix_Free before releasing the memory used by MIX algorithm.
Example

Please refer to the example section of IaaMix_Run.

2.9. IaaMix_GetJsonFileSize¶

Function

Get the memory size to parse the content of the Json file required by MIX algorithm.

Syntax

unsigned int IaaMix_GetJsonFileSize(char* jsonfile);

Parameter

Parameter Name Description Input/Output

jsonfile Json file name Input
Return Value

Return value is the memory size required for decoding json file.
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a

2.10. IaaMix_InitReadFromJson¶

Function

Configure Json parameters to the init structure of the MIX algorithm.

Syntax

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

Parameter

Parameter Name	Description	Input/Output
mixInit	MIX algorithm initialization structure handle	Input/Output
jsonBuffer	The memory address used to parse the Json file content	Input
jsonfile	Json file name	Input
buffSize	The memory size required to parse the Json file content	Input

Return Value

Return Value Result

0 Successful.

Non-Zero. Failed. Please refer to Error code
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Note

The API parses the initialization parameters into AudioMixInit_t structure from jsonfile, and is going to be used by IaaMix_Init.

2.11 IaaMix_ConfigReadFromJson¶

Function

Configure Json parameters to the config structure of the MIX algorithm.

Syntax

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

Parameter

Parameter Name	Description	Input/Output
mixConfig	Configure the structure handle of the MIX algorithm	Input/Output
jsonBuffer	The memory address used to parse the Json file content	Input
jsonfile	Json file name	Input
buffSize	The memory size required to parse the Json file content	Input

Return Value

Return Value Result

0 Successful.

Non-Zero. Failed. Please refer to Error code
Dependency
- Header File: AudioMixProcess.h
- Library File: libMIX_LINUX.so/ libMIX_LINUX.a
Note

The API parses the config parameters into AudioMixConfig_t structure from jsonfile, and is going to be used by IaaMix_SetConfig.

3. MIX DATA TYPE¶

DATA TYPE	Definition
AudioMixInit_t	MIX algorithm initialization parameter structure type
AudioMixConfig_t	MIX algorithm configuration parameter structure type
MIX_HANDLE	MIX algorithm handle type
MIX_INPUT_TYPE	MIX audio input format type
MIX_MODE	MIX algorithm mode type

3.2. AudioMixInit_t¶

Description

MIX algorithm initialization parameter structure type.

Definition

typedef struct{

    int sampleRate;

    int bitWidth;

    int frameLength;

    int inputNumber;

    MIX_INPUT_TYPE inputType;

}AudioMixInit_t;

Members

Member Name	Description
sampleRate	Audio sampling rate, supports 8/16/32/48kHz
bitWidth	Audio sampling bitwidth, only supports 16-bit
frameLength	Audio frame length, only supports 128 points
inputNumber	Input file numbers, supports up to 8 mono-channel inputs/ 4 stereo-channel inputs
inputType	Please refer to MIX_INPUT_TYPE for the MIX input audio format type

Note
- The sampling bitwidth only supports 16-bit and 128-point input per frame.
- When using stereo input, a maximum of 4 channels are supported.
Related Data Type and Interface

IaaMix_Init

IaaMix_Reset

IaaMix_InitReadFromJson

3.3. AudioMixConfig_t¶

Description

MIX algorithm configuration parameter structure type.

Definition

typedef struct{

    int stepSize;

    int chnGain[MIX_MAX_CHN_NUM];

    MIX_MODE mode;

}AudioMixConfig_t;

Members

Member name	Description
stepSize	Smoothness level when clipping. The larger the step size, the higher the smoothness. Value range: 1~10
chnGain	The gain for each files(dB value). Value range: -80~80dB
mode	Please refer to MIX_MODE for the MIX algorithm mode type

Note

When the channel gain is too large, the synthesized signal will be too large and signal clipping will occur. Users must adjust the channel gain carefully.
Related Data Type and Interface

IaaMix_SetConfig

IaaMix_GetConfig

IaaMix_ConfigReadFromJson

3.4. MIX_HANDLE¶

Description

MIX algorithm handle type.
Definition
```
typedef void* MIX_HANDLE;
```
Note

N/A.
Related Data Type and Interface

IaaMix_Init

IaaMix_SetConfig

IaaMix_GetConfig

IaaMix_Run

IaaMix_Reset

IaaMix_Free

3.5. MIX_INPUT_TYPE¶

Description

MIX audio input format type.

Definition

typedef enum {

    MIX_INPUT_MONO = 1,

    MIX_INPUT_STEREO = 2,

}MIX_INPUT_TYPE;

Members

Member name Description

MIX_INPUT_MONO MIX input audio format is mono

MIX_INPUT_STEREO MIX input audio format is stereo
Note
- When the audio format is set to stereo, a maximum of 4 inputs are supported, and the left and right channels are synthesized independently.
- In order to use more easily, different mono/stereo inputs don't need to be sorted in staggered order. However, the internal left/right channel data for each stereo input must still be staggered order.
- Mono synthesis example: Given different input mono 1[0~128], mono 2[0~128], then the input audio ordering: {mono[0_128],mono[0128]}.
- Stereo synthesis example: Given different input stereo 1[0~255], stereo 2[0~255], then the input audio ordering: { stereo 1[0~255], stereo 2[0~255]}, including stereo 1[0~255], stereo 2[0~255], the left and right channels must be staggered.
Related Data Type and Interface

IaaMix_SetConfig

IaaMix_Reset

3.6. MIX_MODE¶

Description

MIX algorithm mode type.

Definition

typedef enum {

    MIX_SAMPLE_TO_SAMPLE = 0,

    MIX_FRAME_TO_FRAME   = 1,

    MIX_DIRECT_ADD       = 2,

}MIX_MODE;

Member

Member name Description

MIX_SAMPLE_TO_SAMPLE Sample-to-sample synthesized audio

MIX_FRAME_TO_FRAME Frame-to-frame synthesized audio

MIX_DIRECT_ADD Direct synthesized audio
Note
- MIX_SAMPLE_TO_SAMPLE: Less smoothing and no delay when the audio is saturated.
- MIX_FRAME_TO_FRAME: The smoothness is higher when the audio is saturated, but there is a 128-point delay due to windowing.
- MIX_DIRECT_ADD: When the audio is saturated, there is no smoothing mechanism.
Related Data Type and Interface

IaaMix_SetConfig

4. Error code¶

MIX API Error Codes are shown in the following table:

Error Code	Macro Definition	Description
0x00000000	ALGO_MIX_RET_SUCCESS	MIX runs successfully.
0x10000401	ALGO_MIX_RET_INVALID_LICENSE	Invalid license.
0x10000402	ALGO_MIX_RET_INVALID_HANDLE	Invalid handle.
0x10000403	ALGO_MIX_RET_INVALID_SAMPLERATE	Invalid sampling rate.
0x10000404	ALGO_MIX_RET_INVALID_BITWIDTH	Invalid sampling bitwidth.
0x10000405	ALGO_MIX_RET_INVALID_FRAMELENGTH	Invalid sound frame length.
0x10000406	ALGO_MIX_RET_INVALID_CHN_NUM	Invalid channel number.
0x10000407	ALGO_MIX_RET_INVALID_CHN_GAIN	Invalid channel gain.
0x10000408	ALGO_MIX_RET_INVALID_STEPSIZE	Invalid audio step size.
0x10000409	ALGO_MIX_RET_INVALID_INPUT_POINTER	Invalid MIX input indicator
0x10000410	ALGO_MIX_RET_INIT_ERROR	MIX initialization error.
0x10000411	ALGO_MIX_RET_INVALID_CALLING	MIX calling API sequence error
0x10000412	ALGO_MIX_RET_INVALID_INPUT_TYPE	MIX input type error
0x10000413	ALGO_MIX_RET_INVALID_MODE	MIX mode error
0x10000414	ALGO_MIX_RET_INVALID_JSONFILE	MIX fails to read json file

Parameter Name	Description	Input/Output
workBufAddress	The memory address used by MIX algorithm.	Input
mixInit	Pointer to the initialization structure of MIX algorithm.	Input

Parameter name	Description	Input/Output
handle	The handle of MIX algorithm.	Input
mixConfig	Configuration structure pointer of MIX algorithm.	Input

Parameter name	Description	Input/Output
handle	The handle of MIX algorithm	Input.
mixConfig	Configuration structure pointer of MIX algorithm.	Input/Output

Parameter name	Description	Input/Output
workBufAddress	Buffer address used by MIX algorithm	Input
mixInit	Initialization structure pointer of MIX algorithm	Input

Member name	Description
MIX_INPUT_MONO	MIX input audio format is mono
MIX_INPUT_STEREO	MIX input audio format is stereo

Member name	Description
MIX_SAMPLE_TO_SAMPLE	Sample-to-sample synthesized audio
MIX_FRAME_TO_FRAME	Frame-to-frame synthesized audio
MIX_DIRECT_ADD	Direct synthesized audio

Return Value	Result
Not NULL	Successful.
NULL	Failed.

Return Value	Result
0	Successful.
Non-Zero.	Failed. Please refer to Error code

Return Value	Result
0	Successful.
Non-Zero.	Failed. Please refer to Error code

Return Value	Result
0	Successful.
Non-Zero.	Failed. Please refer to Error code

SGS MIX ALGORITHM USER GUIDE¶

REVISION HISTORY¶

1. OVERVIEW¶

1.1. Algorithm Introduction¶

1.2. Basic Structure¶

1.3. Function Introduction¶

1.4. Application Scenarios¶

1.5. Chip Difference¶

1.6. Examples Introduction¶

2. API INTRODUCTION¶

2.1. Function Module API¶

2.2. IaaMix_GetBufferSize¶

2.3. IaaMix_Init¶

2.4. IaaMix_SetConfig¶

2.5. IaaMix_GetConfig¶

2.6. IaaMix_Run¶

2.7. IaaMix_Reset¶

2.8. IaaMix_Free¶

2.9. IaaMix_GetJsonFileSize¶

2.10. IaaMix_InitReadFromJson¶

2.11 IaaMix_ConfigReadFromJson¶

3. MIX DATA TYPE¶

3.1. Definition of Data Type Related to MIX Module¶

3.2. AudioMixInit_t¶

3.3. AudioMixConfig_t¶

3.4. MIX_HANDLE¶

3.5. MIX_INPUT_TYPE¶

3.6. MIX_MODE¶

4. Error code¶