dsh-listen

让 LM Agent 听懂声音

一个 DSH （DeepSeek Harness）的工具：传入音频，返回特征。

安装

dsh plugin --profile web add @vlln/dsh-listen

装完重启 dsh web；Plugins 页里填同一个包名。

前置：Node 22+、dsh 0.2.1-rc.5、本机有 ffmpeg/ffprobe。卸载：dsh plugin --profile web remove dsh-listen。

成绩（MMAU）

MMAU-test-mini 1000 题：74.60%。

图中其他行取自 MMAU 论文结果表的 Test-mini 列，是早期版本数据、音频模型端到端；我们跑的是当前 MMAU-v05.15.25 修订版、文本模型加工具。

分域：sound 72.97、speech 82.58、music 68.26。

工具接口与返回

listen({path:"x.wav", features:["levels","signal_image"], from:0, to:10})

参数	说明
path / attachment_id	来源，二选一；路径按会话工作目录解析
features	必填，无默认值：transcript events signal_image levels energy spectral_peaks band_energy chroma pitch pitch_frames onsets tempo
from / to	源文件秒数，默认 0 / EOF；单次区间 ≤60 秒
spectral_detail	transient/balanced/tonal → FFT 1024/2048/4096；只影响 signal_image
frequency_range_hz	图上可见频段，不改计算频带
channel_view	separate/power_mean；只影响出图
dsp_band_hz	[low, high]；band_energy 必填

返回给模型的内容：

{
  "status": "complete",
  "source": {"sha256": "…", "format": "wav", "sample_rate_hz": 48000, "channels": 2, "duration_seconds": 12.3},
  "coverage": {"from": 0, "to": 10},
  "requested_features": ["levels", "signal_image"],
  "available_features": ["levels", "signal_image"],
  "missing_features": [],
  "evidence": {
    "levels": {"status": "ready", "method": "signal-levels-v1", "units": {}, "parameters": {}, "channels": []},
    "signal_image": {"status": "ready", "method": "signal-image-v1", "parameters": {}}
  }
}

• 顶层 status：complete / partial / failed。
• evidence 每个键对应一个特征。值要么 status: "ready"，要么 failed / unavailable 加 reason 和错误码。
• 每块带 method、单位、实际生效参数。公共参数抽到 parameter_sets，块内用 parameters_ref 引用。
• signal_image 的图作为图片附件随结果返回，文本部分不含图。

设计

一个工具，可选拆成四个（audio_signal/audio_transcript/audio_events/audio_dsp）。把"听"拆成原子操作，让 Agent 自己组合。

flowchart LR
  t[transcript] --> c1["本地 MLX Whisper 或 ASR API"]
  e[events] --> c2["本地 LiteRT / YAMNet 分类"]
  i["signal_image<br/>spectral_detail / frequency_range_hz / channel_view"] --> c3["STFT 1024/2048/4096 + 128 mel<br/>功率 → dB，波形包络 → PNG"]
  l[levels] --> c4["逐声道 RMS / 峰值 / DC / 过载计数"]
  en[energy] --> c5["分 bin RMS → 分位数 / 动态范围 / 低能量区间"]
  sp[spectral_peaks] --> c6["单遍 STFT 功率谱 → 局部峰 top-12<br/>对数功率抛物线插值"]
  be["band_energy / dsp_band_hz"] --> c7["同一功率谱 → 频带功率占比"]
  ch[chroma] --> c8["同一功率谱 40–5000 Hz → 12 音级"]
  p["pitch / pitch_frames"] --> c9["FFT 自相关 1000–60 Hz<br/>分位数摘要 / 逐窗候选"]
  on["onsets / tempo"] --> c10["50 ms 平滑包络 → 起音新奇度<br/>起音候选 / BPM 候选"]

参数语义见设计基线，各特征边界见 DSP 证据。

配置

设置	默认	说明
scratch	$DSH_HOME/data/dsh-listen/scratch	解码与中间文件目录
mode	aggregate	aggregate 只给 listen；split 给四个拆分工具
localExecution	true	宿主文件系统解析出的是本进程可读路径；沙箱或远程文件系统设 false
asrEnabled / asrMode	false / api	可选转写：本地 MLX 或 OpenAI 兼容端点
eventsEnabled	false	可选声音标签：本地 LiteRT / YAMNet
allowExternalAudio	false	允许外发音频

限制

• 单次区间最多 60 秒；多声道高采样率时更短（总标量样本 23,040,000 上限）。
• 支持 1–8 声道；ASR 与事件分支混成单声道。
• 支持的格式取决于本机 ffmpeg。
• 不回答语义问题，不做音频生成、播放或编辑。

安全与数据

• 音频在本地解码；除配置 ASR API 并打开 allowExternalAudio，不外发。
• 证据进入主 Agent 上下文；主 Agent 用云模型时，证据也发到模型服务。
• 不读凭据本体；key 由宿主凭据服务或环境变量提供。
• 中间文件写入 scratch，调用结束清理。

插件管理

dsh plugin --profile web add @vlln/dsh-listen          # 装或升级
dsh plugin --profile web remove dsh-listen             # 卸载
dsh --profile web --dump-config | grep -A6 dsh-listen  # 看生效配置

包声明了 dsh.bundle.patch，add 会自动加进 profile 的 bundle 列表，不用手写 insert。旧版手工 insert 过的要先删掉。

兼容性

实测 dsh 0.2.1-rc.5 + Node 22 + macOS arm64（2026-11-06）。声明范围 engines.dsh: ^0.2.1-rc.5。dsh Desktop、Linux、Windows 和 0.2.0 及更早版本未测。

开发

npm run gate:feature   # 静态检查 + 单元/覆盖率
npm run gate           # 静态检查 + 基础设施测试

许可

代码 MIT。可选运行时、权重、数据各按自己的许可。