# jev-highlight-cutter

**Repository Path**: cellinlab/jev-highlight-cutter

## Basic Information

- **Project Name**: jev-highlight-cutter
- **Description**: 按个人偏好与目标时长剪辑长视频高光：Jev 评分、可追溯选片、本地 FFmpeg 粗剪。AI agent skill with evidence-based highlight selection.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jev Highlight Cutter

把长访谈、播客、直播剪成有证据、符合个人偏好和目标时长的原声高光合辑。

这是一个可供 Codex 等 AI agent 使用的 **Skill + Python CLI**：agent 负责理解内容和审阅边界，Jev 负责文字证据评分，本地 FFmpeg 负责剪辑。适合「把五小时访谈剪成八分钟」「多保留失败经历和具体经验」等任务。

**MIT License · Python 3.10+ · 本地处理视频 · 可选本地语音转录**

## 能做什么

- 读取 SRT、VTT、Whisper 风格 JSON，保留原片绝对时间戳。
- 按类型和个人偏好评估信息价值、开头吸引力、完整性、情绪与品味匹配。
- 在目标预算内选取不重叠片段，保存评分、选片依据和原片/成片时间对应。
- 生成可点击的本地审片页、独立 MP4 切片、原声合辑及导出验证报告。
- 支持保留/排除反馈、偏好版本、API 缓存和失败重试。

当前版本主要面向访谈播客。自动转录窗口只是候选；语义判断和视觉事件证据需要 agent 或人工补充。**本 skill 输出粗剪，不自动添加双语字幕、配音、BGM 或导出剪映/ChatCut 工程**；这些可在后续精剪工具中完成。仓库不含用户视频、访谈字幕、私人运行数据或密钥，也不附带商业模型/API 的使用权。

## 目录导航

- [Jev API 配置](docs/jev-api.md)：申请入口、全局环境变量、隐私、费用、模型与重试
- [完整命令说明](references/commands.md)：转录、评分、剪辑、反馈和演示
- [输入格式与时间约定](references/contracts.md)
- [偏好设置](references/taste.md) · [评分标准](references/rubrics.md)
- [验证范围与已知限制](references/validation.md) · [提示词示例](examples/prompts.md)
- [Agent 工作流](SKILL.md) · [贡献说明](CONTRIBUTING.md)

## 1. 安装

先安装 Python 3.10+、Git、FFmpeg（包括 ffprobe）。macOS 可用 Homebrew，Ubuntu/Debian 可用 apt：

```bash
# macOS
brew install python ffmpeg git
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3 python3-venv ffmpeg git
```

核心 CLI 仅依赖 Python 标准库，无需 pip 安装。Windows 请准备 Python 与 FFmpeg，并将两者加入 PATH；下方命令采用 Bash/zsh 语法，可在 WSL 中使用。

### 安装为 Codex Skill

首次安装，目标目录必须不存在：

```bash
mkdir -p "$HOME/.codex/skills"
git clone https://github.com/gnipbao/jev-highlight-cutter.git "$HOME/.codex/skills/jev-highlight-cutter"
python3 "$HOME/.codex/skills/jev-highlight-cutter/scripts/highlight.py" doctor
```

重新打开 agent 会话后，明确调用 `$jev-highlight-cutter`。其他支持 `SKILL.md` 的 agent 可将仓库放到其 skill 目录；不支持自动发现时，让 agent 读取 `SKILL.md` 并按工作流调用 CLI。

也可以克隆到任意目录，仅使用 CLI：

```bash
git clone https://github.com/gnipbao/jev-highlight-cutter.git
```

## 2. 配置 Jev

按 [API 配置指南](docs/jev-api.md) 设置用户全局 `TYPESAFE_API_KEY`。默认评分命令直接读环境变量，不需要 `--key-file`。只检查变量是否存在，不输出值：

```bash
python3 -c 'import os; print("TYPESAFE_API_KEY: configured" if os.environ.get("TYPESAFE_API_KEY", "").strip() else "TYPESAFE_API_KEY: missing")'
```

`doctor` 不调用 Jev，也不验证账号额度。没有密钥仍可建立索引、准备候选和查看待发送请求；真实评分需要可用的 API 账号。`.env` 不会被自动加载。

## 3. 让 agent 剪辑

提供原视频和已有字幕的绝对路径，例如：

```text
使用 $jev-highlight-cutter，把 /data/interview.mp4 剪成约 8 分钟。
字幕在 /data/interview.srt。重点保留具体失败经历、反直觉观点和可执行经验，
排除广告和重复表达。保留完整问答，输出原声合辑、独立切片和审片页。
允许将本次候选字幕、必要上下文和偏好文字发送到 TypeSafe/Jev 评分。
```

不要把密钥粘贴给 agent。若未授权文字传输，agent 应先准备请求并说明实际需要发送的内容。

## 4. 手动 CLI：从长视频到 8 分钟

运行目录必须在 skill 源码目录外。每个视频使用一个新目录；`init` 不覆盖旧任务。以下命令使用安装为 Codex Skill 的路径：

```bash
SKILL="$HOME/.codex/skills/jev-highlight-cutter"
RUN="$HOME/jev-runs/interview-001"
python3 "$SKILL/scripts/highlight.py" doctor
python3 "$SKILL/scripts/highlight.py" init --run "$RUN" --genre interview --target 8m --duration-mode target
python3 "$SKILL/scripts/highlight.py" index --run "$RUN" --video "/data/interview.mp4" --transcript "/data/interview.srt"
python3 "$SKILL/scripts/highlight.py" candidates --run "$RUN"
python3 "$SKILL/scripts/highlight.py" score --run "$RUN" --prepare
```

查看 `$RUN/transfer-preview.json`：它是即将发送的完整文字请求，`uncached_requests` 是未缓存的请求数量。先读完整转录、检查未覆盖段落和候选边界；有语义选段时按 [events 格式](references/contracts.md#agent-event-input) 编写事件文件并重新运行：

```bash
python3 "$SKILL/scripts/highlight.py" candidates --run "$RUN" --events "$RUN/events-authored.json"
python3 "$SKILL/scripts/highlight.py" score --run "$RUN" --prepare
```

确认拥有素材使用权，并同意将这批文字发送到 TypeSafe 后执行：

```bash
python3 "$SKILL/scripts/highlight.py" score --run "$RUN" --allow-text-upload
python3 "$SKILL/scripts/highlight.py" plan --run "$RUN"
python3 "$SKILL/scripts/highlight.py" review --run "$RUN" --thumbnails
python3 "$SKILL/scripts/highlight.py" render --run "$RUN"
python3 "$SKILL/scripts/highlight.py" review --run "$RUN"
python3 "$SKILL/scripts/highlight.py" serve --run "$RUN" --port 18786
```

打开 <http://127.0.0.1:18786/> 审阅原片及合辑，完成后用 Ctrl-C 停止服务。`render --preview` 可生成最高 720p 预览；不带此参数按原尺寸输出。应实际试听切口、检查问题/回答是否完整，不能只依据数值分数交付。

### 时长模式

| 参数 | 行为 |
| --- | --- |
| `--duration-mode target` | 不超目标，默认接受短 5%；不足会报告 `shortfall` |
| `--duration-mode max` | 仅保证不超过上限，可明显短于目标 |
| `--duration-mode exact` | 只在可行时按帧满足目标；否则 `infeasible`，退出码 2 并拒绝渲染 |

`exact` 不通过截断句子、重复画面或隐性变速凑时长。AAC 尾部可能影响容器时长，严格时长以视频帧数为准。

### 没有字幕

可选安装本地 ASR，使用同一虚拟环境运行 `transcribe`：

```bash
python3 -m venv "$HOME/jev-env"
"$HOME/jev-env/bin/python" -m pip install faster-whisper
"$HOME/jev-env/bin/python" "$SKILL/scripts/highlight.py" transcribe \
  --video "/data/interview.mp4" --output "$RUN/asr.json" \
  --model base --language zh --allow-model-download
python3 "$SKILL/scripts/highlight.py" index --run "$RUN" --video "/data/interview.mp4" --transcript "$RUN/asr.json"
```

首次模型下载需要网络和存储空间。已有缓存时省略 `--allow-model-download`，也可传本地模型目录。此过程不上传音频；长视频耗时受设备与模型影响，当前 ASR 不支持分块断点续跑。应校对人名、长句、重叠语音和时间戳。

### 改偏好或选片

创建 `$RUN/brief-patch.json`：

```json
{"taste":{"mode":"interactive","prefer":["具体失败经历","反直觉观点"],"avoid":["广告","重复表达"],"examples":[]},"target_seconds":480,"duration_mode":"max"}
```

```bash
python3 "$SKILL/scripts/highlight.py" configure --run "$RUN" --file "$RUN/brief-patch.json"
python3 "$SKILL/scripts/highlight.py" score --run "$RUN" --prepare
# 检查变更后的请求；同意发送后重新 score，再 plan/review/render
```

审片页可下载 `feedback.json`，再用 `feedback --run "$RUN" --file /path/feedback.json` 应用并重新 `plan`。反馈不会在后台自动渲染。只有想长期复用时才用 `export-profile`；配置与历史版本规则见完整命令说明。

## 输出文件

```text
RUN/
├── brief.json / index.json / transcript.json
├── candidates.json / transfer-preview.json / scores.json
├── plan.json / edl.json / review.html
├── cache/jev/                 # 已完成的 API 请求缓存
├── history/                   # 历史配置与计划
└── renders/<plan-id>/
    ├── roughcut.mp4           # 原声合辑
    ├── cuts/                 # 独立片段
    └── verification.json     # 帧数、音轨、原文件指纹验证
```

`edl.json` 是本项目定义的 JSON 格式，不是剪映/Premiere/Resolve 的原生工程。API 缓存和审片页可能含素材文本，请留在本地。

## 常见问题

| 情况 | 处理 |
| --- | --- |
| 找不到 ffmpeg/ffprobe | 安装并加入 PATH，再运行 doctor |
| 提示缺少 key | 在运行 CLI 的同一 shell 检查环境变量；桌面 app 可能需要重启或从该终端启动 |
| HTTP 401/403 | 在官方控制台检查密钥和权限，不要提交含密钥的日志 |
| HTTP 429/网络失败 | 降低 `--workers 1` 并重试；完成的评分会复用缓存 |
| 候选遗漏 | 检查 coverage，细分过长 ASR 段或编写语义 events |
| 片段不足/时长不可达 | 增加完整候选或调整目标；不要伪造分数或强行截断 |
| stale plan | 按候选→评分→计划顺序重建受影响数据 |
| 字幕没有出现在成片 | 目前字幕用于理解和选段，CLI 不烧录字幕，需后续精剪 |

## 测试与许可证

```bash
python3 -m unittest discover -s tests -v
python3 scripts/highlight.py doctor
```

测试使用明确标注的模拟评分，不消耗 Jev 额度；安装 FFmpeg 时包含小视频真实渲染回归。历史实测范围见 [validation](references/validation.md)。首次开源未重新运行收费 API，也不声称已完成长访谈的独立质量基准。

代码与仓库文档采用 [MIT](LICENSE)，允许使用、修改和商业使用，须保留许可与版权声明。第三方软件、模型服务和用户素材各自适用其条款。项目与 TypeSafe/Jev 无官方隶属关系。