resona

自监督音频表示学习工具包 —— 在同一个 Transformer 骨干上统一「掩码频谱建模」与 「对比 / 自举预训练」，为语音、音乐、环境声学习通用表示，作为声音大模型的音频基座。

⚠️ 早期基础工作，接口仍可能变化。欢迎试用与反馈。

特性

• 🎯 三种自监督方法，一个骨干
  • masked —— 掩码频谱建模（MAE 风格，只编码可见 patch）
  • contrastive —— InfoNCE 对比学习，可学习温度
  • bootstrap —— BYOL 风格自举，EMA 目标网络，无需负样本
• 🔊 自带前端：纯 PyTorch 实现的 log-mel 频谱，不依赖 torchaudio
• 🧩 统一表示接口：无论用哪种目标预训练，都通过 method.encode() 取表示
• 🧪 评估协议：内置线性探针与 kNN
• 🛠️ 完整工程：CI、ruff、mypy、pre-commit、类型注解与测试覆盖

安装

git clone https://github.com/LX588387/resona.git
cd resona
pip install -e .              # 或 pip install -e ".[audio,dev]"

快速开始

import torch
from resona import AudioTransformerEncoder, EncoderConfig, LogMelSpectrogram, build_method

frontend = LogMelSpectrogram()
encoder = AudioTransformerEncoder(EncoderConfig())
method = build_method("masked", encoder)          # 或 "contrastive" / "bootstrap"

wav = torch.randn(8, 16_000 * 2)                  # 8 段 2 秒音频
spec = frontend(wav)                              # (8, 80, frames)
spec = spec[..., : (spec.shape[-1] // 16) * 16]   # 对齐到 patch 宽度
loss = method(spec).loss
loss.backward()

emb = method.encode(spec)                         # (8, embed_dim) clip 级表示

命令行：

resona info                              # 版本、可用方法与默认配置
resona encode --demo --output emb.pt     # 编码一段合成音频
resona pretrain --data ./audio --method contrastive --steps 1000

设计一览

波形 → LogMelSpectrogram → PatchEmbed(+位置编码) → Transformer 编码器 ─┬─ 掩码重建
                                                                      ├─ 对比 (InfoNCE)
                                                                      └─ 自举 (BYOL)

三种方法共享同一个编码器骨干，只在「拿到 patch token 后做什么」上分叉；推理阶段统一 经由 encode() 输出表示，使下游与预训练目标解耦。详见 docs/architecture.md。

文档

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

许可证

MIT © Dai Yanan