earshot：给编码 Agent 的耳朵

这个 Agent 能做什么，适合哪些场景？

earshot 是一个让 AI 编码 Agent「听见」声音的开源工具：它把音频文件转化为文字描述、描述匹配度、最佳片段定位、真假录音判别、逐秒听感时间轴和对照专业发布片的评分卡。它以 CLI、Python API 和 MCP 服务器三种形态提供同一套能力，完全在本地 CPU 上运行，不需要 GPU。内含 forge 组件让 Agent 用代码（物理合成配方）直接造声音并用评分器迭代改进，fit 组件能把一段录音反译成可变参的代码配方，sfx/kit 则提供 252 个纯代码渲染的音效库和电影音效套件。模型（CLAP 和 AudioSet 标注器）首次使用时下载后全部离线运行，仓库本身不含任何音频文件。

earshot 读取音频/视频文件后运行两条开源模型（CLAP 文本-音频嵌入和 AST AudioSet 标注器）加一组无模型测量。核心命令包括：describe（生成带 z 分校准标签和测量的描述）、match / rank（判断描述与文件的匹配度并排序候选文件）、find（在长录音中定位最佳片段并输出裁剪点）、realness（判断真实录音还是代码合成）、timeline 和 sheet（逐秒事件时间轴与带标注的 PNG 图）、critique（对照 7 部专业发布片档案的评分卡并给出带时间戳的修复建议）。forge 用物理合成配方（模态谐振器、滤波噪声、房间模拟等）渲染候选声音，由基于 earshot 的 critic 评分并用进化搜索迭代；fit 通过分析-综合把录音拟合成含 render() 的配方模块，支持变体与 morph；sfx render / kit render 按秒级速度渲染 252 个音效库成员并审计点击、削波等问题。全部能力通过 earshot mcp 作为 MCP 服务器暴露给 Claude Code 等 Agent。

1. 用 Claude Code 制作产品发布短片的开发者：让 Agent 听完音轨后用 critique 得到对照专业发布片的评分和修复清单
2. 给代码生成的影片配声音的团队：用 kit render 的 launch 预设把 252 个代码音效按音乐床电平和切点偏移量自动排布
3. 需要筛选大量音频素材的 Agent 流程：用 rank 按一句描述给候选文件排序，用 find 找到长录音里的关键瞬间
4. 音效设计师与 Agent 协作：用 forge 写物理合成配方，靠 critic 的文字反馈和频谱对比图迭代出接近真实录音的声音
5. 需要把现有录音变成可变参代码的用户：用 fit 把一段点击声转成配方模块，再调整音高、阻尼、衰减生成变体

如何安装或部署这个 Agent？

前置条件：Python 3.10+，PATH 上有 ffmpeg/ffprobe；仅用 CPU，无 GPU 需求。

git clone https://github.com/Leonxlnx/earshot && cd earshot
python -m venv .venv
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu   # Windows: .venv/Scripts/python
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
.venv/bin/python -m earshot doctor --load

首次使用模型时会在仓库内的 .cache/hf（或 EARSHOT_HOME）下载两个开源模型（共约 1.1 GB）：CLAP laion/larger_clap_general 和 AST MIT/ast-finetuned-audioset-10-10-0.4593，之后完全离线。可用 earshot doctor --fetch 提前下载。

作为 MCP 服务器接入 Claude Code：

claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp

如何使用这个 Agent？

CLI 用法（每个命令先输出自然语言摘要，--json 给出完整结果）：

earshot describe enter.ogg
eatshot match key.ogg "a deep thocky mechanical keyboard press" --alts "a mouse click"
earshot find keys.ogg "a single mechanical key press" --top 4
eatshot critique film.mp4
eatshot forge whoosh --refset whoosh_fast --budget 96 --dir made/whoosh
eatshot fit click.wav -o made/click_fit.py --report
eatshot sfx render whoosh_fast/crisp -o w.wav --dur 0.8 --apex 0.32
eatshot kit init --preset launch -o audio/kit.json && earshot kit render audio/kit.json --out audio/kit

Python API：

import earshot
earshot.describe('whoosh.wav')
earshot.find('typing.ogg', 'a single isolated key press')
from earshot import api

注意：每次 CLI 调用都加载模型（约 20-40 秒），多次调用建议用 MCP 服务器（模型常驻）或 from earshot import api 写脚本。可选的 llm_critique 需自备 GEMINI_API_KEY 并显式同意上传。

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题