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  
  --model  
  --language  
  --diarize 
  --format  
  --output <输出文件>

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

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

python3 scripts/generate_edl.py 
  --transcript  
  --strategy  
  --output 

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

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

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

python3 scripts/render_edl.py 
  --edl  
  --output  
  [--segments] 
  [--dry-run]

渲染特性:

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

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

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

python3 scripts/self_eval.py 
  --video  
  --edl  
  --output 

检查项:

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

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

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

python3 scripts/generate_subtitles.py 
  --input <视频文件> 
  --output  
  --mode  
  --style 

字幕模式:

字幕风格预设：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  
  --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 的对比改进