VideoCut

Python 包：ASR 转录（推荐讯飞LLM） → LLM 审核生成 edits.json → 可选网页校正 → ffmpeg 输出成片。适合「AI 粗剪 → 剪映 / Premiere / DaVinci 精修」工作流。

依赖

依赖	说明
uv	创建环境、运行命令（Windows / macOS / Linux 相同用法）
Python ≥ 3.10	pyproject.toml 要求
ffmpeg、ffprobe	在系统 PATH 中可用
~/.config/llm_key/api_key.toml（推荐）	ASR 与 LLM 密钥；可选仓库内或 VIDEOCUT_API_KEY_TOML

安装

在仓库根目录执行：

uv venv
uv pip install -e .

之后所有 CLI 均用 uv run <命令> 调用（保证走当前虚拟环境）。

推荐：一条命令（autocut）

串联 process → review（LLM）→ 本地网页校正 → cut，其中 autocut 内已固化常用参数：讯飞 LLM ASR（xf_llm）、多说话人、language=auto。

# Windows（路径按你的机器改）
# 省略 --output / -o 时：在当前工作目录下自动创建 output/YYYYMMDD_HHMMSS/（本地时间，每次运行一个新文件夹）
uv run autocut --video .\src_video\demo.mp4

# 指定固定项目目录（便于复跑同一路径下的 review / cut）
uv run autocut --video .\src_video\demo.mp4 --output .\output\demo --ref .\src_video\script.pdf

# macOS / Linux
uv run autocut --video ./src_video/demo.mp4
uv run autocut --video ./src_video/demo.mp4 --output ./output/demo --ref ./src_video/script.pdf

• --output / -o：项目根目录（其下会有 inputs/、work/、final/）。可选；不写则默认为 <当前目录>/output/YYYYMMDD_HHMMSS/（在仓库根执行即项目下的 output/）。
• --ref：如果你有对应的文本稿，可选；若提供，将 PDF 复制到 work/ref.<ext>，供 review 读入参考稿。其他格式如doc、txt也可以支持。
• --no-review-ui：跳过浏览器校正，在 LLM 生成 edits.json 后直接 cut（适合批处理或完全信任模型结果时）。

网页校正阶段：终端会打印 http://127.0.0.1:<端口>/，浏览器里改完后回到同一终端按回车，再继续导出成片。推荐进行此步进行二次审查。

输出目录

<output> 即一次运行的项目根：由 autocut / process 的 --output / -o 指定；若省略，则为当前工作目录下的 output/YYYYMMDD_HHMMSS/。

<output>/
├── inputs/
│   └── source.<ext>          # 指向源视频的符号链接；Windows 上可能为复制
├── work/
│   ├── transcript.srt
│   ├── transcript.words.json
│   ├── signals.json          # duration + silences（ffmpeg silencedetect）
│   ├── ref.pdf               # 若使用过 --ref
│   ├── edits.json            # LLM + 可选网页校正
│   └── analysis.md           # LLM 说明（若有）
└── final/
    ├── edited.mp4
    └── edited.srt

可选：自行放入 inputs/video_script.md、work/hotwords.txt，review 会按路径自动读入（见 review --help）。

配置 api_key.toml

推荐：用户级固定路径（勿提交进仓库）：

• Linux / macOS：~/.config/llm_key/api_key.toml
• Windows：%USERPROFILE%\.config\llm_key\api_key.toml

可从仓库内示例生成：

mkdir -p ~/.config/llm_key   # Windows: mkdir %USERPROFILE%\.config\llm_key
cp api_key.example.toml ~/.config/llm_key/api_key.toml

按下列顺序查找密钥文件，先命中者生效：

1. 环境变量 VIDEOCUT_API_KEY_TOML（绝对路径或带 ~ 的路径，指向任意 api_key.toml）
2. 自当前工作目录向上最多 20 层目录查找 api_key.toml（便于项目内单独密钥）
3. 上述皆无时，使用 ~/.config/llm_key/api_key.toml

按所用 ASR 填写对应小节（名称以代码为准，见 src/videocut/core/config.py）：

• ASR模型任选其一：
  • [ASR_Doubao] — 豆包 ASR（process --asr doubao）
  • [ASR_xf_standard] / [ASR_xf_LLM] — 讯飞（xf_standard / xf_llm）
• LLM模型：
  • [review_api] — OpenAI 兼容接口：base_url、api_key、model_name；可选 max_tokens

分步命令（调试或自定义参数）

步骤	命令
1. 转录 + 静音信号	uv run process <video> [-o <BASE>] [--asr doubao|xf_standard|xf_llm] … — -o 可选，默认与 autocut 相同：output/YYYYMMDD_HHMMSS/
2. LLM 生成 edits	uv run review <BASE>
3. 网页校正	uv run review-ui <BASE>
4. 导出成片	uv run cut <BASE>（默认读 inputs/source.* 与 work/edits.json，输出到 final/）

其它入口：transcribe（仅 ASR）、ref-extract、test-doubao-asr 等见 pyproject.toml 中 [project.scripts]。

cut 行为摘要

• 校验 edits.json 索引；应用 textEdits；按 transcript.words.json 做词边界吸附（约 ±150ms）
• ffmpeg 拼接保留段；编码器自动回退（NVENC / VAAPI / QSV / VideoToolbox / libx264）
• 重映射 SRT 时间轴到成片时间线

Cursor 与示例

• .cursor/skills/videocut/SKILL.md — 给 Agent 的完整流程、LLM 启发式、edits.json 字段约定
• .cursor/skills/videocut/edits.example.json、signals.example.json — 格式示例