Auto Video Editing（自动视频剪辑）

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

Prerequisites（前置要求）

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

bash
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 脚本前先激活：

bash
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 提取音频：

bash
python3 scripts/extract_audio.py "<video_path>"

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

Phase 2: Speech Recognition（语音识别）

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

bash
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 文件，格式如下：

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 根据转录结果将视频切分为独立片段：

bash
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 为每个片段烧录字幕：

bash
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 将用户选择的片段合成为最终视频：

bash
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 分钟学会拍小红书封面」而非「我今天教大家拍封面」

1. 确认标题后，使用 generate_cover.py 将封面写入视频：

bash
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 在视频上叠加章节时间轴：

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

自动行为：

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

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

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

chapters.json 格式：

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 重新切分相关片段

Important Notes（注意事项）

1. 精确切割：视频切分使用重编码模式（非 stream copy），确保音频在句子边界精确切断，避免相邻片段出现重复的尾音。
2. 多视频处理：如果用户提供多个视频，对每个视频独立执行 Phase 1-3.5，然后在 Phase 4 统一展示所有视频的片段列表，支持跨视频混合选择片段。
3. 识别模型选择：中文视频建议使用 large 模型，base/small 模型中文识别率较低。large 模型约需 2.9GB 下载空间。
4. 工作目录：所有中间文件（音频、转录、片段）都保存在视频文件所在目录下，便于管理。
5. 错误处理：如果某一步失败，向用户报告具体错误信息，并建议可能的解决方案。
6. 字幕字体：ffmpeg 需要编译包含 libass 和 libfreetype。macOS 可通过 brew install ffmpeg 获取。
7. 竖屏适配：字幕位置和字体大小已针对 9:16 竖屏视频（如小红书、抖音）优化。横屏视频同样支持。
8. 速度调整：如需调整播放速度，可使用 ffmpeg：

bash ffmpeg -i input.mp4 -filter_complex "[0:v]setpts=PTS/1.25[v];[0:a]atempo=1.25[a]" -map "[v]" -map "[a]" -c:v libx264 -preset fast -crf 18 -c:a aac -b:a 192k output_1.25x.mp4

FAQ / Troubleshooting（常见问题诊断）

遇到错误时，先运行环境诊断：

bash
python3 scripts/utils.py

Q1: No such filter: 'drawtext' 或 No such filter: 'ass'

原因：ffmpeg 编译时未包含 libfreetype（drawtext 所需）或 libass（字幕所需）。

诊断：

bash
ffmpeg -hide_banner -filters 2>/dev/null | grep -E "drawtext|ass|subtitles"

如果无输出，说明缺少对应滤镜。

解决：

• macOS：标准 brew install ffmpeg 可能不包含这些库。使用第三方 tap 安装完整版：

bash brew tap homebrew-ffmpeg/ffmpeg brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-fdk-aac 该 tap 默认启用 --enable-libfreetype --enable-libass --enable-libfontconfig。

• Linux/WSL：apt install ffmpeg 通常已包含。如果缺少，安装开发依赖后从源码编译：

bash sudo apt install libfreetype6-dev libfontconfig1-dev libass-dev

• 影响范围：缺少 drawtext 时，字幕烧录（burn_subtitles.py）、封面文字（generate_cover.py）和章节标题标签会失败或自动降级。章节进度条的色块和播放头不受影响（仅使用 drawbox）。

Q2: Undefined constant or missing '(' in 'iw*0.5-tw/2'

原因：ffmpeg drawtext 的 x 表达式中使用了 tw（text width），但某些 ffmpeg 版本中 tw 在 x 参数的上下文中不可用。

解决：脚本已修复此问题（使用像素值 {pixel_x}-text_w/2 代替 iw*{frac}-tw/2）。如果你修改了脚本并遇到此错误，请使用 text_w 而非 tw，并确保 x 表达式中不包含 iw* 动态计算。

Q3: Invalid alpha value specifier '%{eif:...}' (drawtext fontcolor)

原因：试图在 fontcolor 参数中嵌入 %{eif} 表达式来实现透明度渐变，但 ffmpeg 不支持在颜色值中使用此语法。

解决：使用 drawtext 的 alpha 参数（独立于 fontcolor），而非试图在 fontcolor=white@'%{eif:...}' 中嵌入表达式。正确写法：

drawtext=text='hello':fontcolor=white:alpha='if(lt(t,1),t,1)'

错误写法（会报错）：

drawtext=text='hello':fontcolor=white@'%{eif:if(lt(t,1),t,1):d:2}'

Q4: ffmpeg 硬件编码器失败 (h264_videotoolbox / h264_nvenc / h264_qsv 报错)

原因：检测到的硬件编码器不支持当前的视频参数（如特殊分辨率、色彩空间），或驱动版本不兼容。

诊断：

bash
ffmpeg -encoders 2>/dev/null | grep -E "nvenc|videotoolbox|qsv|amf"

解决：在脚本命令后添加 --force-cpu 参数（如脚本支持），或手动替换编码参数。也可以在 scripts/utils.py 中临时修改 get_ffmpeg_encoder() 函数，让它直接返回 ("libx264", ["-preset", "fast", "-crf", "18"])。

Q5: 中文字幕显示为方框（豆腐块）

原因：系统中没有可用的中文字体文件。

诊断：

bash
python3 -c "from scripts.utils import find_chinese_font; print(find_chinese_font())"

如果返回 (None, ...)，说明未找到中文字体。

解决：

• macOS：系统自带 PingFang SC，一般不会出现此问题。
• Linux/WSL：安装中文字体包：

bash sudo apt install fonts-noto-cjk

• WSL 备选：脚本会自动尝试 /mnt/c/Windows/Fonts/msyh.ttc（微软雅黑），前提是 Windows 已安装该字体。
• 手动指定：使用 --font-path /path/to/your/font.ttf 参数。
• 自动下载：脚本首次运行时会尝试从 Google Fonts（中国用户使用 jsDelivr CDN）下载 Noto Sans SC，缓存到 fonts/ 目录。

Q6: Whisper 模型下载失败 / 超时

原因：网络问题，尤其是中国用户无法访问 HuggingFace。

解决：

• 使用 --mirror 参数：python3 scripts/transcribe.py audio.wav --mirror --model auto
• 或手动设置环境变量：

bash export HF_ENDPOINT=https://hf-mirror.com

• 使用 faster-whisper 时，模型从 HuggingFace 下载；设置 HF_ENDPOINT 后会自动走镜像。
• 使用 openai-whisper 时，模型从 GitHub 下载，中国用户可能需要代理。建议改用 faster-whisper。

Q7: pip install faster-whisper 安装失败 / 超时

解决：中国用户使用清华镜像：

bash
pip install faster-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

Q8: WSL 环境下 ffmpeg 找不到或版本过旧

诊断：

bash
which ffmpeg && ffmpeg -version | head -1

解决：

bash
sudo apt update && sudo apt install ffmpeg

如果系统源的 ffmpeg 版本过旧（< 4.0），使用 PPA：

bash
sudo add-apt-repository ppa:savoury1/ffmpeg4
sudo apt update && sudo apt install ffmpeg