Auto Video Editor — 自动视频编辑器

自动视频剪辑（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：建议使用 WSL2 环境运行；支持 QSV/AMF 硬件编码
• 无独显 (集成显卡)：Intel iGPU 使用 QSV 编码，AMD iGPU 使用 AMF 编码；Whisper 建议 medium 模型（而非 large）
• 中国用户：自动检测中国区域，使用清华 pip 镜像和 HuggingFace 镜像下载模型，也可通过 --mirror 参数强制启用

工作流程（Workflow） Phase 0：Media Library Setup（素材库初始化） 首次使用时，帮助用户建立素材目录结构：

python3 scripts/media_library.py init [project_dir]

这会创建以下目录结构：

media/
├── raw/ — 原始素材（摄像机/手机直出的视频）
├── broll/ — B-roll 素材（城市街景、产品特写等）
├── bgm/ — 背景音乐（MP3/WAV/M4A）
├── assets/ — 叠加素材（水印 PNG、Logo 等）
└── output/ — 输出目录

询问素材来源： 询问用户的视频文件位置（本地路径、外部设备或云端） 建议将原始素材复制/移动到 media/raw/ 目录 询问是否有 B-roll、BGM 等辅助素材 如果用户视频散落在多个目录，建议先集中到 media/raw/ 扫描并建立索引：

python3 scripts/media_library.py scan [project_dir]

索引系统会自动：

• 扫描所有视频/音频/图片文件
• 提取时长、分辨率、帧率等元数据
• 关联已有的 transcript 文件
• 小型项目（< 200 文件）使用 JSON 索引（media_index.json）
• 大型项目自动升级为 SQLite 索引（media_index.db）

手动升级：python3 scripts/media_library.py upgrade 查看素材库状态：python3 scripts/media_library.py status 搜索素材：python3 scripts/media_library.py search "关键词"

Phase 1：Audio Extraction（音频提取） 对每个输入视频文件，使用 extract_audio.py 提取音频：

python3 scripts/extract_audio.py ""

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

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

python3 scripts/transcribe.py "" --model auto --language zh --detect-fillers

• --model auto：根据硬件自动选择最佳模型（NVIDIA GPU → large-v3，Apple Silicon → large-v3-turbo，集成显卡 → medium，纯 CPU → small）
• --engine auto：自动检测 faster-whisper（推荐）或 openai-whisper
• --mirror：中国用户使用镜像源下载模型
• --language：zh（中文），en（英文），ja（日文）等，也可省略让 whisper 自动检测
• --silence-threshold 1.0：静音检测阈值（秒），默认 1.0。设为 0 关闭
• --word-timestamps：启用逐词时间戳（卡拉OK字幕必需）
• --detect-fillers：检测填充词（中文：嗯/呃/那个/就是说；英文：um/uh/like/you know），标记纯填充词片段为建议跳过

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

{
  "segments": [
    {"id": 1, "start": 0.0, "end": 2.5, "text": "大家好"},
    {"id": 2, "start": 2.5, "end": 5.1, "text": "今天我们来聊一个话题"}
  ],
  "silences": [
    {"start": 15.2, "end": 18.5, "duration": 3.3, "before_segment": 5, "after_segment": 6}
  ],
  "filler_words": [
    {"segment_id": 3, "text": "嗯那个", "fillers_found": ["嗯", "那个"], "is_filler_only": true},
    {"segment_id": 7, "text": "就是说我觉得这个方案", "fillers_found": ["就是说"], "is_filler_only": false}
  ]
}

静音检测：transcribe.py 会自动分析相邻语音片段之间的间隙。超过阈值（默认 1 秒）的间隙会被标记为静音并输出到 silences 字段中。这些静音通常是说话人的停顿、卡壳或口误，在构建 render_config.json 选片时应注意避开这些区域。

Phase 2.5：Transcript Review（转录文字校验） 转录完成后，必须对所有 transcript.json 中的文字进行逐条审查，修正以下两类问题：

• 语音识别错误（ASR errors）：
• 专有名词/产品名：如 "opencloud" → "OpenClaw"、"cloudcode" → "Claude Code"、"cloud ops" → "Claude Opus"
• 同音字错误：如 "小红树" → "小红书"、"检映" → "剪映"、"断耕" → "断更"、"懒得讲" → "懒得剪"
• 英文拼写：如 "scale" → "skill"、"箱子" → "视频"
• 尾部幻觉：Whisper 有时在安静片段末尾生成无意义的重复文字，应直接删除
• 口误标记（Speaker errors）：
• 重复/卡壳：说话人重复说同一句话或卡住后重新说，标记为可跳过
• 乱码片段：语音模糊导致识别为无意义文字的片段（如连续的单字碎片），标记为可跳过

校验流程：

• 读取所有 transcript.json 的文字内容
• 逐条检查，列出发现的问题（原文 → 修正 或 标记为可跳过）
• 将修正列表展示给用户确认
• 用户确认后，直接修改 transcript.json 文件中的 text 字段
• 对于口误/乱码片段，在展示片段列表时（Phase 3）标注为建议跳过

注意：此步骤必须在 Phase 5（渲染）之前完成，因为字幕文字来源于 transcript.json。修正后再渲染，才能保证最终视频中的字幕文字正确。

Phase 3：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

如果有