earshot – 为 AI 代理提供 聆听 和 制造 声音的方式

它是什么

• 一个仅使用 Python、仅使用 CPU 的命令行工具（和库），将音频转换为 AI 代理可以推理的结构化数据，反之亦然：将代码转换为声音。
• 它附带一组 CLI 命令（describe、match、find、critique 等），以及 Python API 和 MCP 服务器，使 Claude 风格的代理可以通过套接字调用它。

关键能力

功能	代理接收的内容	工作原理
describe FILE	自然语言描述以及校准标签（z 分数）、AudioSet 标签、响度、频谱测量。	使用两个开放模型：CLAP（文本-音频嵌入）和 AudioSet 标签器，以及无模型测量。
match FILE QUERY	相似度分数（余弦 + z 分数）和判定（强/可能/弱）。	使用 CLAP 嵌入查询，与文件的嵌入进行比较，并与 125 个参考声音的词汇表进行交叉检查。
find FILE QUERY	长录音中最佳匹配时刻的时间戳。	滑动窗口，使用相同的嵌入/标签管道对每个片段进行评分，返回 top-k 修剪。
realness FILE…	真实录音与代码合成的分类，带有每个窗口的置信度。	在真实与合成声音的保留集上训练的分类器（ROC-AUC 0.92）。
timeline FILE	“聆听转录”：带有时间、电平、标签、响度曲线、节拍网格、可选视频同步的事件。
sheet FILE	带注释的 PNG（波形、频谱图、标签、同步标记），可视化代理可以读取。
critique FILE	将启动风格视频与基于七个专业启动影片构建的配置文件进行比较的记分卡。
forge RECIPE	从 代码 生成新声音（描述物理合成的“配方”），并使用相同的 earshot 批评者迭代改进它们。
fit FILE	分析录音并输出一个 Python 配方，可以重新渲染近似结果，并带有变化旋钮。
gallery DIR	生成一个自包含的 HTML 页面，显示许多生成的声音、它们的频谱图、测量值和配方。

代理如何使用它

• CLI 打印人类可读的摘要；--json 返回完整的结构化结果，LLM 代理可以解析。
• MCP 服务器保持模型温暖，因此 Claude Code 或其他代理可以重复调用 earshot，而无需 20-40 秒的加载时间。
• 两个现成的 Claude 技能（skills/earshot 和 skills/real-sound）展示了如何将工具嵌入代理的工作流程。

从代码制造声音 – forge

• 配方 是一个小的 Python 模块，描述物理合成块（模态谐振器、滤波噪声、房间模拟等）。
• earshot forge 渲染许多候选声音，使用 earshot 批评者（描述匹配、真实感、音调平衡、包络）对它们进行评分，并运行进化搜索以改进参数。
• v0.2.0 添加了 34 个运动设计类别（嗖嗖声、点击声、撞击声等），具有多个变体和一个基准测试，表明生成的声音难以与真实录音区分。

将录音转换为代码 – fit

• earshot fit 执行分析-通过-合成：将紧凑的合成模型拟合到输入音频，然后写入可重用的配方。
• 在 12 个样本的测试集上报告的中位 CLAP 余弦为 0.945，大多数生成的配方获得与原始相同的顶级标签。

安装与要求

• Python 3.10+，ffmpeg/ffprobe 在 PATH 中，仅 CPU。
• 首次运行下载两个开放模型（约 1.4 GB）：laion/larger_clap_general 和 MIT/ast-finetuned-audioset-10-10-0.4593。
• 可选的 LLM 批评使用 Gemini（API 密钥由用户提供）。

性能与限制

• 描述匹配“强”的时间为 98%；精确变体为 61%。
• 真实与合成分类 ROC-AUC 0.92，但模型可能被欺骗；无模型测量（频谱平衡、包络）更可靠。
• 在笔记本电脑 CPU 上工作：分析 60-90 秒的电影约需 1.5 分钟。
• 无法判断高级美学、语音内容或约 14 kHz 以上的频率。

谁可能觉得它有用？

• 构建 AI 驱动的视频或游戏管道的开发人员，需要代理 推理 音效。
• 探索音频-LLM 集成、音频到代码合成或合成声音评估的研究人员。
• 希望生成可通过编程调整的基于代码的音效的创作者。

底线 earshot 弥合了音频和代码之间的差距，为 AI 代理提供了结构化的“耳朵”来聆听、评估和生成声音，而无需依赖录制的样本。它是一个真正的开源软件项目，专注于 AI 驱动的音频分析和合成。