Earshot v0.3 发布解读：给 agent 装耳朵，难的不是听懂，是知道自己听错

引言：agent 能拍片了，但它听不见

过去一年，编码 agent 的能力边界扩得很快。它能写出渲染一段视频的代码、能搭一个产品演示页、能生成一个能跑的游戏原型。

但它听不见自己做出来的东西。

它分不出一次「高级的机械键盘按键声」和「廉价塑料咔哒声」的差别。它注意不到某个撞击声比画面剪辑点晚了 80 毫秒。它听不出音乐在第 12 秒该起的地方没起来。

这不是 agent 笨，是它没有耳朵。它一直在盲做。

Earshot 就是冲这件事来的。它的自我定位只有一句话：Ears for coding agents（给编码 agent 的耳朵）。

做的事也很清楚：把声音变成 agent 能推理的证据。一个文件听起来像什么（用文字描述）、有多符合某个描述（打分）、一段长录音里最好的片段在哪、这段声音是实录还是代码合成的、整部影片的逐秒听觉转录、一张带标注的可视化图，以及一份对标专业发布影片的评分卡。

它 10 月 15 日上线，四天后（10 月 19 日）发到 v0.3，GitHub 上 899 颗星、52 个 fork、0 个未解决 issue。MIT 许可，纯 CPU 本地跑，不用显卡。

而这一篇要讲的，不是它有多强，是它作者自己承认的那些地方。

因为 Earshot 的 README 里有一句话，我在这两年看过的所有发布材料里没见过第二次：

作者把代码生成的音效和真实录音放在一起盲听，15 次里认对 8 次。「和抛硬币一样。」

一个做声音评测工具的人，公开说自己听不出来。

---

一、产品定位：它到底是什么，不是什么

它是什么

一句话：一个让编码 agent「能听声音」的本地工具链，包含分析、评测和合成三段。

分三块：

块	做什么	依赖
听（describe / match / find / compare / realness / timeline / sheet / critique）	把声音转成文字、分数、时间轴、图片	两个开源音频模型
造（forge / fit / sfx / kit）	用代码合成音效，并自己听、自己改	纯 DSP 计算，v0.3 的音效库不用模型
接（CLI / Python API / MCP server）	三种方式让 agent 调用	—

三条路都能用：命令行、Python 脚本、MCP 服务器（给 Claude Code 这类客户端用）。

它不是什么

四件事容易误会。

不是音频生成模型。 它不跑扩散模型，不用神经网络合成声音。forge 造声音靠的是物理合成——模态谐振器、接触激励、滤波噪声、算出来的房间和麦克风模型。所有声音是算出来的，不是学出来的。

这一点很重要，因为它决定了成本结构：造一个音效不需要 GPU，不需要网络，是秒级的算术。

不是语音识别或 TTS。 它明确说自己判不了「speech content」。转写人声、读文本这些事不归它管。

不是给人类用的播放器。 它的输出是给 agent 读的：--json 给结构化结果，sheet 给一张 agent 能看的 PNG，gallery 生成一个静态 HTML 页面（这个倒是给人看的，但是副产品）。

不是「另一个 earshot」。 GitHub 上还有个 hec-ovi/earshot-mcp，版本号恰好也是 0.3.0，做的是「让多个 agent 互相发消息」。名字撞了，东西完全不同。这篇讲的是 Leonxlnx/earshot。

项目的规模与阶段

这个信息决定了后面所有判断的权重。

指标	数值（2026-10-19 抓取）
GitHub star	899
fork	52
创建时间	2026-10-15
最后推送	2026-10-18
未解决 issue	0
许可	MIT

四天 899 星，0 个 issue。 这个组合说明两件事：一是关注度确实起来了，二是还没有经受过真实用户的压力测试。0 issue 不代表没有 bug，只代表还没有人认真用。

作者 Leon Lin（GitHub 账号 Leonxlnx，X 上叫 @LexnLin，慕尼黑）此前做过一个叫 Taste Skill 的开源项目，是帮 AI 生成的界面提升设计质量的。Earshot 是同一个思路换了个感官：给 agent 一套能自我检查的工具，让它能改。

1.4 要花多少钱

代码免费，模型免费，运行免费。 MIT 许可，两个依赖模型分别是 Apache-2.0 和 BSD-3-Clause。

成本在三个地方，都不是钱：

第一，模型下载约 1.1GB，但两个来源给的数字不一样。 README 写「首次使用下载两个开源模型（约 1.1GB）」，RuntimeWire 的报道写「约 1.4GB」。这个差异可能是 README 只算权重、报道算了 tokenizer 和配置，也可能其中一个算错了。抓取时没有核实到确切值，按 1.1–1.4GB 之间准备空间是稳妥的。

下载之后可以完全离线：设 EARSHOT_OFFLINE=1、HF_HUB_OFFLINE=1 或 TRANSFORMERS_OFFLINE=1 任一个，它就不再联网。如果缓存里缺模型，会报错并指出是哪个文件夹，不会偷偷重新下载。

第二，CLI 每次调用要冷启动 20–40 秒。 这是最容易被低估的成本。

原因很直接：每次敲 earshot describe 都是一个新进程，要把两个模型重新加载进内存。measure、sfx、kit 三个命令不加载模型，所以是秒级的。

官方的建议是：超过几次调用，就用 MCP 服务器（模型常驻）或者写一个 Python 脚本（from earshot import api，一次加载多次调用）。

这条建议不是优化项，是能不能用的分界线。 用 CLI 连续跑十次分析，光等待就五六分钟；用 Python 循环，同样的活十几秒。

第三，CPU 时间。 官方给了一个参考：60–90 秒的影片，在笔记本 CPU 上分析约 1.5 分钟。

默认线程数是 min(4, 核数/2)，可以用 EARSHOT_THREADS 调。精度默认 bf16，但只在支持原生 bf16 的 CPU（AVX512-BF16 / AMX）上生效，其他一律 fp32。

没有的东西：没有付费版，没有云服务，没有 API key，没有用量限制，没有商业支持。这是一个个人项目，不是一家公司在卖东西。

---

二、核心能力拆解：它提供了哪些关键能力

README 里列了 17 个命令。按「回答什么问题」分组，比按字母排列有用得多。

能力一：这是什么声音（describe / match / rank）

describe FILE 输出的是带校准的文字描述：

0.56 s short transient (attack 3 ms, decays in 190 ms).
Sounds most like: a single mechanical keyboard key press (z +5.4),
a soft key release click (z +3.6) ... [clear reading].
peak -0.1 dBFS, brightness 1.5 kHz ...

注意那个 z +5.4。这是 z-score，表示「这个描述比平均水平高出多少个标准差」。它不是一个 0 到 1 的相关性分数——这是理解整个工具的关键。z 值配合一个校准过的词汇表，才能说「有多像」。

而且它会给出备选解读（a soft key release click (z +3.6)）。这一点很重要：声音的描述天然是多义的，一个按键声可能像「键按下」也可能像「键回弹」。只给一个答案的工具会骗人。

match FILE QUERY --alts ... 给的是判断：strong / plausible / weak / no match，附带「如果放进 322 个描述里，它能排第几」。

rank QUERY PATHS... 是批量版：给一堆候选文件，按符合程度排序。官方举的用例是「从十个下载里挑最像的那个」。

能力二：在长录音里找到那一下（find）

find FILE QUERY 在长录音里定位最佳片段，输出是起止秒数：

0:03.94-0:04.19 (0.24 s stroke, z +4.1 strong)

这在实操里比听起来有用。比如你有一份 40 分钟的现场录音，要找一段干净的单次按键声做音效素材——手工听要半小时，它几秒钟给出三个候选。

能力三：判断真假（realness）

这是最有争议、也最有意思的一个。

realness FILE 判断一段声音是真实录音（或专业制作）还是代码合成，给出每段的分数和证据。

为什么需要它？因为当 agent 自己造音效时，「听起来是不是假的」是核心质量指标。但正如后面要讲的，这个判断本身很脆弱。

能力四：看一整部片子的声音（timeline / sheet）

timeline FILE --video V 输出「听觉转录」：事件（时间、电平、标签）、段落划分、响度曲线、节拍网格、音画同步点。

sheet FILE -o out.png 把上面这些画成一张图：视频帧、段落、带标签的事件、频谱图、波形、响度、同步标记。给「能读图的 agent」用的——这是个很聪明的设计，多模态 agent 看一张标注图，比读一堆 JSON 更快抓住问题。

能力五：给发布影片打分（critique / profile）

critique film.mp4 拿一部片子对标一个「7 部专业发布影片」的档案，输出：

VERDICT: close - 21 of 23 scored metrics in range
FIX FIRST: 1. [major] nothing reaches body level until 0:01.01 ...

关键是它给的是「带时间戳的修改建议」，不是一句「还不错」。这让 agent 有下一步动作可做。

profile REFS... -o p.json 可以拿你自己欣赏的片子建一套标准。这个设计避免了对官方那 7 部片的过拟合——虽然大多数人不会去建。

能力六：用代码造声音（forge / fit）

forge 是最有野心的一块。

流程是：agent 写一个「配方」（物理合成的代码），forge 渲染出一批候选，一个「听众」（critic）给每个打分——描述匹配度、真实感、与参考录音的接近程度、无模型的物理指标（1/3 倍频程音色平衡、频谱包络、杂音检测、打磨度）。然后 agent 读批评意见（「像开瓶声混玻璃叮」「衰减比参考长 2.4」「尾巴不平滑」），看频谱图，改配方，再跑一遍。

这是一个闭环。 不是「一次生成」，是「生成、听、改、再生成」。

v0.2 把它扩到 34 个 motion-design 类别（whoosh、swish、riser、impact、点击、悬停音、通知音等），每类 4–6 个变体，其中 16 类模仿了专业发布影片里设计过的音效。

fit 是反方向：把一段录音翻译成代码。用分析合成的方式，拟合一个小模型（模态振铃、跟踪的分音、时变噪声手势，或它们的混合），让渲染结果逼近原录音，最后写成一段可执行的配方模块。

产物不是采样，是结构。所以你可以让它出新的 take、改变体（大小、阻尼、音高、亮度、衰减）、甚至在两段录音之间做形变。

能力七：201 个音效的代码库（sfx / kit，v0.3 新增）

这是 v0.3 的主题，也是这次更新的全部重点。

一个「音效库」，但里面存的不是音频文件，是配方。201 个音效全部以代码形式存在，按 id 秒级渲染，不用模型、不用网络。

构成：

• 183 个 forge v2 的成品（34 个类别）
• 3 个调过音的卡林巴音色（来自发布影片）
• 15 个从 CC0 录音「拟合」出来的声音（点击、嘀嗒、pop、触摸、按键、响指、铃声、whoosh）

用法：

earshot sfx list --kind whoosh
earshot sfx render whoosh_fast/crisp -o w.wav --dur 0.8 --apex 0.32
earshot sfx check w.wav
earshot kit init --preset calm -o audio/kit.json
earshot kit render audio/kit.json --out audio/kit

三个旋钮值得单独说，因为它们是精确的：

• dur：长度精确到采样点
• apex：让 whoosh 的峰值落在目标时刻的 5 毫秒内（实测 2.5 毫秒内）
• pitch：接受音名或赫兹，直接改配方自己的音高参数（pluck E5、bell G5、sub drop G1 实测 0 音分偏差）

这解决的是「音画同步」这个具体问题：你要一个 whoosh 在 0.32 秒达到峰值、总长 0.8 秒，它就是 0.32 和 0.8，不用事后去拉伸和修剪。

sfx check 是一个纯测量的审计：检查咔哒声、被切断的尾巴、削波、直流偏移、梳状振铃、上升的音高滑音（超过 4 个半音的「合成鞭子」）、命中音的堆叠攻击。201 个里有 185 个通过，三个预设都不用那 16 个不合格的。

kit 是「一部片子的声音套装」：每个角色（嘀嗒、命中、whoosh、按键、铃声、文字）指定一个库里的声音，渲染出确定性的、带缓存的 take，并写一份 kit.lock.json 记录每个 take 的实测起点、峰值、终点。不合格的 take 会自动换种子重掷。

能力与场景对应

能力	回答什么问题	谁最需要	成熟度
describe / match	这是什么声音、像不像我要的	找素材、配 UI 音	可用（125 段实测有数）
find	长录音里哪一段是我要的	素材挖掘	可用
realness	这是实录还是合成的	质检、防假	可用但脆弱（见第六章）
timeline / sheet	整部片子的声音结构	视频/游戏后期	可用（93% 检出率）
critique	我的片子比专业片差在哪	发布片、产品演示	可用但需谨慎（非盲测）
forge	造一个声音并改到满意	音效设计	可用但需人把关
fit	把录音变成可变的代码	素材再创作	可用（12 段实测）
sfx / kit	给一部片子批量配音效	短片、游戏、Demo	可用（185/201 过审计）

---

三、典型应用场景：谁在什么条件下用它解决什么问题

3.1 场景地图

按使用者拆，三群人：

• 用 Claude Code / Codex 做视频或游戏的独立开发者：片子能生成，声音靠猜
• 小团队的音效/后期：没有专职声音设计师，需要工具兜底
• Agent 工具链的研究者：想看「给 agent 装感官」这条路能走多远

按用途拆，主场是「已有素材的质量判断」和「短片音效的快速补齐」，不是「专业音频制作」。

按形态拆：CLI 快试、Python 脚本跑量、MCP 接进 agent 的工作流。

哪些是主场，哪些只是「也能做」：给自己的 AI 生成视频配音效、从海量素材里挑音、判断一段声音真假，是主场。做音乐、做专业混音、配音，不是。

3.2 场景一：给 AI 生成的短片配音效

谁在用：独立开发者、内容创作者，用 agent 生成了一段 30 秒的产品演示或游戏预告。

触发条件：画面有了，声音是空的，或者只配了一段免费音乐。要发出去，得加音效：转场 whoosh、UI 点击、logo 落板的 impact。

痛点：三条路都不顺。自己找免费素材，要听几百个才能挑出五个，而且风格不统一。买商业库，一套几百美元，还不一定对味。找个音效师，一个短片几百到几千。

产品介入点：sfx + kit。选一个预设（calm / crisp / minimal），每个角色指定一个库里的声音，一次渲染出全套。

前置依赖：装 Python 环境、ffmpeg、下模型（1.1GB+）。第一次配环境大概半小时。但 sfx 和 kit 不加载模型——配好之后这两个命令是秒级的，很轻。

产出与收益：一套能用的短片音效，风格统一（因为来自同一个库），时间点精确（apex 在 2.5 毫秒内），而且全部是代码算出来的，没有版权风险。

边界与风险：185/201 通过审计，意味着有 16 个是已知有瑕疵的（预设避开了）。但「通过测量审计」不等于「好听」——作者自己说得很清楚：它能判断「像不像那类声音」，判不了「好不好意思」。用它出初版可以，直接上线要人听一遍。

3.3 场景二：判断一段声音是真录的还是 AI 生成的

谁在用：内容审核、素材采购、以及对「AI 味」敏感的品牌方。

触发条件：拿到一段音频，怀疑是合成的；或者反过来，自己生成的音效要判断够不够真。

痛点：人耳越来越难分辨。而且判断「像不像真的」这件事，没有客观标准——你觉得假，客户觉得好。

产品介入点：realness。它给出每段的分数和一个 firm verdict，加上证据。

前置依赖：无，一条命令。

产出与收益：一个可复核的判断。对于批量素材筛选，这是效率工具。

边界与风险：这是它最脆弱的能力。 官方数据是 ROC-AUC 0.92，firm verdict 会把 6.7% 的真实录音判成合成、5.5% 的合成判成真实，还有 20% 的声音被判为「不确定」。

更麻烦的是作者自己写的一句话：「realness 模型很容易被骗——一个模态谐振器加一个房间加一层底噪，读起来就是『真实』。」

也就是说，这段代码生成的假声音，因为结构上模仿了真实录音的物理特征，能骗过判断器。拿它当证据之前，要知道这一点。

3.4 场景三：给 agent 装一套自我检查的闭环

谁在用：在搭 agent 工作流的开发者。

触发条件：agent 能生成声音（或用 earshot forge 造），但不知道好不好，需要能自我迭代。

痛点：没有反馈信号，agent 只能一次成型。而「一次成型」在创意工作里基本等于「差」。

产品介入点：forge 的 critic 回路 + MCP 接入。agent 写配方 → 渲染 → 读批评 → 改 → 再渲染。

前置依赖：要是 MCP 客户端（Claude Code 等），要配 .mcp.json，要接受模型常驻占内存。

产出与收益：把「生成」变成「迭代」。官方给的数据是 forge v2 相比 v1，同类变体之间的相似度从 0.89–0.97 降到 0.71–0.85（不再是近似复制品），衰减过快的尾巴也修好了（click 的 t40 从 0.56 倍基准中位数升到 1.44 倍）。

边界与风险：这是 Goodhart 定律的现场。 搜索的目标是 earshot 自己的模型给出的分数，所以它能优化到「让模型满意」，而不一定是「让声音变好」。

官方给的解法是四条并用：看无模型的物理测量、看频谱图对比、做鲁棒重渲染、最后人来盲听。这四条里，最后一条不可省略——原因第六章会讲到。

3.5 场景成熟度分级

分级	具体做法	说明
开箱即用	measure / sfx / kit	不用下模型，装好就能跑，秒级
开箱即用	describe / match / find	首次跑要下 1.1GB 模型，之后每条命令 20–40 秒
需要一点配置	Python 脚本调 earshot.api	一次加载多次调用，跑量必须这么干
需要一点配置	MCP 接进 Claude Code	写 .mcp.json，模型常驻
需要一点配置	forge 造声音	要准备参考录音（--refs），要理解 critic 的输出
仅概念验证	critique 对标专业片	7 部参考片是固定档案，且规则改过、非盲测
仅概念验证	realness 当证据用	作者自曝容易被骗，20% 判为不确定
不建议使用	做音乐、做专业混音	不是这个工具的范围
不建议使用	语音转写、配音	官方明确说判不了 speech content

3.6 不适用或需谨慎的场景

第一，任何需要「最终判断」的场合。 它能告诉你「这像不像一类声音」「这像不像合成的」，但它自己说判不了品味、情感、来源、许可。最后的判断必须是人。

第二，14kHz 以上的内容。 官方明说两个模型听不到 14kHz 以上。做高频细节（镲片、齿音、空气感）的场景，它给不了意见。

第三，拥挤混音里的具体事件。 单一声源是可靠的，混在音乐里的声音「只能当提示」。官方数据是 60 秒混音里 93% 的音效被检出，但这是在受控测试里。

3.7 场景适配表

场景	适合谁	触发条件	用到的能力	需要什么准备	成熟度	主要风险
AI 短片配音效	独立开发者	画面有了，声音是空的	sfx + kit	Python、ffmpeg、可不下模型	开箱可试	185/201 过审计，仍需人耳
海量素材筛选	内容团队	要听几百个挑几个	rank / find	模型（1.1GB）	开箱可试	strong 判定 98% 大类对，61% 精确对
声音真假判断	审核、采购	怀疑素材是合成的	realness	模型	可用但脆弱	作者自曝容易被骗
影片声音体检	视频后期	发布前要检查	critique / timeline / sheet	模型	需配置	对照的是 7 部固定片，非盲测
Agent 自我迭代	工作流开发者	agent 要能改自己的产出	forge + MCP	参考录音、MCP 配置	需配置	Goodhart：优化的是工具自己的模型
录音转可编辑代码	音效设计	想改造现有素材	fit	模型 + 源素材许可	可用	12 段实测，riser 类未测
做音乐 / 混音	—	—	—	—	不适用	不在范围
语音转写	—	—	—	—	不适用	官方说不支持

---