Video Editing

Auto Video Editing（自动视频剪辑）

根据语音内容，将口播/脱口秀类视频按句子自动切分，然后按用户选择合成带字幕的最终视频。

Prerequisites（前置要求）

在执行任何操作之前，先运行环境检测：

python3 scripts/utils.py

这会自动检测平台（macOS/Linux/WSL/Windows）、GPU 类型、可用编码器、Whisper 引擎，并给出诊断报告。

如果缺少依赖，提示用户安装：

• ffmpeg: brew install ffmpeg（macOS）或 apt install ffmpeg（Linux/WSL）或下载 Windows 版本
• whisper: pip install faster-whisper（推荐，速度快 4 倍）或 pip install openai-whisper
• 中国用户加速安装：pip install faster-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple

如果项目根目录有 .venv 虚拟环境，运行 Python 脚本前先激活：

source .venv/bin/activate  # macOS/Linux/WSL
# Windows: .venv\Scripts\activate

平台说明

• macOS (Apple Silicon): 自动使用 VideoToolbox 硬件编码加速，Whisper 推荐 large-v3-turbo 模型
• macOS (Intel): 使用 VideoToolbox 编码，Whisper 使用 CPU 模式
• Linux: 自动检测 NVIDIA GPU (NVENC)、Intel QSV、AMD AMF
• WSL: 支持，自动检测 Windows 字体路径 (/mnt/c/Windows/Fonts/)
• Windows: 建议使用 WSL2 环境运行；支持 QSV/AMF 硬件编码
• 无独显 (集成显卡): Intel iGPU 使用 QSV 编码，AMD iGPU 使用 AMF 编码；Whisper 建议 medium 模型（而非 large）
• 中国用户: 自动检测中国区域，使用清华 pip 镜像和 HuggingFace 镜像下载模型，也可通过 --mirror 参数强制启用

Workflow（工作流程）

Phase 1: Audio Extraction（音频提取）

对每个输入视频文件，使用 extract_audio.py 提取音频：

python3 scripts/extract_audio.py "<video_path>"

输出：与视频同目录下的 <video_name>_audio.wav 文件。

Phase 2: Speech Recognition（语音识别）

使用 transcribe.py 对音频进行语音识别，生成带时间戳的逐句文本：

python3 scripts/transcribe.py "<audio_path>" --model auto --language zh

• --model auto：根据硬件自动选择最佳模型（NVIDIA GPU → large-v3，Apple Silicon → large-v3-turbo，集成显卡 → medium，纯 CPU → small）
• 也可手动指定：tiny, base, small, medium, large-v3, large-v3-turbo
• --engine auto：自动检测 faster-whisper（推荐）或 openai-whisper
• --mirror：中国用户使用镜像源下载模型
• --language：zh（中文），en（英文），ja（日文）等，也可省略让 whisper 自动检测

输出：与音频同目录下的 <video_name>_transcript.json 文件，格式如下：

{
  "segments": [
    {"id": 1, "start": 0.0, "end": 2.5, "text": "大家好"},
    {"id": 2, "start": 2.5, "end": 5.1, "text": "今天我们来聊一个话题"}
  ]
}

转录后检查：如果文本中有明显的识别错误（如产品名、专有名词），应修正 transcript.json 中的文字后再进行后续步骤。

Phase 3: Video Splitting（视频切分）

使用 split_video.py 根据转录结果将视频切分为独立片段：

python3 scripts/split_video.py "<video_path>" "<transcript_json_path>"

输出：在视频同目录下创建 <video_name>_clips/ 文件夹，包含按句子编号命名的片段文件，如 clip_001.mp4, clip_002.mp4 等。

注意：

• 默认 padding 为 0（片段间无重叠），避免合成时出现重复音频。
• 使用精确重编码切割（-ss 后置 + re-encode），确保音频在句子边界精确切断。

Phase 3.5: Subtitle Burning（字幕烧录）

使用 burn_subtitles.py 为每个片段烧录字幕：

python3 scripts/burn_subtitles.py "<clips_dir>" "<transcript_json_path>"

字幕行为：

• 自动检测语言：中文内容自动使用中文字幕，英文内容使用英文字幕。
• 自动折行：长字幕自动分成两行，不会超出屏幕边界。
• 竖屏优化：字体大小按短边（宽度）缩放，字幕位置在画面 72% 高度处，适配小红书等竖屏平台。
• 中文字体优先级：
  1. 首先尝试从 Google Fonts 下载 Noto Sans SC（会缓存到 skill 的 fonts/ 目录）
  2. 如果下载失败，macOS 使用 PingFang SC（苹方）；Windows 使用 Microsoft YaHei（微软雅黑）
• 可用 --font-path 指定自定义字体文件
• 可用 --font-size 调整字号（默认 48，基于 1080p 自动缩放）

输出：<video_name>_clips_subtitled/ 目录，包含带字幕的片段。

注意：此步骤完成后，Phase 4-5 中应使用 _clips_subtitled/ 目录而非 _clips/ 目录。

Phase 4: User Interaction（用户交互）

展示片段列表给用户，格式如下：

视频片段列表：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  #   | 时间区间          | 内容
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1   | 00:00.0 - 00:02.5 | 大家好
  2   | 00:02.5 - 00:05.1 | 今天我们来聊一个话题
  3   | 00:05.1 - 00:08.3 | 这个话题非常有意思
  ...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

请选择要合成的片段（示例）：
  - 连续范围：1-10
  - 多个片段：1,3,5,7
  - 混合选择：1-4,6,8-10

如果有多个视频文件，分别展示每个视频的片段列表，让用户跨视频选择。 选好后可将来自不同视频的片段复制到同一个临时目录中，按顺序重新编号后合成。

等待用户回复选择后，进入 Phase 5。

Phase 5: Merge & Export（合成导出）

使用 merge_clips.py 将用户选择的片段合成为最终视频：

python3 scripts/merge_clips.py "<clips_dir>" --select "1-4,6,8" --output "<output_path>"

• --select：用户选择的片段编号，支持 1-4（范围）、1,3,5（逐个）、1-4,6,8-10（混合）。
• --output：输出文件路径，默认为 <clips_dir>/../<video_name>_final.mp4。

输出：合成后的最终视频文件。

Phase 6: Cover Generation（封面生成）

合成完成后，为视频生成封面图片。

交互流程：

1. 询问用户是否要为视频命名以及封面标题怎么写。
2. 如果用户提供了标题，直接使用该标题。
3. 如果用户没有特别要求，先从 transcript JSON 中读取所有句子文本，然后 站在观众的角度 总结出一个吸引人的封面标题：
   • 标题应简短有力（建议 6-15 个字）
   • 从观众视角出发，突出视频的核心看点或价值
   • 例如：「3 分钟学会拍小红书封面」而非「我今天教大家拍封面」
4. 确认标题后，使用 generate_cover.py 将封面写入视频：

python3 scripts/generate_cover.py "<final_video_path>" --title "封面标题文字" --transcript "<transcript_json_path>"

• --title：封面上显示的标题文字
• --transcript：转录 JSON 路径（当未提供 --title 时，脚本会输出全文供 AI 总结）
• --font-path：可选，指定自定义字体
• --output：可选，指定输出路径，默认为 <video_name>_with_cover.mp4

注意：

• 封面标题会自动过滤特殊字符和 emoji，避免乱码。
• 脚本会提取视频第一帧，叠加白色粗体标题文字（带黑色描边和阴影），然后将这一帧替换回视频的第一帧，生成新的视频文件。原视频不会被修改。
• 中文字体使用与字幕相同的查找逻辑（Google Noto Sans SC > 系统字体）。

输出：<video_name>_with_cover.mp4

Phase 7: Chapter Timeline Bar（章节时间轴）

为最终视频添加可视化的章节进度条。

使用 add_chapter_bar.py 在视频上叠加章节时间轴：

python3 scripts/add_chapter_bar.py "<video_path>" --transcript "<transcript_json_path>"

自动行为：

• 根据 transcript 自动将视频分为若干章节（每章约 15-30 秒，最多 8 章）
• 每章使用不同颜色的色块，带白色播放进度指示
• 章节切换时自动显示章节标题（3 秒后淡出）
• 横屏视频：时间轴在视频底部，章节标题在时间轴上方
• 竖屏视频：时间轴在视频顶部（避开底部平台 UI），章节标题在时间轴下方

也可以提供自定义章节 JSON：

python3 scripts/add_chapter_bar.py "<video_path>" --chapters chapters.json

chapters.json 格式：

{
  "chapters": [
    {"title": "开场", "start": 0.0, "end": 15.0},
    {"title": "正题", "start": 15.0, "end": 60.0}
  ]
}

参数说明：

• --transcript：从转录 JSON 自动生成章节
• --chapters：使用自定义章节 JSON
• --style color（默认）：彩色分段，每章不同颜色
• --style mono：单色风格，灰白交替，更简约
• --max-chapters：自动分章的最大章节数（默认 8）
• --font-path：自定义字体
• --output：输出路径，默认为 <video_name>_chapters.mp4

输出：<video_name>_chapters.mp4，同时在终端打印 YouTube 兼容的章节时间戳。

Phase 8: Post-merge Validation（合成后验证）

合成完成后，对最终视频执行一次验证流程：

1. 提取最终视频的音频
2. 重新进行语音识别
3. 检查识别结果中是否存在相邻片段的文字重复（前一句末尾 2-3 个字与后一句开头重复）
4. 如发现技术性重复（非自然语言重复），需要回到 Phase 3 重新切分相关片段