VoxLedger

声纹注册、验证与评测的 Python 工具箱，提供 NumPy 基线、注册库、试验列表、分数校准和可分享的报告。

作者：Yang Chuanjun · 深圳大学。

时间线说明

本项目于 2026 年 9 月创建和验证。Git 中 2025 年至 2026 年中的日期是本次生成的演示时间线，不代表那些日期已经开展的工作。每次开发提交均执行构建、测试、格式与静态检查；未使用空提交。项目未宣称论文成果、预训练模型或真实语音数据集成绩。

快速开始

make install
make build
make test
make format-check
make lint
make typecheck
.venv/bin/python examples/synthetic-demo.py --output /tmp/voxledger-demo

演示会生成两个不同频率的合成音频、注册库、试验分数、指标 JSON 和 HTML/Markdown 报告。合成音不是人声，输出仅验证工具流程。

能力

环节	提供的工具
音频	WAV PCM 8/16/24/32 位读取，IEEE float 32/64 位读取，16/24/32 位与 float32 写入
特征	log-mel、MFCC、LFCC、CMVN、统计池化与确定性基线嵌入
注册	多片段注册、质量加权聚合、保持片段身份的重命名、完整字段 JSON/NPZ 持久化
评测	精确阈值下的 EER、原始 minDCF、ROC/DET、bootstrap 工具
分数	余弦打分、归一化、Platt 与带权保序回归校准
交付	命令行、完整公开 API/CLI 快照、离线测试、多 Python 版本 CI

WAV → 单声道/采样率对齐 → log-mel → 统计池化嵌入
                                      ↓
                           注册库 + 验证音频
                                      ↓
                        余弦分数 → EER/minDCF → 报告

使用自己的数据

注册配置使用 JSON，音频路径相对于配置文件：

{"sample_rate":16000,"n_mels":40,"speakers":{"alice":["alice.wav"],"bob":["bob.wav"]}}

.venv/bin/voxledger enroll --config enroll.json --output book.npz
.venv/bin/voxledger verify --book book.npz --trials trials.tsv --scores scores.tsv
.venv/bin/voxledger eval --scores scores.tsv --output metrics.json
.venv/bin/voxledger report --metrics metrics.json --output-dir report
.venv/bin/voxledger identify --book book.npz --audio alice.wav --threshold 0.8

试验 TSV 必须包含 model、test、label；标签使用 target / nontarget，音频路径相对于试验文件。评估需要两类试验，阈值应使用独立开发集选择。CLI 注册时记录基线参数，验证时使用相同参数。

指标与边界

分数越大表示越可能属于同一说话人。EER 使用 FAR/FRR 交点插值；有限数据可能没有一个确定阈值恰好达到这个插值误差率。minDCF 返回未经归一化的检测代价，默认先验 p_target=0.01、漏检和误报代价均为 1。ROC/DET 返回原始概率及对应阈值。

默认嵌入器是 log-mel 统计基线，不能作为可靠的身份认证系统。线性重采样没有抗混叠滤波，真实数据宜预先使用经过验证的重采样器统一采样率。注册库不使用 pickle；仍应只处理已授权的音频数据。

更多内容：使用指南、API 参考、设计说明。MIT License。