Maix-Speech 详细使用文档

使用默认不带 MaixPy3 的镜像可进行下文操作

Maix ASR 目前完成的功能模块包括:连续数字识别(DIG), 关键词识别(KWS), 大词汇量连续语音识别(LVCSR)
该库基于 AM+LM 两段式识别,用户可灵活配置 声学模型和语言模型 来适应不同的嵌入式场景,也可加入热词等。

Maix ASR 运行流程简述

  1. asr_device 采集指定长度的原始音频,输出到int16_t数组里
  2. asr_preprocess 对原始音频进行 agc/anc/aec 等操作,并进行stft计算,生成80维MEL Fbank数据
  3. asr_am 对 fbank 进行声学模型计算,输出每个时刻(默认64ms一格)的拼音预测结果(前BEAM_CNT个)
  4. asr_decoder 对am的输出结果进行相关解码处理,实现对应功能,如 DIG/KWS/LVCSR
  5. decoder 运行用户注册的回调函数,执行用户逻辑代码

ms_asr.h中的宏定义和数据类型

发布版本

#define VERSION_RELEASE 0

默认公开发布的库文件为RELEASE版,失能了DBG相关宏功能

推理类型

#define INFER_ZHOUYI    0 //周易AIPU 推理
#define INFER_V83X      1 //V83X AWNN推理
#define INFER_CPU0      2 //CPU 推理
#define INFER_CPU1      3 //CPU 推理(弃用)

调试选项

在release版里失能

#define DBG_MICRAW  (1<<0) //运行时dump原始麦克风音频到 micraw.pcm
#define DBG_MIC     (1<<1) //运行时dump 前端处理后的音频到 mic.pcm
#define DBG_STRIP   (1<<2) //显示边界信息
#define DBG_LVCSR   (1<<3) //显示LVCSR解码详情
#define DBGT_PP     (1<<4) //音频前端处理计时
#define DBGT_AM     (1<<5) //AM模型运算计时
#define DBGT_KWS    (1<<6) //关键词解码计时
#define DBGT_WFST   (1<<7) //WFST解码计时

建模单元

声学模型建模单元,目前仅实现汉语识别的 CN_PNYTONE(含声调拼音)
其他宏定义预留

#define CN_PHONE        0
#define CN_PNY          1
#define CN_PNYTONE      2
#define CN_HAN          3
#define EN_PHONE        4
#define EN_SW1K         5
#define EN_SW3K         6
#define EN_SW5K         7
//en subword: https://bpemb.h-its.org/en/

量化方式

声学模型输出结果的量化方式

#define QUANT_NONE      0
#define QUANT_INT8      1
#define QUANT_UINT8     2

常量定义

#define BEAM_CNT        (10)             //每个时刻保留前BEAM_CNT个概率结果
#define ASR_KW_MAX_PNY  (6)              //每个关键词最多6个字
#define ASR_KW_MAX      (100)            //最多100个关键词

音频设备类型

目前支持 pcm, mic, wav 或者 用户自定义设备输入

#define DEVICE_PCM    0
#define DEVICE_MIC    1
#define DEVICE_WAV    2
#define DEVICE_MIC2   3
#define DEVICE_MIC4   4
#define DEVICE_CUSTOM 5

音频接口类

当用户有自定义的音频输入设备,或者需要使用自己的声学前端处理程序,可以实现以下音频设备接口
初始化时使用 DEVICE_CUSTOM 来选择自定义设备。

typedef struct{
    int  (*init)(char* device_name);            //初始化音频设备/文件
    int  (*read)(int16_t* data_buf, int len);   //读取指定长度音频到buf,返回读取到的数量
    void (*clear)(void);                        //清缓存
    void (*deinit)(void);						//释放音频设备
}asr_device_t;

解码器类型

解码器以位段形式表示,目前支持以下四种解码器(详细使用方式见下节)

#define DECODER_RAW   1      //raw解码器,返回AM输出的原始结果
#define DECODER_DIG   2		 //数字解码器,输出中文数字识别结果
#define DECODER_LVCSR 4		 //连续语音识别解码器,输出汉字结果
#define DECODER_KWS   8      //关键词识别解码器,输出当前时刻的各个关键词概率
#define DECODER_ALL   0xffff //选中所有解码器

AM初始化参数

AM初始化参数,参考例程填写

typedef struct{
    char* model_name;
    int model_in_len;
    int strip_l;
    int strip_r;
    int phone_type;
    int agc;
}am_args_t;

拼音概率

AM输出结果为 pnyp_t 数组,每个时刻 BEAM_CNT个。
可使用 am_vocab[idx]获取对应下标的拼音的字符串形式

typedef struct
{
    uint32_t idx;  //pny的下标
    float p;
}pnyp_t;

ms_asr.h中的函数接口

初始化

初始化asr库,用户选择对应的音频设备,AM模型参数,和调试选项
当用户使用自定义音频设备时,device_type填 DEVICE_CUSTOM ,device_name 填对应的 asr_device_t指针
注意解码器设置由另外独立API设置

int  ms_asr_init(int device_type, char* device_name, am_args_t* am_args, int dbg_flag);

释放

释放asr库相关资源

void ms_asr_deinit(void);

解码器设置

用户可以注册若干个解码器(当然也可以不注册),解码器的作用是解码声学模型的结果,并执行对应的用户回调

typedef void (*decoder_cb_t)(void* data, int cnt);
int  ms_asr_decoder_cfg(int decoder_type, decoder_cb_t decoder_cb, void* decoder_args, int decoder_argc);

DECODER_RAW
function: 输出原始AM的预测结果
decoder_args:None
cb_data: pnyp_t 指针,最近一帧的拼音概率列表,每格时刻保留 BEAM_CNT个拼音
cb_len: 最近一帧的解码格数,即: pnyp_t cb_data[cb_len][BEAM_CNT]

DECODER_DIG
function:输出最近4s内的中文数字识别结果
decoder_args:blank_ms, 超过该值则在输出结果里插入一个'_'表示空闲静音
cb_data: 最近4s的中文数字识别结果,字符串形式,支持 0123456789 .(点) S(十) B(百) Q(千) W(万)
cb_len: strlen(cb_data)

DECODER_KWS
function: 输出最近一帧所有注册的关键词的概率列表,用户可以观察概率值,自行设定阈值进行唤醒
decoder_args:

arg0: 关键词列表,以拼音间隔空格填写,如:
    char* my_kw_tbl[3]={
    (char*)"xiao3 ai4 tong2 xue2",
    (char*)"tian1 mao1 jing1 ling2",
    (char*)"tian1 qi4 zen3 me yang4"
    };
arg1: 关键词概率门限表
    虽然回调会输出所有关键词的概率,但是也需要概率门限表来去除上一帧输出过的有效关键词来排重
    按顺序排列输入即可
arg2: 关键词数量
arg3: 是否进行自动近音处理,置1则会自动将不同声调的拼音作为近音词来合计概率

cb_data: 最近一帧注册的所有关键词的概率(float,0~1)
cb_len: 关键词数量

注:cb_data中输出的值如果是负数,则表示对应的关键词上一帧刚输出过,需要排重。

相关函数:
手工注册静音词,每个拼音可以注册最多10个近音词。
注意,使用该接口注册近音词会覆盖使能 "自动近音处理" 里自动生成的近音表

int ms_asr_kws_reg_similar(char* pny, char** similar_pnys, int similar_cnt);
DEMO:
char* similar_pnys[3] = {(char*)"xin1", (char*)"ting1", (char*)"jin1"};
ms_asr_kws_reg_similar((char*)"jing1", similar_pnys, 3);

DECODER_LVCSR
function: 输出连续语音识别结果(小于1024个汉字结果)
decoder_args:

arg0: sfst_name, sfst文件路径(LG.fst)
arg1: sym_name, sym文件路径(输出符号表)
arg2: phones_txt, phones.bin的路径(拼音表)
arg3: words_txt, words.bin的路径(词典表)
arg4: beam, WFST搜索的beam大小,默认为5,建议在3~9之间,越大搜索空间越大,越精确但越慢
arg5: bg_prob, 在BEAM_CNT之外的背景拼音的默认概率值的自然对数的绝对值,默认为10
arg6: scale, acoustics_cost = log(pny_prob)*scale
arg7: is_mmap, 是否使用mmap方式加载WFST解码图。
    使用mmap方式则无需加载sfst文件到内存,使用即时磁盘读取的方式读取解码图,速度较慢,beam<=5时可以实时解码
    使用非mmap方式,读取整个sfst文件到内存,解码速度最快,beam上限可以到10

cb_data:

data0: char* words, 识别的汉字结果字符串,注意编码方式根据输入的words.bin的编码方式而定,可以为GBK或者UTF-8
data1: char* pnys, 识别的拼音字符串结果
注意,字符串内可能有','或者'.'表示语句停顿,如不需要则自行滤除

cb_len: 固定为2,表示返回了2个参数

清缓存

重置内部缓存操作,在开启新的语音识别前清一次

void ms_asr_clear(void);  

运行语音识别

frame: 每次run的帧数; 返回实际run的帧数
用户可以每次run 1帧,run完做其他处理;或者一个线程里一直run,由外部线程stop来停止
内部自动调用asr_device的read接口读入相应长度的数据进行出来

int  ms_asr_run(int frame); 

获取一帧的时间

返回一帧的时间 ms

int ms_asr_get_frame_time(void); 

获取声学模型词典

void ms_asr_get_am_vocab(char** vocab, int* cnt);

设置asr数据源

重新设置asr的数据源,一般在pcm/wav识别时使用,比如进行下一个wav文件识别
内部会自动进行缓存清除操作

int ms_asr_set_dev(int device_type, char* device_name); 

单独运行WFST解码

输入 T_CNTxBEAM_CNT 个拼音结果,进行decoder推理,用于lm的测试

void ms_asr_wfst_run(pnyp_t* pnyp_list); 

配置文件解析

例程使用opts.c来解析配置文件,用户可以在其上添加参数,或者自行编写配置解析函数。
例程的配置文件为极简的格式,行首#则记为注释(行尾#无效),
一行参数使用':'分割,格式为 arg_name:arg_value
参数说明(行尾的#仅为文档里的说明使用,实际不含该注释):

#device config
device_type:wav      #设备类型:wav,pcm,mic,custom
device_name:1.2.wav  #设备名

#am config
model_name:asr_7332_192.bin #am模型路径
model_in_len:192    #模型输入长度
strip_l:6           #左右边界长度
strip_r:6
phone_type:pnytone  #模型建模类型
agc:1               #是否使能AGC(自动增益控制)

#lm config
sfst_name:lg_6c.sfst #解码图文件路径
sym_name:lg_6c.sym   #输出符号表路径
phones_txt:phones.bin#拼音表路径
words_txt:words.bin  #词典表路径
font_path:./         #字体路径,可选
beam:8.0             #解码搜索宽度
bg_prob:10.0         #背景概率对数值的绝对值
scale:0.5            #声学分比例
is_mmap:0            #是否以mmap方式加载语言模型

#lib dbg
dbg_micraw:0         #是否dump原始mic音频到micraw.pcm
dbg_mic:0            #是否dump preproces后的音频到mic.raw
dbg_strip:0          #是否显示边界信息
dbg_lvcsr:0          #是否打印wfst解码详情
dbgt_pp:0            #preprocess计时
dbgt_am:0            #am模型运算计时
dbgt_kws:0           #kws解码计时
dbgt_wfst:0          #wfst解码计时

#app config
do_raw:0             #打印原始am模型结果
do_dig:0             #注册数字识别回调
do_kws:0             #注册关键词识别回调
do_lvcsr:1           #注册连续语音识别回调

#testbench config    #跑分测试配置
#testpath:/mnt/kws/aishell_test_1_10/ #待测试wav目录,不测试则注释掉改行
testpny:1            #输出pny测试结果
testhan:1            #输出han测试结果
#testlm:lm_test.txt  #LM测试文件(每行一句话的拼音字符串,空格分割,\n换行)