Video Clip Assistant v2

AI 智能视频剪辑助手。基于 video-use 架构改进，本地 Whisper 替代付费 API，在 WorkBuddy 环境下实现完整 AI Agent 驱动剪辑闭环。

核心理念：用户只需描述剪辑意图，AI Agent 自动完成转录 → 分析 → 编辑决策 → 渲染 → 自检全流程。无需手动操作时间轴。

架构概述

素材文件夹 → Layer 1 转录层 → Layer 2 AI决策层 → Layer 3 渲染层 → Layer 4 自检层 → 成品
                  ↓                    ↓                ↓              ↓
            Whisper/ASR        LLM 分析生成 EDL    FFmpeg 渲染    质量检查循环

快速开始

一键智能剪辑（AI Agent 工作流）

# 1. 转录视频
python3 scripts/transcribe.py --input my_video.mp4 --output transcript.json --format json

# 2. 预览 LLM prompt
python3 scripts/generate_edl.py --transcript transcript.json --strategy remove_fillers --dry-run

# 3. 在 WorkBuddy 对话中粘贴 prompt，获取 EDL JSON，保存为 edl.json

# 4. 预览 EDL
python3 scripts/render_edl.py --edl edl.json --dry-run

# 5. 渲染视频
python3 scripts/render_edl.py --edl edl.json --output edit/final.mp4

# 6. 自检质量
python3 scripts/self_eval.py --video edit/final.mp4 --edl edl.json --output quality_report.json

简短模式（交互式对话）

直接在对话中说：

"帮我剪辑 ~/Videos/meeting.mp4，去掉所有口癖和长停顿" "从 ~/Videos/live.mp4 提取 5 个最精彩的高光片段"

Agent 会自动识别意图 → 选择策略 → 生成 EDL → 请求确认 → 渲染 → 自检 → 交付。

核心脚本

scripts/transcribe.py — ASR 转录层 (新增)

高精度语音转文字，输出结构化 packed transcript。

python3 scripts/transcribe.py \
  --input <视频/音频文件> \
  --engine <whisper|faster-whisper|funclip> \
  --model <tiny|base|small|medium|large> \
  --language <zh|en|auto> \
  --diarize \
  --format <json|packed> \
  --output <输出文件>

scripts/generate_edl.py — AI 决策层 (新增)

基于 transcript 和剪辑策略生成 Edit Decision List。

python3 scripts/generate_edl.py \
  --transcript <transcript.json> \
  --strategy <remove_fillers|extract_highlights|condense|topic_splits|social_clip|custom> \
  --output <edl.json>

内置策略 (详见 templates/clip_strategies.yaml):

scripts/render_edl.py — 渲染执行层 (新增)

按 EDL 指令调用 FFmpeg 渲染最终视频。

python3 scripts/render_edl.py \
  --edl <edl.json> \
  --output <edit/final.mp4> \
  [--segments] \
  [--dry-run]

渲染特性:

• 自动 30ms 音频 crossfade at cut points
• 支持色彩校正 (warm/cool/cinematic/vivid)
• 字幕烧录
• Concat 拼接

scripts/self_eval.py — 自检循环 (新增)

渲染后自动检查视频质量。

python3 scripts/self_eval.py \
  --video <edit/final.mp4> \
  --edl <edl.json> \
  --output <quality_report.json>

检查项:

• 时长与 EDL 预期对比
• 黑帧检测
• 音频爆音
• 过长静音
• 切点边界完整性

scripts/generate_subtitles.py — 字幕生成 (新增)

基于 Whisper 词级时间戳生成 SRT 字幕。

python3 scripts/generate_subtitles.py \
  --input <视频文件> \
  --output <subs.srt> \
  --mode <sentence|standard|word_chunk> \
  --style <default|netflix|douyin|bilibili|youtube|minimal>

字幕模式:

字幕风格预设：templates/subtitle_styles.json。

保留脚本 (增强)

scripts/cut_video.py

按时间轴剪切视频（支持 EDL JSON 输入）。

# 传统模式
python3 scripts/cut_video.py --input video.mp4 --start 10 --duration 30 --output clip.mp4
python3 scripts/cut_video.py --input video.mp4 --segments "0-30,60-90,120-150" --output ./clips/

# EDL 模式 (新增)
python3 scripts/cut_video.py --input video.mp4 --edl edl.json --output ./clips/

scripts/extract_highlights.py

双重维度高光提取：音频能量 + 场景检测。

python3 scripts/extract_highlights.py \
  --input <视频> \
  --num-clips <数量> \
  --min-duration <秒> \
  --output <目录> \
  [--transcript transcript.json]  # 新增：结合语义增强

scripts/burn_subtitles.py

可配置字幕风格烧录。

python3 scripts/burn_subtitles.py \
  --input <视频> \
  --srt <字幕.srt> \
  --output <输出.mp4> \
  [--style <风格预设>]          # 新增
  [--style-file styles.json]    # 新增

scripts/export_social.py

多平台短视频格式导出（保留）。

python3 scripts/export_social.py \
  --input <视频> \
  --format <vertical|square|horizontal> \
  --duration <秒> \
  --output <目录>

典型工作流

工作流 1: 从长视频/直播回放提取精华

# 1. 转录
python3 scripts/transcribe.py --input raw_video.mp4 --output transcript.json

# 2. 生成高光 EDL
python3 scripts/generate_edl.py \
  --transcript transcript.json \
  --strategy extract_highlights \
  --num-clips 5 \
  --output highlights_edl.json

# 3. 渲染
python3 scripts/render_edl.py \
  --edl highlights_edl.json \
  --output edit/highlights.mp4

# 4. 导出多平台版本
python3 scripts/export_social.py \
  --input edit/highlights.mp4 \
  --format vertical \
  --duration 60 \
  --output shorts/

工作流 2: 去口癖精修口播视频

# 1. 转录 (词级时间戳)
python3 scripts/transcribe.py \
  --input talking_head.mp4 \
  --output transcript.json

# 2. 生成去冗余 EDL
python3 scripts/generate_edl.py \
  --transcript transcript.json \
  --strategy remove_fillers \
  --output clean_edl.json

# 3. 生成字幕
python3 scripts/generate_subtitles.py \
  --input talking_head.mp4 \
  --output subs.srt \
  --mode sentence \
  --style netflix

# 4. 渲染 (带色彩校正 + 字幕)
python3 scripts/render_edl.py \
  --edl clean_edl.json \
  --output edit/final.mp4

# 5. 烧录字幕
python3 scripts/burn_subtitles.py \
  --input edit/final.mp4 \
  --srt subs.srt \
  --style netflix \
  --output edit/final_subtitled.mp4

# 6. 质量检查
python3 scripts/self_eval.py \
  --video edit/final_subtitled.mp4 \
  --edl clean_edl.json

工作流 3: 批量制作社交平台短视频

直接把需求告诉 AI Agent：

"帮我把 ~/Videos/tutorial.mp4 拆成 5 个 60 秒的抖音竖版短视频，每个视频有 hook 和 CTA，加字幕"

Agent 会自动：

1. 转录视频
2. 使用 social_clip 策略生成 EDL
3. 渲染每个片段
4. 横转竖裁切 + 字幕
5. 自检每个输出

环境要求

• 必须: FFmpeg (ffmpeg / ffprobe)
• 转录: openai-whisper 或 faster-whisper（pip install openai-whisper）
• 中文增强: FunClip / funasr（pip install funasr funclip，可选）
• 说话人分离: pyannote-audio（pip install pyannote.audio，可选，需 HuggingFace token）
• Python 3.9+

# 最小安装
pip install openai-whisper pyyaml

# 推荐安装 (全功能)
pip install openai-whisper faster-whisper pyyaml

# 中文增强
pip install funasr funclip

# 说话人分离 (可选)
pip install pyannote.audio

技术架构

双通道感知（借鉴 video-use）

Layer 1 — 结构化转译文本 (always loaded)
  词级时间戳 + 说话人 ID + confidence
  ~12KB per source → LLM 主要阅读窗口

Layer 2 — 按需视觉采样 (on demand)
  仅在决策点采样：模糊停顿、复拍对比、切点健康检查
  避免暴力逐帧 (30,000 frames → 45M tokens)

EDL 标准化 (借鉴 video-use)

EDL (Edit Decision List) 将编辑决策与渲染执行隔离:

• 可审计: 每次编辑有 start/end/reason/confidence
• 可回溯: 保存 edl.json，下次可重放
• 可干预: 用户审核后修改再渲染

Schema: templates/edl_schema.json

自检循环 (借鉴 video-use)

渲染后自动检查质量，发现问题自动修复（max 3 轮）。

模板目录

与 video-use 的对比改进