resona

resona 是一个面向声学信号的自监督表示学习工具包。它把语音、环境声与声场（多通道） 三类信号统一到同一套特征前端与预训练接口下，支持掩码声学建模（MAM）与对比预训练。

核心信号处理只依赖 numpy，PyTorch 是可选依赖——你可以在没有 GPU、甚至没装深度学习框架的 机器上直接做特征抽取与数据检查。

特点

• 统一前端：一个 UnifiedFrontend 按信号域自动选参，输出规整的 (planes, n_mels, frames) 张量。
• 声场空间线索：多通道信号额外拼接 ILD / IPD 等空间平面，并做频带池化对齐到对数梅尔维度。
• 两条预训练路线：MAE 风格的掩码重建，以及 InfoNCE 对比学习，共享同一个 Transformer 编码器。
• 可对拍的参考实现：损失与掩码都有纯 numpy 版本作为「真值」，方便单测逐值校验。
• 离线优先 / 依赖精简：WAV 读写只用标准库，不强依赖 soundfile / scipy。
• 完整开发基建：ruff + mypy + pytest，CI 多版本矩阵，pre-commit 钩子。

安装

pip install resona            # 纯 numpy 核心
pip install "resona[torch]"   # 额外启用神经网络编码器与预训练

快速上手

import numpy as np
from resona import Domain, FeatureConfig, UnifiedFrontend

cfg = FeatureConfig.for_domain(Domain.SPEECH)
frontend = UnifiedFrontend(cfg, domain=Domain.SPEECH)
feat = frontend(np.random.randn(16000))
print(feat.shape)  # (1, 64, T)

声场信号（多通道）会自动拼上空间平面：

field = UnifiedFrontend(FeatureConfig.for_domain(Domain.FIELD), domain=Domain.FIELD)
print(field(np.random.randn(4, 24000)).shape)  # (7, 96, T)

命令行：

resona info                                   # 环境与可用模型
resona features input.wav feat.npy            # 抽取特征
resona mask-demo --strategy timefreq --ratio 0.6
resona pretrain --objective mam --steps 5     # 需要 torch

文档

• 使用指南
• 架构
• 设计笔记
• API 参考
• 示例

状态

早期阶段（0.x），公开接口可能仍有调整。欢迎通过 issue 讨论。

许可

MIT © Lucy Liang