用 earshot 给编码 Agent 装上「耳朵」：CPU 本地音频 MCP 服务器、声音检索与音画核对实操

# 前置：确认 ffmpeg / ffprobe 可用（官方要求二者在 PATH 上）
ffmpeg -version
ffprobe -version

# 安装（MCP 形态，官方 README 原样）
uv tool install "earshot[mcp] @ git+https://github.com/Leonxlnx/earshot"

# 立刻把两个模型下到本地（约 1.1 GB）
earshot doctor --fetch

# 后续升级
uv tool upgrade earshot

# 可选：需要 Gemini 音频点评时才装 llm 扩展
uv tool install "earshot[mcp,llm] @ git+https://github.com/Leonxlnx/earshot"

# 方式 A：uv tool install 装的（推荐）
claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- earshot mcp

# 方式 B：从源码克隆装的，换成虚拟环境里的 python
claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp

# Windows 克隆安装时把路径换成 .venv/Scripts/python.exe

# 任意 MCP 客户端的 .mcp.json 等价写法
{
  "mcpServers": {
    "earshot": {
      "command": "/path/to/earshot/.venv/bin/python",
      "args": ["-m", "earshot", "mcp"],
      "env": { "EARSHOT_THREADS": "3" }
    }
  }
}

# 机器较慢、客户端超时：启动 Claude Code 时放宽 MCP 超时
MCP_TIMEOUT=60000 claude

# 注册后确认在列表里
claude mcp list

# 用自然语言描述给一批候选排序
earshot rank "a single mechanical key press" candidates/*.ogg

# 对选中的文件做匹配判定，--alts 给出容易混淆的干扰项
earshot match key.ogg "a deep thocky mechanical keyboard press"   --alts "a clicky blue switch keyboard" "a mouse click"

# 让工具用文字描述某个文件听起来是什么
earshot describe key.ogg

# 每条命令都支持通用输出开关
earshot rank "a single mechanical key press" candidates/*.ogg --json --out rank.json

# 在长录音里找最像「单次机械按键」的 4 个片段
earshot find keys.ogg "a single mechanical key press" --top 4

# 输出是若干 start / end 秒数，可直接喂给 ffmpeg 裁剪
# 例：把 2.40 到 2.75 秒切出来复核
ffmpeg -i keys.ogg -ss 2.40 -to 2.75 -c copy hit.ogg

# 批量脚本里用 --json + --out 拿结构化结果
earshot find keys.ogg "a single mechanical key press" --top 4 --json --out hits.json

# 对整段影片做音画点评，输出按时间戳列出待修项
earshot critique film.mp4

# 生成标注图：帧 + 事件标签 + 频谱 + 响度 + 对拍标记
earshot sheet film.mp4 -o sheet.png

# 把一批 forge 产物汇成一个静态试听页
earshot gallery made/ -o page.html

# 可选：调用音频大模型点评（需自己的 GEMINI_API_KEY 且显式同意上传）
earshot llm film.mp4 --yes-upload

# 结构化结果落盘，供 Agent 二次处理
earshot critique film.mp4 --json --out critique.json

# 列出可用配方与参考集
earshot forge --list

# 按键音：给真实参考录音、搜索预算与变体数
earshot forge keypress --refs path/to/real/keypresses/   --budget 144 --variants 4 --dir made/keypress

# 用内置参考集的 forge 划分跑 whoosh
earshot forge whoosh --refset whoosh_fast --budget 96 --dir made/whoosh

# 用文字目标 + 干扰项 + 自己的参考录音，走 real 模式
earshot forge whoosh --target "a fast crisp air whoosh"   --alts "a wind gust" "a sword swing"   --refs path/to/real/whooshes/ --mode real --dir made/whoosh

# 拿报告里的参数换随机种子重渲染，验证是否稳定
earshot forge --render keypress --params made/keypress/report.json   --seeds 1 2 3 --dir made/again

# 打开 made/keypress/report.md 与 audition.wav 试听对比