# 实验室项目介绍

# 概述

聆思工作站对 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 打开后,通过右上角的 可以找到 显示当前可用的串口设备

点击后会列出当前可用的设备串口列表,从中选择你要读取日志的设备串口,填入配置即可。

# 启用录音

addressrecord_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_regexword_regex 分别代表要对唤醒和识别进行匹配,因此需要精确匹配到日志中代表唤醒词或识别词的语句。

在正则表达式的语法中,匹配到语句时,第一个 group 代表是语句本身,而后表达式中的剩余部分如果有括号 () 括起,则会按顺序匹配到后续的 group 中。例如

如果使用 .+aaa.+ 来匹配 bbbaaabbb ,那么第一个 group 就是 bbbaaabbb。表达式中没有括号,所以整个匹配只有一个 group

如果使用 .+(aaa).+ 来匹配 bbbaaabbb ,那么此时会有两个 group ,第一个是语句本身 bbbaaabbb ,第二个 groupaaa

下面来一个比较正式的例子。

假设设备唤醒的日志为

[2020/01/01] device_wake_up: {"keyword": "小飞小飞"}

那么我们可以编写表达式

.+device_wake_up.+"keyword": "(.+?)".*

这里表示,.+ 匹配大于零个任意字符,只要找准比较唯一的数据,将他们用 .+ 拼接起来。在这个例子中,device_wake_upkeyword 是比较具有象征性的词。

实际使用过程可以先使用 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_${设备名}.csvserial_${设备名}.log 则会存在多个。

running.log 为测试程序运行日志,用于协助分析测试流程是否正常。

# 录音结论

record_output 目录下会存在一个 logs 目录,保存的是录音程序运行日志,以日期为文件名保存,可以用于协助分析录音是否正常。

所有录音回放任务启动后,会在 record_output 下以时间为名创建目录,目录下会包含如下子目录

- 01-01_12-00-00
  - algo
  - pcm
  - raw

其中 algo 目录内的音频为 1 通道的 PCM 音频,目录下存在一个 target.txt 文件,描述音频文件与词条名的对应关系。该目录的产物可用作调优工具的输入音频。