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 channel at most
    		•  09/26/2023

    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_GetInputSamples 获取MIX算法输入的采样点数
    IaaMix_Run MIX算法处理
    IaaMix_Free 释放MIX算法资源
    IaaMix_setCallbackFunc MIX算法验证回调函数

    2.2. IaaMix_GetBufferSize

    • 功能

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

    • 语法

      int IaaMix_GetBufferSize(void);

    • 形参

      参数名称 描述 输入/输出

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    • 注意

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

    • 举例

      无。

    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

    • 注意

      • MIX算法仅支持16bit采样位宽

    • 举例

      无。

    2.4. IaaMix_SetConfig

    • 功能

      初始化MIX算法需要的参数。

    • 语法

      int IaaMix_SetConfig(MIX_HANDLE handle, AudioMixConfig_t *mixConfig);

    • 形参

      参数名称 描述 输入/输出
      handle MIX算法handle 输入
      mixConfig MIX算法的初始化结构体指针 输入

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    • 举例

      无。

    2.5. IaaMix_GetConfig

    • 功能

      打印MIX算法运行时的参数。

    • 语法

      int IaaMix_GetConfig(MIX_HANDLE handle);

    • 形参

      参数名称 描述 输入/输出
      handle MIX算法handle 输入

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    • 举例

      无。

    2.6. IaaMix_GetInputSamples

    • 功能

      获取MIX算法输入长度。

    • 语法

      int IaaMix_GetInputSamples(MIX_HANDLE handle, int *samples);

    • 形参

      参数名称 描述 输入/输出
      handle MIX算法handle 输入
      samples MIX算法输入样本数目 输出

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    • 举例

      无。

    2.7. IaaMix_Run

    • 功能

      MIX算法处理

    • 语法

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

    • 形参

      参数名称 描述 输入/输出
      handle 算法handle 输入
      input 输入数据 输入
      output 输出数据 输出

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    • 注意

      • 每个通道的采样率和采样位宽应该一致

    2.8. IaaMix_Free

    • 功能

      释放MIX算法的资源

    • 语法

      int IaaMix_Free(MIX_HANDLE handle);

    • 形参

      参数名称 描述 输入/输出
      handle MIX算法handle 输入

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    • 注意

      • 必须先调用IaaMix_Free，再释放供MIX算法所使用的内存。

    • 举例

      无。

    2.9. IaaMix_setCallbackFunc

    • 功能

      MIX算法验证回调函数（暂不支持）。

    • 语法

      int IaaMix_setCallbackFunc(int(*log)(const char *szFmt, ...),
                        int(*envSet)(char *key, char *par),
                        int(*envGetString)(char *var, char *buf, unsigned int size),
                        int(*envSave)(void),
                        int(*readUuid)(unsigned long long *u64Uuid));

    • 返回值

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

    • 依赖

      • 头文件: AudioMixProcess.h

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

    3. MIX 数据类型

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

    数据类型 定义
    AudioMixInit_t MIX算法初始化数据结构体类型
    AudioMixConfig_t MIX算法配置参数数据结构体类型
    MIX_HANDLE MIX算法句柄类型

    3.2. AudioMixInit_t

    • 说明

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

    • 定义

      typedef struct{
    int sampleRate;
    int bitWidth;
    int frameLength;
    int chnNum;
}AudioMixInit_t;

    • 成员

      成员名称 描述
      sampleRate 语音采样率，支持8kHz到48kHz采样率
      bitWidth 语音采样位宽，只支持16bit
      frameLength 语音帧长度，需要为128的倍数
      chnNum 通道数目，最大支持8路

    • 注意事项

      • 采样位宽只支持16bit

    • 相关数据类型及接口

      IaaMix_Init

    3.3. AudioMixConfig_t

    • 说明

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

    • 定义

      typedef struct{
    int stepSize;
    int chnGain[MIX_MAX_CHN_NUM];

      }AudioMixConfig_t;

    • 成员

      成员名称 描述
      stepSize 削顶时语音平滑步长，stepSize较大时，语音平滑度低；反之，语音平滑度高，取值范围：1~10
      chnGain 每个通道的音量，为正值时，音量增大；为负值时，音量减小， 取值范围：-80~80dB

    • 注意事项

      • 音量过大时会导致语音失真

    • 相关数据类型及接口

      IaaMix_SetConfig

    3.4. MIX_HANDLE

    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_VOLUME 通道音量大小不支持
    0x10000408 ALGO_MIX_RET_INVALID_STEPSIZE 语音变化步长不支持