# 实验室项目介绍
# 概述
聆思工作站对 CSK 自动测试项目支持了 测试音频下载、测试音频幅值自动调整、自动化测试唤醒/识别/误唤醒 等功能,以 test.csk
配置为基础,快速地构建一个可维护的测试项目,便于流程化地、可复用地进行自动化测试。
# 配置文件
自动化测试项目创建后,在项目目录中会生成 test.csk
配置文件,即为测试项目的配置文件,配置文件遵循 TOML (opens new window) 的语法进行配置。若项目目录中的配置文件被改名或者删除,那么将无法通过聆思工作站创建测试任务。
# 配置示例
下面是一个测试项目配置示例,字段前有部分注释解释,但可能较难理解,故建议在后文中参考各个字段的具体描述。
# 一个基本的项目配置样例
[auto_test]
# 项目名称,用于生成测试结论时的文件夹或文件命名
project_name="自动化测试项目"
# 测试设备配置
[[auto_test.devices]]
name="美的 4002 板子"
serial_port="COM4"
[[auto_test.tasks]]
# 任务名,在执行测试时在列表显示
name="basic"
# 任务类型
# 可用 type:
# recognize 唤醒识别测试
# wake_up 唤醒测试
# mistake_wake_up 误唤醒测试
# record_only 回放录音采集
type="recognize"
# 测试备注,创建输出文件夹时会用到。如果未定义或定为空,那么使用 name 作为文件夹名
remark="基础任务"
# 配置企业微信机器人 appid ,实现发送测试通知到企业微信
wework_appid=false
# 测试音频文件夹,若 ./ 开头则代表相对路径,否则需要完整路径
voice_directory="./result/人声音频/"
# 播放两个音频间的间隔时间,单位秒。填写前后静音段时,请充分考虑回复提示音长度,避免设备在播放提示音时收到语音请求。
silence_duration=3
[[auto_test.tasks]]
# 若不定义名称或名称与父任务重复,那么不会被使用
name="三米加噪"
# 定义父任务,可以继承父任务所有配置,仅替换需要覆盖的内容
# 若字段值的任务不存在,该任务视为未定义
parent="basic"
[[auto_test.tasks]]
name="3m加噪"
parent="basic"
[[auto_test.tasks]]
name="误唤醒"
type="mistake_wake_up"
Tips
想要注释部分区域可以通过选中若干行配置后,按下键盘
ctrl + /
的方式进行注释,加载配置时则会忽略这些配置
# 配置说明
# 项目信息
在 [auto_test]
标签下,可声明以下信息,用于描述项目的组成
[auto_test]
project_name=""
# 项目包含的测试任务
[[auto_test.tasks]]
# 任务说明见下文任务配置说明
# 设备配置
一个测试项目可以进行一项同时包含多个设备的测试任务,因此根据 TOML (opens new window) 语法,我们需要将任务声明为数组元素。所以所有测试任务的前缀都需要声明为
[[auto_test.devices]]
这样的配置表示 auto_test
这个配置对象中,包含一个名为 devices
的数组用以声明当前已连接且要用作测试的设备。
# 设备配置字段说明
一个测试设备所包含的所有基础信息属性如下
[[auto_test.devices]]
# 设备别名,用于标记设备,非必填
# 若不声明此设备则测试结论相关文件通过 serial_port 标识文件名,录音相关文件通过 address 标识文件名
name="美的4002板"
# 串口号,用于读取设备运行日志。串口号为重要参数,当且仅当进行类型为"回放采集(record_only)"的任务时可不填
serial_port="COM3"
# 串口读取波特率。不配置则默认使用 115200
baut_rate=115200
# 录音设备地址,用于读取设备录音。非必填,若不填则不保存此设备的录音
address=255
# 录音格式,用于剪辑录音和录音数据监测。非必填,若不填则不保存此设备的录音
record_format="16k32bit6ch"
# 唤醒词匹配正则表达式。非必填,若不声明则使用 Castor 默认正则。
# 需保证仅有一处括号括起来的匹配符,用于匹配出 group(1) 来比对是否命中预期结果
wakeup_regex=".+?\[TXT\]: (.+), \[KID\].+"
# 识别词匹配正则表达式。非必填,若不声明则使用 Castor 默认正则。
# 需保证仅有一处括号括起来的匹配符,用于匹配出 group(1) 来比对是否命中预期结果
word_regex=".+?\[TXT\]: (.+?), \[KID\].+"
# 超时日志匹配正则表达式。非必填,若不声明则使用 Castor 默认正则。
asr_timeout_regex=".+TIMEOUT.+"
# 填写串口
同一时间可能有多台设备进行连接,所以当需要读取设备日志的时候, serial_port
是必须的。
当 test.csk
打开后,通过右上角的 …
可以找到 显示当前可用的串口设备
点击后会列出当前可用的设备串口列表,从中选择你要读取日志的设备串口,填入配置即可。
# 启用录音
address
与 record_format
同时声明为正确的数值时,将保存该设备的录音。
# 如何获取 address
同一时间可能有多台设备进行连接,所以 address
是必须的。
当 test.csk
打开后,通过右上角的 …
可以找到 显示当前可用的录音设备
点击后会列出当前可用的录音设备地址列表,从中选择你要保存录音的设备地址,填入配置即可。
# 录音格式
设备保存的录音以 PCM 格式输出,对录音的解码需要根据格式来处理,因此 record_format
是必须的。
一个可用的 record_format
示例以及含义如下
16k16bit6ch
取值 | 含义 | 实际数值 |
---|---|---|
16k | 采样率 | 16000HZ |
16bit | 波特率 | 16 位 |
6ch | 通道数 | 6 |
# 如何配置正则
在设备配置中,wakeup_regex
, word_regex
, asr_timeout_regex
分别代表不同场景下用来判断设备状态的正则,各自的要求也有所不同。
# 匹配唤醒、识别日志
wakeup_regex
和 word_regex
分别代表要对唤醒和识别进行匹配,因此需要精确匹配到日志中代表唤醒词或识别词的语句。
在正则表达式的语法中,匹配到语句时,第一个 group
代表是语句本身,而后表达式中的剩余部分如果有括号 ()
括起,则会按顺序匹配到后续的 group
中。例如
如果使用 .+aaa.+
来匹配 bbbaaabbb
,那么第一个 group
就是 bbbaaabbb
。表达式中没有括号,所以整个匹配只有一个 group
。
如果使用 .+(aaa).+
来匹配 bbbaaabbb
,那么此时会有两个 group
,第一个是语句本身 bbbaaabbb
,第二个 group
为 aaa
。
下面来一个比较正式的例子。
假设设备唤醒的日志为
[2020/01/01] device_wake_up: {"keyword": "小飞小飞"}
那么我们可以编写表达式
.+device_wake_up.+"keyword": "(.+?)".*
这里表示,.+
匹配大于零个任意字符,只要找准比较唯一的数据,将他们用 .+
拼接起来。在这个例子中,device_wake_up
和 keyword
是比较具有象征性的词。
实际使用过程可以先使用 Regexr 网站 (opens new window) 进行测试,输入表达式和测试日志后,下方就会显示匹配结果。点击
Details
就可以看到匹配到的所有group
,这样可以确定是否真正匹配到了唤醒词或者识别词。
# 任务配置
一个测试项目中可以声明多种测试任务,因此根据 TOML (opens new window) 语法,我们需要将任务声明为数组元素。所以所有测试任务的前缀都需要声明为
[[auto_test.tasks]]
这样的配置表示 auto_test
这个配置对象中,包含一个名为 tasks
的数组用以声明可执行测试的任务。
# 任务配置字段说明
一个测试任务所包含的所有基础信息属性如下
[[auto_test.tasks]]
# 任务名,在执行测试时在列表显示
name="任务名称"
# 任务类型
# 可用 type:
# recognize 唤醒识别测试
# wake_up 唤醒测试
# mistake_wake_up 误唤醒测试
# record_only 回放采集
type="recognize"
# 任务别名,创建输出文件夹时会用到。如果未定义或定为空,那么使用 name 作为文件夹名
remark="任务别名"
# 配置企业微信机器人 appid ,实现发送测试通知到企业微信
wework_appid=""
# 测试音频文件夹,若 ./ 开头则代表相对路径,否则需要完整路径
voice_directory="./result/人声音频/"
# 播放音频前静音,单位秒
silence_duration = 1.6
# 识别超时时间,单位秒。离线场景根据固件内配置设置,在线场景酌情配置。
# 唤醒成功后,超过 {recognize_timeout} 毫秒没有识别结果则重新播放唤醒音频
recognize_timeout = 3
# 是否启用一次唤醒仅对应一次识别的模式
recognize_one_shot=false
# 输出声卡 index ,当你的电脑连接了多个声卡时,可以指定声卡 index,表示使用该声卡进行人声播放
# 当 index 不在可用声卡列表时,该配置无效
output_device_index=0
# 配置测试音频文件夹
当需要进行唤醒识别测试和回放采集任务的时候,需要给测试任务配置 voice_directory
属性。
通常我们习惯在项目中的 dataset
目录中存放各种测试音频,用于不同任务的测试。比较直观的目录结构可能为
- dataset
- 唤醒测试音频
- 唤醒识别测试音频
- ...等等
不同的测试任务,文件夹的音频存放规则有所不同。
# 唤醒测试
测试音频应当通过 ${词条}/音频文件
的形式存放。例如,如果测试音频为 小飞小飞
的音频,那么目录结构形如
- 唤醒测试音频
- 小飞小飞
- audio_0.wav
- audio_1.wav
- audio_2.wav
- 小美小美
- audio_0.wav
- ...
如果有多个唤醒词要测试,那么新建多个目录即可。
测试程序会遍历目录下的所有音频,用作测试音频数据进行测试。
# 唤醒识别测试
进行唤醒识别测试时,需要一个固定的唤醒音频,并且将音频名定位 wakeup_{唤醒词}.wav
。例如,如果一个唤醒音频的唤醒词为 小飞小飞
,则音频应命名为 wakeup_小飞小飞.wav
。
目录中的其他文件,则将被作为识别测试音频,并且音频的父目录应命名为词条名,一个完整的示例如
- dataset
- wakup_小飞小飞.wav
- 打开空调
- 1.wav
- 2.wav
- 3.wav
# 回放采集
回放采集只需要保证音频的父目录为词条名,例如
- dataset
- 小飞小飞
- 1.wav
- 2.wav
- 3.wav
- 小优小优
- 1.wav
- 2.wav
- 3.wav
# 高阶用法
为了可以更加便捷快速的配置并开始执行测试任务、或者实现一些更定制化的调用,我们也提供一些难度有所上升的使用方式。
# 父任务
你可以先配置好一个可能可复用的任务,而后提供 其他任务作为模板,声明为父任务
父任务示例
[[auto_test.task]]
name="basic"
remark="基础任务"
type="wake_up_and_recognize"
voice_directory="./测试音频集1"
子任务示例
parent="basic"
name="子任务示例1"
voice_directory="./测试音频集2"
在上述的示例中,父任务为 basic
,子任务为 子任务示例1
。
在子任务复用父任务参数的过程中,遵循以下几个规则:
parent
引用的是父任务的name
字段- 父任务中的配置,除了
name
任务名和remark
任务别名,其他字段参数都将被复用 - 暂不支持嵌套父任务,即
parent
的任务不能再有parent
,否则可能无法生成测试任务。 - 若
parent
引用的name
不属于当前项目配置的任务中,则无法生成此任务。
# 指定 python
执行路径
在安装 python3
的过程中,安装完成后可能并不会在环境变量中声明执行路径,导致终端中可能无法直接通过运行 python3
来执行相关脚本。你可以通过在配置文件中声明 python
执行路径,例如如果你的 python3
安装在 C:\\Python39\\python.exe
,那么你可以这样配置
[auto_test]
project_name="SOME_NAME"
python_executor="C:\\Python39\\python.exe"
声明路径时无需在意
\\
还是/
,都可以被识别。
# 执行测试任务
打开 test.csk
文件后,在 LStudio 右上方可以看到一系列相关的操作。
其中 『▶️ 执行』 代表运行测试任务。点击运行测试任务后,会列出当前配置文件声明的,可执行的测试任务。
点击将要执行的任务之后,将会在底部新建一个终端开始运行测试任务,终端中可以看到相关的运行日志输出。
注意:
- 每次点击运行后,都会新建一个终端,如果重复运行,那么可能会出现端口重复占用问题,建议运行前确认当前没有一个正在运行的测试任务终端。
- 程序开始运行后,如果需要停止任务,请通过在终端中按下键盘
ctrl + c
的方式停止,有助于程序正常释放资源。
# 检查测试结果
项目目录下,默认情况下可能有两个产物目录
- test_project
- test_result
- record_output
其中 test_result
代表测试结论相关输出文件, record_output
代表录音相关输出文件。
# 效果结论
测试任务启动后,会根据当前时间、项目名、任务名创建目录,目录下会包含以下文件
- 20200101120000_${项目名}${任务名}
- result_${设备名}.csv
- serial_${设备名}.log
- running.log
result_${设备名}.csv
为测试记录以及结论统计。
serial_${设备名}.log
为设备运行日志。
若有多设备同时进行测试,那么
result_${设备名}.csv
和serial_${设备名}.log
则会存在多个。
running.log
为测试程序运行日志,用于协助分析测试流程是否正常。
# 录音结论
record_output
目录下会存在一个 logs
目录,保存的是录音程序运行日志,以日期为文件名保存,可以用于协助分析录音是否正常。
所有录音回放任务启动后,会在 record_output
下以时间为名创建目录,目录下会包含如下子目录
- 01-01_12-00-00
- algo
- pcm
- raw
其中 algo
目录内的音频为 1 通道的 PCM 音频,目录下存在一个 target.txt
文件,描述音频文件与词条名的对应关系。该目录的产物可用作调优工具的输入音频。