soundscape-lm

环境声音理解工具包：把一段音频转成「这是什么场景 + 里面有哪些声音事件 + 一句自然语言描述」，并支持音频-文本检索。

面向声学场景与事件理解的早期研究，强调 可复现 与 离线优先：核心链路只依赖 numpy / scipy，深度模型与大语言模型都是可选后端。

---

能做什么

• 声学场景分类（ASC）：基于 clip 级嵌入的最近原型分类器，输出场景标签与概率。
• 声音事件检测（SED）：帧级概率 → 中值滤波 → 阈值 → (onset, offset, label) 事件。
• 评估指标：分段指标（P/R/F、错误率 S/D/I）、事件指标（带时间容差的最优二分匹配）、 跨模态检索指标（R@1/5/10、mAP@10）。
• 音频-文本检索：把音频与文本嵌入放入同一空间，用余弦相似度排序。
• LLM 场景描述：把场景与事件结果渲染成中/英文描述；离线可用，也可接入 OpenAI 兼容接口。

安装

pip install soundscape-lm            # 核心（numpy + scipy）
pip install "soundscape-lm[llm]"     # 额外：requests，用于接入大语言模型
pip install "soundscape-lm[audio]"   # 额外：soundfile，用于读写音频文件

从源码安装：

git clone https://github.com/isla-brooks/soundscape-lm.git
cd soundscape-lm
pip install -e ".[dev]"

快速上手

import numpy as np
from soundscape.features import FeatureConfig, logmel_spectrogram
from soundscape.sed import LinearFrameModel, SoundEventDetector
from soundscape.sed.labels import DESED_EVENTS
from soundscape.llm import render_description

cfg = FeatureConfig()                       # 32 kHz, 64 梅尔频带
signal = np.random.default_rng(0).standard_normal(cfg.sample_rate * 4) * 0.05

feats = logmel_spectrogram(signal, cfg)     # (帧数, 64)
model = LinearFrameModel.random(cfg.n_mels, len(DESED_EVENTS))
events = SoundEventDetector(model, DESED_EVENTS, cfg).detect(signal)

print(render_description("street_traffic", events, language="zh"))

命令行：

soundscape scenes                # 列出内置场景标签
soundscape demo --seconds 4      # 在合成音频上跑通完整流程
soundscape evaluate --reference ref.txt --estimated est.txt --mode event

文档

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

许可证

MIT © Han Xiaoyu