earshot

earshot 核心定位是给编程智能体装上耳朵。当前AI编程智能体可以渲染影片、游戏、演示画面，但无法感知音频细节，分不清按键音色、听不出音效同步偏差。

earshot 将音频转换成编程智能体能够读懂、推理的结构化证据，全程CPU本地运行，提供CLI、Python API、MCP服务器三种接入方式，可直接对接Claude Code等AI编程智能体。

核心能力与命令

CLI单次调用会重新加载模型（耗时20–40秒），高频调用建议使用MCP服务长驻加载模型，或直接调用Python API。

Forge：代码生成音效

earshot forge 是物理建模音效合成器，不靠预存音频采样，依靠模态谐振、噪声、房间声学、麦克风模拟等DSP组件渲染声音。

工作流程：编程智能体编写音效配方，工具批量渲染候选样本，通过多维度评估（文本匹配度、真实感、频谱包络、失真、瞬态/衰减特征），使用进化搜索迭代调参；编程智能体读取critique报告，修改配方，反复迭代直到音效达标。

内置34类运动音效配方：呼啸、撞击、低频Drop、UI点击、按键、提示音、故障音效等，v2版本改进了声音衰减、频谱平衡，盲测中人很难区分合成音效与真实录音。

earshot forge keypress --refs path/to/real/keypresses/ --budget 144 --variants 4 --dir made/keypress

Fit：录音反向转为合成配方

earshot fit 对真实录音做逆向分析，拟合分层声学模型，输出可编辑的Python合成配方。配方存储声学结构而非音频采样，可以调整时长、音高、阻尼、亮度，还能在两段声音之间做变形插值。
在12组测试录音实验中，原始录音与代码渲染结果的中位CLAP余弦相似度0.945，盲听测试听众无法分辨。

SFX音效库与Kit混音

内置183个forge v2成品音效，支持通过代码实时渲染，无模型、无需联网。支持自定义音效套件（kit），为项目内各类交互事件绑定音效，自动做音频审计，检测削波、伪影、异常振铃等问题。可精确控制峰值位置、音高、时长，误差控制在毫秒级。

部署与依赖

• 环境：Python3.10+，系统需要安装ffmpeg/ffprobe；仅CPU运行，不需要GPU
• 模型：CLAP、AudioSet-AST两个开源模型，合计约1.1GB，一次性下载本地缓存，支持完全离线模式
• 安装示例：

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
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
.venv/bin/python -m earshot doctor --load

• MCP接入Claude Code示例：

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

性能指标

• 音频事件检出：60秒影片混音中音效事件检出率93%，低音量事件89%
• 真实/合成分类：保留测试集ROC-AUC 0.92
• 文本-音频匹配：保留测试集内“强”裁决98%为正确声音类别

已知局限

earshot适合评估响度、时序、音画同步、声音类别；不擅长判断音乐情绪、艺术品味、版权许可。高复杂度混音环境下，声音标签识别可靠性下降；模型存在被优化“欺骗”的可能，不能单靠模型分数，必须结合客观声学测量、频谱图与人工盲测综合评估。