agent-ear
给没有音频通道的文本 Agent 一副离线耳朵:把音频/视频编译成同一时间轴上的 audio-score.json,再整理成层级化、带时间戳的 hearing.md。任何文本模型都能读,不需要模型本身支持音频。
状态:v0.2.9,PyPI + GitHub 已发布;basic(Omni 详细转录)与 precise(Omni 前置 + 按需精修)已实现。
强依赖:Qwen Omni 模型 API。 basic/ask/precise/music 都依赖qwen3.8-omni-flash;没有 Omni API Key 和网络时,只有privacy本地降级可用。precise 还额外依赖 Qwen ASR。
边界:只做离线文件;不做 Live Translation、实时流、空间声学、声纹身份、完整音乐总谱。
这不是“可选云增强”。 Omni 是基础模式的必需前置;
privacy是唯一不调用 Qwen 的模式(MOSS 仍未实现)。
配套:实时 vs 离线。 这个项目处理已经录好的文件,给的是可下刀的时间戳。 如果你要的是正在说话时的实时对话、打断(barge-in),用 dsh-moss-live——它管"说得出话",这里管"切得准"。
为什么不是直接问 Omni?
因为“听懂”和“能剪”不是一回事。
- 直接问 Omni:180 条 QA 87.2%;agent-ear 的 QA 只有 58.9%——它不是 QA 冠军。
- agent-ear 的增量是 40ms 事件边界、词级时间、BPM/downbeat、切点偏差;这些是“能直接对着剪”的东西。
所以:单问题、只要答案,直接问 Omni;要时间轴/批量/可审计,才用 agent-ear。 详见 直接 ask vs 转录后 ask。
安装
DeepSeek Harness 用户:
dsh plugin add agent-ear会装成 bundle(dsh.bundle.patch已在包内), 技能会出现在 DSH 的技能目录里。CLI 仍需另外装:uv tool install agent-ear。
基础模式只调 Qwen,但不需要
dashscope/百炼 SDK。 我们直接用 DashScope 兼容的 HTTPS 接口,避免把 SDK 和它的依赖拖进基础安装;Qwen Key 仍在agent-ear setup里配置。先装 CLI,再装 skill。
skills/agent-ear/scripts/agent-ear只是一个 6 行的薄包装,它execPATH 里的agent-ear命令。 如果你只用npx skills add HudsonHuang/agent-ear、或手动 clone 来装 skill,必须另外执行uv tool install agent-ear, 否则第一条命令就会报exec: agent-ear: not found。agent-ear doctor会用NO-CLI标出这种情况。
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/HudsonHuang/agent-ear/main/install.sh -o /tmp/agent-ear-install.sh
sh /tmp/agent-ear-install.sh
或手动:
uv tool install "agent-ear" # 只装 basic(推荐先这样)
# uv tool install "agent-ear[local]" # precise 需要:torch/BEATs/Beat This!,体积较大
agent-ear setup
DSH(推荐:npm bundle)
dsh plugin add agent-ear
uv tool install agent-ear # CLI 仍需单独装
agent-ear setup --target dsh
agent-ear 的 npm 包带 dsh.bundle.patch,安装后会通过 bundle 注册 Skill;这比手动复制 <DSH_HOME>/skills/agent-ear 更容易被 DSH 插件市场发现。
Windows(原生,PowerShell,推荐一键)
irm https://gh-proxy.com/https://raw.githubusercontent.com/HudsonHuang/agent-ear/main/install.ps1 | iex
它会自动:
- 找/下 ffmpeg + ffprobe(优先 gyan 直连,失败走
gh-proxy,再失败才 winget); - 找/下 uv(pip 国内镜像 → USTC 二进制 → 官方安装器);
- 用阿里云/清华 PyPI 镜像装
agent-ear; - 只装 DSH Skill,不下载任何模型;
- 跑
doctor,告诉你还缺什么。
不需要预装 Python/uv/ffmpeg。所有下载优先国内源;即使开了 VPN 也优先走国内镜像。
手动安装也可以:
uv tool install agent-ear
agent-ear setup --install-ffmpeg
Windows 配置在 %APPDATA%\agent-ear\config.json;ffmpeg 本地版在 %LOCALAPPDATA%\agent-ear\ffmpeg\bin。
Windows + DSH 已实际安装测试,PR #1 修复了 PowerShell BOM、--api-key-stdin 失败提示和 BPM 回退;Windows CI(3.10/3.12)通过。
模型:按需下载,basic 不下载模型
- basic 只调 Qwen Omni;安装时不下载 BEATs/Beat This!,第一次
precise/事件/beat 才下载。 - 模型默认走
hf-mirror.com;可用HF_ENDPOINT或EAR_HF_ENDPOINT覆盖。 - GitHub 模型资源(BEATs)优先走
gh-proxy.com,失败再直连。 - PANNs 的 447 类标签已随包内置,不再访问 Google Storage。
- 需要预下载时:
agent-ear setup --download-models(并行下载)。
安装向导会问什么
agent-ear setup 会:
- 检查 ffmpeg/ffprobe;Windows 上可
--install-ffmpeg自动下载; - 询问 Qwen API Key(隐藏输入,不回显);
- 可选自定义 base URL(默认
https://dashscope.aliyuncs.com); - 检查 Key;
- 选择要安装的 Agent:Codex / DSH / Claude Code;
- 写
~/.config/agent-ear/config.json(Windows:%APPDATA%\agent-ear\config.json,0600); - 安装 Skill,跑 doctor + 本地 smoke test。
Key 也可以走环境变量:DASHSCOPE_API_KEY(优先级最高)。
快速使用
# 问答:一次 Omni 调用,同时返回完整分析 + 答案
agent-ear ask input.mp4 "这段音频里发生了什么?"
# 详细转录:完整 transcript/events/music,0.5–2s 时间戳
agent-ear listen input.mp4 --mode basic --out .ear/my-video
# 精确:词级 ASR + 40ms 事件 + beat grid
agent-ear listen input.mp4 --mode precise --need transcript,events,beat --out .ear/my-video-precise
# 长视频只要笑声:不转写,只跑目标事件
agent-ear listen long.mp4 --mode basic --request "把视频里所有笑声都剪出来"
agent-ear listen long.mp4 --mode precise --request "把视频里所有笑声都剪出来"
# 问已保存的转录,不重新调 Omni
agent-ear ask --score .ear/my-video "谁在什么时候笑了?"
# 直接出剪辑/DAW 结果
agent-ear export .ear/my-video --format srt
agent-ear export .ear/my-video --format edl --labels Laughter,Applause
agent-ear highlights .ear/my-video --top 5 --by Laughter --format edl
agent-ear mixcheck render.wav --json
agent-ear compare before.wav after.wav --json
读结果:
cat .ear/my-video/hearing.md
agent-ear digest .ear/my-video/audio-score.json --level 1
输出
.ear/<name>-<hash>/
├── audio-score.json # 唯一事实源,schema 校验
├── audio-score.json.gz
├── hearing.md # 层级 Markdown:概览 / 章节 / 音乐 / 事件索引 / 限制
├── digest.md # 章节级短摘要
├── context.md # 给文本 LM 的完整上下文
└── work/ # 16k/32k wav
audio-score.json:speech/events/music/relations/timeline/views;事件带precision(omni-coarse/refined-40ms)。hearing.md:给 Agent/人读;# 音频纪要+## 概览/## 章节/## 音乐/## 事件索引/## 限制。context.md:给文本 LM 的完整 transcript/events/music;agent-ear ask --score直接使用,不再调 Omni。
模式
| 模式 | 用途 | 时间精度 | 依赖 |
|---|---|---|---|
basic(默认) |
详细转录、摘要、粗剪 | 0.5–2s | Qwen API |
precise |
字幕、打轴、卡点、精剪 | 词级 + 40ms | Qwen + local extra |
music |
音乐描述 + beat grid | BPM/beats | Qwen + local extra |
privacy |
不上传 | 本地 | local extra(MOSS 未实现) |
precise 用 --need transcript,events,beat 显式指定;不指定时默认三项都跑。--request 会按自然语言只跑需要的层。
实测(2026-11-11)
| 项 | 结果 |
|---|---|
| 1 小时 basic 结构化 | 231s,RTF 0.064,¥0.211/音频小时 |
| 5 分钟 precise 全量 | 57s,RTF 0.19 |
| 5 分钟只要笑声 basic / precise | 15.2s / 24.1s;53/65 事件 refine |
| Omni 单模型 QA(180 条) | 87.2% |
| 直接 ask vs 一次转录+回答 | 87.2% vs 80.0%(全量) |
| 转录后强文本模型(40 条子集) | 77.5% |
诚实结论:basic 的价值是完整转录/时间轴/可审计,不是“QA 超过 Omni”。单问题最高准确率仍是直接 ask;多问题/剪辑才值得先转录。详见 直接 ask vs 转录后 ask。
Codex / DSH / Claude
安装后 Skill 位置:
- Codex:
$CODEX_HOME/skills/agent-ear(默认~/.codex/skills/agent-ear) - DSH:
$DSH_HOME/skills/agent-ear(默认~/.dsh/skills/agent-ear) - Claude Code:
~/.claude/skills/agent-ear
Windows 下对应 %USERPROFILE%\.codex\skills\agent-ear 等。
Codex 重启后可用 /skills 查看;DSH 新会话可见;Claude 输入 /agent-ear。Skill 内部通过 scripts/agent-ear(Windows:scripts\agent-ear.cmd)调用 CLI。
DSH 有两种装法:
dsh plugin add agent-ear(npm bundle,推荐),或手动把 Skill 放到<DSH_HOME>/skills/agent-ear。前者会通过dsh.bundle.patch注册 Skill,也能进 DSH 插件市场;后者适合不想装 npm 包的用户。
Doctor / 配置 / 卸载
agent-ear doctor --json # 依赖/config/skill/模型,不联网
agent-ear doctor --check-api # 额外检查 key
agent-ear config show # 不显示 key
agent-ear config set-key # 隐藏输入
agent-ear skill list
agent-ear uninstall --target codex
agent-ear uninstall --target all --purge
已知限制
- basic 是 0.5–2s 时间戳,不能精确打轴;要精确用 precise。
- precise 事件 refine 目前只覆盖可映射标签(如 Laughter);开放标签仍是
omni-coarse。 - 1 小时 basic 已实测;1 小时 precise 未实测。
- 5 分钟 precise 的 Qwen diarization 会过切说话人;长音频显式
--speakers 2或合并。 - AED 选型不是永久的;
ear/aed_registry.py的LAST_REVIEWED超过 6 个月要重查。 - Windows 原生支持 basic/precise;
privacy的 MOSS 仍未实现。
开发
uv venv .venv --python 3.12
uv pip install --python .venv/bin/python -e ".[dev,local]"
.venv/bin/python -m pytest -q
.venv/bin/python -m ear.cli --help
模型缓存:~/.cache/ear/models(EAR_MODEL_DIR 可覆盖)。下载支持 HTTPS_PROXY / EAR_DOWNLOAD_PROXY。
文档
Metadata
Release files for agent-ear 0.2.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_ear-0.2.9-py3-none-any.whl | Python 3 | none | any | Details for agent_ear-0.2.9-py3-none-any.whl |
Release files / agent_ear-0.2.9-py3-none-any.whl
| Download URL | agent_ear-0.2.9-py3-none-any.whl |
|---|---|
| Size | 134.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d8020c9017038db9353ea000193b7f3f9511ff90d3712fbc1c7b2bb2b152ddfe
|
|
BLAKE2b-256 checksum How to use checksums |
a73ad684fa56818cf6ff90896f880d46a082498143b62a9422e8c0efe01a00dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for agent-ear 0.2.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
1 file in this release has been uploaded with provenance metadata.
Attestation for agent_ear-0.2.9-py3-none-any.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.