agent-ear 0.2.0__py3-none-any.whl

agent_ear-0.2.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: agent-ear
+Version: 0.2.0
+Summary: Give text-only agents an offline ear: audio/video -> a time-indexed audio score.
+Author: agent-ear contributors
+License: MIT
+Project-URL: Homepage, https://github.com/HudsonHuang/agent-ear
+Project-URL: Repository, https://github.com/HudsonHuang/agent-ear
+Project-URL: Issues, https://github.com/HudsonHuang/agent-ear/issues
+Keywords: audio,agent,skill,transcription,audio-tagging,video-editing
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: requests>=2.31
+Requires-Dist: soundfile>=0.12
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: local
+Requires-Dist: torch>=2.2; extra == "local"
+Requires-Dist: torchaudio>=2.2; extra == "local"
+Requires-Dist: beat-this>=0.1; extra == "local"
+Requires-Dist: panns-inference>=0.1; extra == "local"
+Requires-Dist: silero-vad>=5.0; extra == "local"
+Requires-Dist: librosa>=0.10; extra == "local"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# agent-ear
+
+给没有音频通道的文本 Agent 一副**离线耳朵**：把音频/视频编译成同一时间轴上的 `audio-score.json`，再整理成层级化、带时间戳的 `hearing.md`。任何文本模型都能读，不需要模型本身支持音频。
+
+> 状态：basic（Omni 详细转录）与 precise（Omni 前置 + 按需精修）已实现。  
+> 定位：**local-first, cloud optional**。basic 需要 Qwen API Key；`privacy` 模式不调用 API。  
+> 边界：只做离线文件；不做 Live Translation、实时流、空间声学、声纹身份、完整音乐总谱。
+
+## 安装
+
+### macOS / Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/HudsonHuang/agent-ear/main/install.sh -o /tmp/agent-ear-install.sh
+sh /tmp/agent-ear-install.sh
+```
+
+或手动：
+
+```bash
+uv tool install "agent-ear"          # 只装 basic（推荐先这样）
+# uv tool install "agent-ear[local]" # precise 需要：torch/BEATs/Beat This!，体积较大
+agent-ear setup
+```
+
+### Windows（原生，PowerShell）
+
+```powershell
+winget install Gyan.FFmpeg
+uv tool install agent-ear
+agent-ear setup
+```
+
+如果 GitHub 脚本可用：
+
+```powershell
+irm https://raw.githubusercontent.com/HudsonHuang/agent-ear/main/install.ps1 | iex
+```
+
+Windows 需要 `ffmpeg`/`ffprobe` 在 PATH；`uv tool install` 默认把 `agent-ear.exe` 放到 `%USERPROFILE%\.local\bin`。
+
+### 安装向导会问什么
+
+`agent-ear setup` 会：
+
+1. 检查 ffmpeg/ffprobe；
+2. 询问 **Qwen API Key**（隐藏输入，不回显）；
+3. 可选自定义 base URL（默认 `https://dashscope.aliyuncs.com`）；
+4. 检查 Key；
+5. 选择要安装的 Agent：Codex / DSH / Claude Code；
+6. 写 `~/.config/agent-ear/config.json`（Windows: `%APPDATA%\agent-ear\config.json`，0600）；
+7. 安装 Skill，跑 doctor + 本地 smoke test。
+
+Key 也可以走环境变量：`DASHSCOPE_API_KEY`（优先级最高）。
+
+## 快速使用
+
+```bash
+# 问答：一次 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 "谁在什么时候笑了？"
+```
+
+读结果：
+
+```bash
+cat .ear/my-video/hearing.md
+agent-ear digest .ear/my-video/audio-score.json --level 1
+```
+
+## 输出
+
+```text
+.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](docs/direct-vs-transcribe.md)。
+
+## 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 的 Skill 与 Plugin 不是一回事：Skill 放目录即可，不需要 `dsh plugin add` 或 `dsh.bundle.patch`。
+
+## Doctor / 配置 / 卸载
+
+```bash
+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 仍未实现。
+
+## 开发
+
+```bash
+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`。
+
+## 文档
+
+- [Windows 原生支持](docs/windows.md)
+- [输出 Schema](docs/output-schema.md)
+- [按请求动态选策略](docs/request-strategies.md)
+- [直接 ask vs 转录后 ask](docs/direct-vs-transcribe.md)
+- [v2 架构](docs/architecture-v2.md)
+- [水位结果](docs/eval-results-2026-11-11.md)
+- [事件 refine](docs/refine-eval.md)
+- [AED 选型与敞口](docs/aed-selection.md)
+- [Roadmap](docs/roadmap.md)
+- [Schema 示例](schema/examples/)
+- [Skill 源文件](skills/agent-ear/SKILL.md)

agent_ear-0.2.0.dist-info/RECORD

@@ -0,0 +1,52 @@
+agent_ear-0.2.0.dist-info/licenses/LICENSE,sha256=hwrtwEQGr45Wv3l_p6feRVCj_xmXcp7Eg030bu5nynM,1079
+ear/__init__.py,sha256=6QEO_wqcLRMT-pm_Tyn-yTWZSD-01NMSuY_8lzEfZpw,101
+ear/aed_psed.py,sha256=1mGltd9Z-L5YTYpy7rDZ_VmxnYGqLFHNGlfza2P4nMs,2312
+ear/aed_registry.py,sha256=4BasDPpCe2lr4FzGO-zp3r4VW4vsAAdF3PPh_AfiD-w,1972
+ear/asr_qwen.py,sha256=VNnDY0E3EDzydSbN9-JIEJsEtiRcnjxceBnJWOFHpDk,7662
+ear/beats.py,sha256=8xFFODTTgaM7Uii2Z0AHqcDtKCoyIwj9g0g1wrXSI8w,3388
+ear/cli.py,sha256=a5ymbO0EabTg2aJ4Vd1snoc4WfZnSoikjPWL62XhlYA,33462
+ear/config.py,sha256=xTDDMOOvcYW4IgOZxeXHQF-WEe6enewMZ5rs-X-ilbk,6381
+ear/context.py,sha256=ZXChzwUDNOuWCuAaoXt7WkxGDYeE6bzGNSVoytQa8qU,1678
+ear/doctor.py,sha256=Qx6CR7QmlcL4CihjHY6q4vEr8N-X1kPtXjFR6v3RtKc,3151
+ear/events_panns.py,sha256=k4KZ_eEZ3LlVjPZE8p8p30LrFoYsp1rQZhiSLKwPHuI,6598
+ear/fuse.py,sha256=kI2kG2MgxKuq-XrJ8rsBecYQKvCEwzpCEnTlNtlVxb8,9291
+ear/install.py,sha256=V1Pw4qIQ5w6K_WSyMo4oRTv0ELrJUI0ZkEexsZghI7w,6596
+ear/media.py,sha256=RGt948GHWiDrKTBGjRge_4XXzx1rZyvhgySTg7BaVMM,5243
+ear/models.py,sha256=NmNJpyUJlNhQtpdd1Dh0RQRhccqNkI9ljjWZg4T2C0E,6504
+ear/omni.py,sha256=7Tq9QoO-9nRXAMObwueTBI_pxGSZdQOpnTJ7idp-GgY,13810
+ear/probe.py,sha256=jihav14mVjicFfrNM4uvVCxi_9qBtJIJZJyS12qmCCE,3351
+ear/render.py,sha256=0824s2VQLrSW2YjTqjl2XA7fnXCFLzA-iRZyAIfHZoo,7539
+ear/requests.py,sha256=nfVOTmjlTwDZV64opJA9AMI17V_vQ59co07CUU4mtzA,2238
+ear/routing.py,sha256=o6PwGlnG5EbkkPtwc4lZ2gShoVbNCyCd4JmKZc256DY,1793
+ear/score.py,sha256=z-5FvMeO8PWJzpRJW5_-tUlbHS-sz8-KXpQiaNFRcaE,10066
+ear/setup.py,sha256=PYpeoQm8c62HnxX4P7cTynxdcCio6KGYrPEY7gfwCvU,6272
+ear/text_llm.py,sha256=lHcXQfkLf38mxDEaIhy9eWWPG-Rz1Pokk76pT8fHAtY,2104
+ear/_data/schema/audio-score.schema.json,sha256=_WV0oGip5b6Ent3_kjh6rxs5XPdgVLOG5gOQ4siqd7o,19212
+ear/_data/schema/examples/basic.json,sha256=FXX-Xc_tSfEskr2GkA5aYcd-QbBFN4NtKIYGDwQh_ZA,28490
+ear/_data/schema/examples/events.json,sha256=faMxvCsg4MDIF0uy_aA4eb1ec4wrNNfADyZp33usJ_A,11479
+ear/_data/schema/examples/precise.json,sha256=kMMi_MGbx64XDqaSqzNBpsg9XTKvx7fZgrMo_ywLZBI,73386
+ear/_data/skill/SKILL.md,sha256=DkW_Eag1yoa4vg9wj0jtSjLtquWcjdvZQsbFlTnugoQ,4875
+ear/_data/skill/references/direct-vs-transcribe.md,sha256=sp_STMRrR-2SfrogNIedDBcRuwIIwbzC45X8qBfXTa0,5631
+ear/_data/skill/references/output-schema.md,sha256=HW3MpbkforxfVhJLLDPit9fHnRRegJdk1vJ7e_DLml8,4850
+ear/_data/skill/references/request-strategies.md,sha256=5OvSOC7thoMa5NUEHOv1FTPW3pBcROsrxFPuNI-Rzt0,3681
+ear/_data/skill/scripts/agent-ear,sha256=Jq0TZ32btUTPCaD4UbX5oNmJanbpRvcdEwpbjFYoDsc,129
+ear/_data/skill/scripts/agent-ear.cmd,sha256=0b1TZWvQZ--LXobkpUFv1V_L9wvMo3PR8dkd6sA9MsQ,120
+ear/_data/skill/scripts/agent-ear.ps1,sha256=mQT-ZN5RKzqUo8LRcMFPtwz6fJdt4vjdv-aqhVBYmRQ,137
+ear/_vendor/pretrainedsed/LICENSE,sha256=OZrMbZA8_WWmzVurpqma8-5TTXkWGweFTBpv_qs9yIs,1071
+ear/_vendor/pretrainedsed/config.py,sha256=EOQBIHapuITRIiybGZuLvXqRZ3XUbRwkJcJk0Szr5oM,1372
+ear/_vendor/pretrainedsed/ear_runner.py,sha256=Fr-gdJ9kbEFDeIWnGykcD6AOvhYoxSgi7AkcnIkmNMY,5481
+ear/_vendor/pretrainedsed/data_util/audioset_classes.py,sha256=dxrbY3aLNJFxoWaLSwwvky9tsbIeEEUMfpE2wDl-B28,54411
+ear/_vendor/pretrainedsed/models/prediction_wrapper.py,sha256=U_N_eHCoXmQkLQfdCH_7THKoqEE9Q6WTq0a7qFs5g-s,10385
+ear/_vendor/pretrainedsed/models/seq_models.py,sha256=16wquWfOZePa19089xcWOhB-jMC1e9qw13WnLwdcpmc,1163
+ear/_vendor/pretrainedsed/models/transformer_wrapper.py,sha256=jKcoRHXkfcAKX0dr2Nk3QA41yVrjFkuP2REVBcSk3ug,506
+ear/_vendor/pretrainedsed/models/beats/BEATs.py,sha256=x9ukbZ-DoJsAljN4FnlaIjnLq1-el5xVjFfxWVNmd2U,6931
+ear/_vendor/pretrainedsed/models/beats/BEATs_wrapper.py,sha256=K4tztnUsWP618mQy5lnTNFpo7xD1koxK-McO7SPW4E8,2041
+ear/_vendor/pretrainedsed/models/beats/Tokenizers.py,sha256=_Msfr8Nc1-lHRZNAiwcevgXbvnyHeWXtt3EwVSYX4Gg,6429
+ear/_vendor/pretrainedsed/models/beats/backbone.py,sha256=Xfk--IPS_qD5o3Y8qpNpC3BpBQlNbscn-G9oqCe4fF0,30779
+ear/_vendor/pretrainedsed/models/beats/modules.py,sha256=xLQXCxxChnF7YGeI9hegp2ivB2zeqqmx01v3DWw4Wf4,7386
+ear/_vendor/pretrainedsed/models/beats/quantizer.py,sha256=Mi8fVfTVIu6SfQNucPk-XhW_D_Nqbe9bRYfefDUFNZA,8171
+agent_ear-0.2.0.dist-info/METADATA,sha256=VRn95N7rjdJAd-_CNaEIA4mjrfIh4d_YO3-vHaK68ZA,8560
+agent_ear-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+agent_ear-0.2.0.dist-info/entry_points.txt,sha256=Z191ozvwL7gzaYyssiIZejFJh1KaTO123eA-6rxVHEc,43
+agent_ear-0.2.0.dist-info/top_level.txt,sha256=b1z7E33IPyW9p9kWpE2Kpypr6qb_dorXsTqlWLYWySc,4
+agent_ear-0.2.0.dist-info/RECORD,,

agent_ear-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_ear-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-ear = ear.cli:main

agent_ear-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-ear contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_ear-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ear

ear/__init__.py

@@ -0,0 +1,3 @@
+"""Ear: compile audio/video into a time-indexed, LLM-readable audio score."""
+
+__version__ = "0.2.0"