earshot - 让编码智能体「听见」声音并写出声音的本地工具

earshot 是一个面向 AI 编码智能体的声音工具。按项目自述，如今的编码智能体已经能写出渲染影片、产品演示或游戏的代码，却「听不见」自己做出来的东西：分不清一次按键是高级还是廉价，察觉不到打击声比剪辑点晚了 80 毫秒，也听不出音乐在错误的位置推向高潮。earshot 要解决的就是这个缺口——把声音变成智能体可以推理的证据，同时让智能体能够用代码自己造声音、再靠「听」来改进。它适合把音频质量纳入自动化流程的开发者、做动效与产品演示的团队，以及希望给编码智能体补上听觉能力的工具作者。

维护者与状态

项目由 Leonxlnx 维护，仓库创建于 2026-10-15，最后一次提交在 2026-10-18。最新正式版本为 v0.2.0，发布于 2026-10-16。截至 2026-10-22，仓库星标数为 2054。需要说明的是，素材中多处提到「0.3 新增」的内容，而事实表中的最新 release 仍是 v0.2.0，因此下文凡涉及版本归属的能力描述，均以项目自述原文为准，读者应以仓库实际发布状态为准。

主要能力

据项目说明，earshot 以命令行工具、Python API 和 MCP 服务器三种形态提供同一套能力，全部在本地 CPU 上运行。README 中列出的命令覆盖了从「听懂」到「造声」的完整链路：

• 描述与匹配：describe 给出一个文件听起来像什么，包括带 z 分数的校准标签、最接近的备选解读、AudioSet 标签与客观测量；match 判断一段描述与音频的契合程度，给出余弦相似度、在词表中的 z 分数，以及 strong / plausible / weak / no match 的结论；rank 则按描述对多个候选文件排序。
• 定位与比较：find 在长录音中找出最符合描述的时间片段，以起止秒数表示；compare 与 ab 用于找最近的参考录音、判断典型性，并用文字说明两段声音或两个片段的差异。
• 真实性判断：realness 区分真实录音、专业制作与代码合成，并给出证据和逐窗口分数。
• 时间线与图卡：timeline 输出「聆听转录」，包含事件（时间、电平、标签）、段落、响度、节拍网格，以及声音与画面剪辑点、提示帧的同步情况；sheet 生成一张带标注的 PNG，含视频帧、段落、带标签的事件、频谱图、波形、响度与同步标记，供能读图的智能体使用。
• 评分与测量：critique 参照 7 部专业发布影片构成的画像，给发布视频打分并给出带时间戳的修改建议；profile 允许用户用自己欣赏的影片自建参考画像；measure 只做客观测量、不加载模型，输出 LUFS、真峰值、LRA、包络、频谱、速度与调性。
• 合成与拟合：forge 用代码写出一段声音（配方由模态共振、接触激励、滤波噪声、计算出的房间与麦克风构成，内部不含录音素材），再由一个基于 earshot 的评审器打分，通过进化式搜索保留最优并变异，智能体读评审意见、看频谱图、改写配方后重跑；fit 把一段录音翻译成可再渲染、可调参的 forge 配方模块。
• 音效库与套件：据 README 的 0.3 说明，sfx 提供 201 个以代码形式存储的音效，可按 id 在数秒内渲染，无需模型与网络，并能把 whoosh、hit、click 或音符对准画面中的某一时刻；kit 为整部影片渲染一套音效，并测量起始、峰值与结束点。
• 其他：gallery 把 forge 产物汇成一个静态 HTML 试听页；llm 提供可选的音频大模型点评（Gemini），仅在用户自带密钥并明确同意上传时启用；mcp 把同一套工具以 MCP 服务器形式暴露给 Claude Code 等智能体；doctor 检查安装、模型、数据文件与 CPU 设置。

交互设计上，每条命令先打印一段通俗语言摘要，--json 输出完整结果，--out 可保存为文件；错误以单行形式写到 stderr 并以退出码 1 结束。

使用入口

仓库地址为 Leonxlnx/earshot。据项目说明，安装后即可通过命令行调用，例如描述一个音频文件：

earshot describe enter.ogg

也可以按描述匹配或检索片段：

earshot match key.ogg "a deep thocky mechanical keyboard press" --alts "a clicky blue switch keyboard" "a mouse click"
earshot find keys.ogg "a single mechanical key press" --top 4

合成音效时，用配方加参考集的方式运行：

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

在 Python 中可从 earshot import api 调用，或使用 from earshot.forge import forge。README 特别提示：每次 CLI 调用都是新进程，回答前需要加载模型，约 20 至 40 秒（measure、sfx、kit 不加载模型）；如果调用次数较多，应改用 MCP 服务器（模型常驻）或写一个 Python 脚本。

许可与限制

项目采用 MIT 许可证。据项目说明，已知限制与边界包括：CLI 单次调用存在上述模型加载开销；llm 子命令会把音频上传给第三方服务，必须由用户自备密钥并明确同意，默认不启用；forge 的参考集按来源划分为搜索可用的 forge 侧与仅供固定基准评测使用的 bench 侧，以避免评测泄漏；合成配方内部不含录音素材，产物由物理合成与效果处理生成。素材未给出具体的硬件门槛，仅说明在本地 CPU 上运行，实际资源需求应以仓库文档为准。