video-full-process

用途

video-full-process 是一个统一工作流技能，把 video-clean 和 video-add-chapters 两个既有技能合并为一次运行。它面向需要端到端处理原始视频录像的场景：一次转写、去除停顿与填充词、检测并嵌入章节，并将章节时间戳重新映射到清理后的视频上，最终产出可直接用于 YouTube 的章节标记和逐章文档。

主要能力

只转写一次视频，复用转写结果，从而节省 API 成本。
去除视频中的停顿和填充词。
检测章节边界并嵌入章节。
将章节时间戳重新映射到清理后的视频。
生成 YouTube 章节标记和逐章文档。

使用方式

快速开始命令：

# Full processing with default settings
python process_video.py "video.mp4" --language ko

# Preview mode (see what will be changed)
python process_video.py "video.mp4" --preview

# Skip chapter embedding (only clean + generate docs)
python process_video.py "video.mp4" --no-embed-chapters

完整处理：

python process_video.py "presentation.mp4" --language ko

该命令依次执行：转写（若不存在）、章节检测、停顿去除、章节重映射、章节嵌入、文档生成。

部分处理：

# Skip transcription (reuse existing)
python process_video.py "video.mp4" --skip-transcribe

# Skip cleaning (only add chapters)
python process_video.py "video.mp4" --skip-clean

# Skip chapter embedding (only clean + generate docs)
python process_video.py "video.mp4" --no-embed-chapters

自定义：

# Adjust pause threshold
python process_video.py "video.mp4" --pause-threshold 0.8

# Custom output directory
python process_video.py "video.mp4" --output-dir "./output"

工作流概览

输入：raw_video.mp4

转写（一次）：使用分块转写，支持长视频（15 分钟以上），输出 transcript.json。
并行执行：2a 清理（输出 cleaned .mp4 与 pauses.json）；2b 检测章节（输出 chapters.json）。
将章节重映射到清理后的视频：计算被移除的时间，调整章节时间戳。
嵌入章节并生成文档：ffmpeg 元数据嵌入、YouTube 章节 txt、章节 markdown 文件。

输出：cleaned-chapters.mp4 及文档。

输出文件

{video} - cleaned.mp4：已去除停顿/填充词的视频。
{video} - cleaned-chapters.mp4：已嵌入章节的清理后视频。
{video} - pauses.json：被移除的停顿数据（用于重映射）。
{video} - chapters.json：检测到的章节边界。
{video} - chapters_remapped.json：为清理后视频调整过的章节。
{video} - youtube_chapters.txt：可复制粘贴到 YouTube 描述。
Chapter NN - Title.md：逐章文档。

章节重映射逻辑

当停顿被移除后，章节时间戳必须调整。示例：

原始视频： |--Ch1--|--pause--|--Ch2--|--pause--|--Ch3--| 0 30 40 60 70 90

清理后视频（停顿已移除）： |--Ch1--|--Ch2--|--Ch3--| 0 30 50 70

重映射：

Ch1: 0 → 0（无变化）
Ch2: 40 → 30（之前移除了 10 秒停顿）
Ch3: 70 → 50（之前共移除了 20 秒停顿）

remap_chapters.py 脚本会利用视频清理产生的停顿数据自动完成此操作。

与既有技能的集成

本技能编排两个既有技能：

video-clean（.claude/skills/video-cleaning/）：提供 transcribe_video.py、edit_video_remove_pauses.py；修改：新增 --output-pauses 标志。
video-add-chapters（Settings/Skills/video-add-chapters/）：提供 transcribe_video.py、suggest_chapters.py、generate_docs.py；修改：新增 --skip-if-exists 标志。

环境要求

系统：

Python 3.7+
FFmpeg（用于视频处理）

Python 包：

pip install openai

环境变量：

OPENAI_API_KEY：Whisper API 所需。

成本估算

单次转写：约 $0.006/分钟（若分开运行则为 $0.012/分钟）。
1 小时视频：约 $0.36（通过复用转写节省 $0.36）。

故障排除

“Transcript not found” 错误：先运行转写，或使用 --force-transcribe：

python process_video.py "video.mp4" --force-transcribe

“Chapter timestamps don't match”：重新生成重映射章节：

python remap_chapters.py "video - chapters.json" --pauses "video - pauses.json"

FFmpeg 嵌入失败：检查 chapters.json 格式是否正确：

{
  "chapters": [
    {"start": 0, "title": "Intro", "description": "..."},
    {"start": 120, "title": "Main", "description": "..."}
  ]
}

文件结构

video-full-process/
├── SKILL.md              # This documentation
├── process_video.py      # Main orchestrator script
└── remap_chapters.py     # Chapter timestamp remapping

版本历史

v1.0（2026-01）：初始发布；video-clean + video-add-chapters 统一工作流；转写复用（单次 API 调用）；自动章节重映射；FFmpeg 章节嵌入。

适用场景

端到端处理原始视频录像。
制作带嵌入章节的成品视频。
生成带章节标记的 YouTube 就绪内容。
同时需要停顿去除和章节组织的场景。

限制

资料未提供除上述之外的其他限制说明。