video-clip-extractor

视频片段提取技能

运行视频编排器来处理视频并提取精彩片段。

触发时

1. 获取来源 — 如果用户未提供视频 URL 或文件路径，请向其索取。
2. 明确意图（可选）— 如果用户希望片段聚焦于特定主题，请将其记录为 --user-intent。如果不清楚，请询问：“有没有想重点关注的特定主题或时刻？（例如‘搞笑时刻’、‘关键论点’）”
3. 检查环境 — 当前目录中是否存在 video_orchestrator.py？如果存在，直接运行。否则，使用全局安装路径 ~/.local/share/openclip。
4. 验证前置条件 — 检查是否已安装 ffmpeg，以及是否已设置至少一个 API 密钥。如果缺少，请在运行前提醒用户。
5. 运行命令并向用户实时输出结果。
6. 报告结果 — 完成后，列出生成的片段及其时间戳和标题。

设置（仅首次使用时）

运行前，确定执行环境：

1. 位于 openclip 仓库中 — 如果当前目录中存在 video_orchestrator.py，则跳过设置，直接运行。
2. 全局安装 — 如果 ~/.local/share/openclip 不存在，请执行以下步骤：

**前置条件：**必须已安装 git 和 uv。

• 如果未安装 uv，请安装：macOS：brew install uv · Linux/Windows：pip install uv

git clone https://github.com/linzzzzzz/openclip.git ~/.local/share/openclip
cd ~/.local/share/openclip && uv sync

之后更新 openclip：

git -C ~/.local/share/openclip pull && cd ~/.local/share/openclip && uv sync

执行

如果位于 openclip 仓库中（当前目录包含 video_orchestrator.py）：

uv run python video_orchestrator.py [options] <source>

如果全局运行（从其他任意目录运行）：

cd ~/.local/share/openclip && uv run python video_orchestrator.py -o "$OLDPWD/processed_videos" [options] <source>

$OLDPWD 会保存用户的原始目录，因此片段会保存到该目录，而不是 openclip 安装目录中。

其中，<source> 是视频 URL（Bilibili/YouTube）或本地文件路径（MP4、WebM、AVI、MOV、MKV）。

对于已有字幕的本地文件，请将 .srt 文件放在同一目录下，并使用相同的文件名（例如，video.mp4 → video.srt）。

运行前检查清单

• 位于 openclip 仓库中：从仓库根目录运行，以确保相对路径（例如 references/、prompts/）能够正确解析
• 必须安装 ffmpeg（生成所有片段都需要）：
  • macOS：brew install ffmpeg
  • Ubuntu：sudo apt install ffmpeg
  • Windows：从 ffmpeg.org 下载
  • 使用 --burn-subtitles 时：需要包含 libass 的 ffmpeg（详情请参阅 README）
• 设置一个 API 密钥：
  • QWEN_API_KEY（默认提供商：qwen），或
  • OPENROUTER_API_KEY（如果使用 --llm-provider openrouter），或
  • GLM_API_KEY（如果使用 --llm-provider glm），或
  • MINIMAX_API_KEY（如果使用 --llm-provider minimax）
• 使用 --speaker-references 时：运行 uv sync --extra speakers 并设置 HUGGINGFACE_TOKEN

CLI 参考

必需参数

参数	描述
source	视频 URL 或本地文件路径

可选项

标志	默认值	描述
-o, --output <dir>	processed_videos	输出目录
--max-clips <n>	5	高光片段的最大数量
--browser <browser>	firefox	用于读取 Cookie 的浏览器：chrome、firefox、edge、safari
--title-style <style>	fire_flame	标题样式：gradient_3d、neon_glow、metallic_gold、rainbow_3d、crystal_ice、fire_flame、metallic_silver、glowing_plasma、stone_carved、glass_transparent
--title-font-size <size>	medium	艺术标题的字体大小预设。选项：small（30px）、medium（40px）、large（50px）、xlarge（60px）
--cover-text-location <loc>	center	封面文字位置：top、upper_middle、bottom、center
--cover-fill-color <color>	yellow	封面文字填充颜色：yellow、red、white、cyan、green、orange、pink、purple、gold、silver
--cover-outline-color <color>	black	封面文字描边颜色：yellow、red、white、cyan、green、orange、pink、purple、gold、silver、black
--language <lang>	zh	输出语言：zh（中文）、en（英语）
--llm-provider <provider>	qwen	大模型提供商：qwen、openrouter、glm、minimax
--user-intent <text>	—	自由文本形式的关注点描述（例如“关于 AI 风险的片段”）。引导大模型优先选择与此主题相关的片段
--subtitle-translation <lang>	—	烧录前将字幕翻译成此语言（例如 "Simplified Chinese"）。需要 --burn-subtitles 和 QWEN_API_KEY
--speaker-references <dir>	—	说话人分离所用的参考 WAV 文件目录（每位说话人一个，文件名 = 说话人姓名）。需要 uv sync --extra speakers 和 HUGGINGFACE_TOKEN
-f, --filename <template>	—	yt-dlp 模板：%(title)s、%(uploader)s、%(id)s 等。

标志

标志	描述
--force-whisper	忽略平台字幕，使用 Whisper
--skip-download	使用已下载的视频
--skip-transcript	跳过转录文本生成，使用现有的转录文本文件
--skip-analysis	跳过分析，使用现有的分析文件生成片段
--use-background	在分析提示词中包含背景信息（主播姓名/昵称）
--skip-clips	跳过片段生成
--add-titles	为片段添加艺术标题（默认禁用）
--skip-cover	跳过封面图片生成
--burn-subtitles	将 SRT 字幕烧录到视频中。输出位于 clips_post_processed/。需要支持 libass 的 ffmpeg
-v, --verbose	启用详细日志
--debug	导出发送给大模型的完整提示词（保存到 debug_prompts/）

自定义文件名模板（-f）

使用 yt-dlp 模板语法。常用变量：%(title)s、%(uploader)s、%(upload_date)s、%(id)s、%(ext)s、%(duration)s。

示例：-f "%(upload_date)s_%(title)s.%(ext)s"

环境变量

根据所选的 --llm-provider 设置相应的 API 密钥：

• QWEN_API_KEY — 用于 --llm-provider qwen
• OPENROUTER_API_KEY — 用于 --llm-provider openrouter
• GLM_API_KEY — 用于 --llm-provider glm
• MINIMAX_API_KEY — 用于 --llm-provider minimax

工作流

编排器会自动运行以下流程：

1. 下载 — 获取视频和平台字幕（Bilibili/YouTube），或接受本地文件
2. 分割 — 将超过内置阈值的视频拆分为多个片段，以便并行分析
3. 转录 — 使用平台字幕或 Whisper AI；--force-whisper 可强制使用 Whisper
4. 分析 — 大模型为转录文本片段的吸引力评分；--user-intent 可引导选择
5. 生成片段 — 使用 ffmpeg 在识别出的时间戳处剪辑视频
6. 添加标题（可选）— 使用 --title-style 渲染艺术化文字叠加层
7. 生成封面 — 为每个片段创建缩略图

使用 --skip-clips、--skip-cover 跳过指定步骤。使用 --add-titles 启用艺术化标题。使用 --skip-download 和 --skip-analysis 从中间结果恢复执行。

输出示例

成功运行后，结果如下：

✅ Processing complete — 5 clips generated
📁 processed_videos/video_name/clips/

  clip_01.mp4  [00:12:34 – 00:15:20]  "Title of the moment"
  clip_02.mp4  [00:28:45 – 00:31:10]  "Another highlight"
  clip_03.mp4  [00:45:00 – 00:47:30]  "Key discussion point"
  ...

Cover images: clips/*.jpg

输出结构

processed_videos/{video_name}/
├── downloads/              # Original video, subtitles, and metadata (URL sources)
├── local_videos/           # Copied video and subtitles (local file sources)
├── splits/                 # Split parts and AI analysis results
├── clips/                  # Generated highlight clips + cover images
└── clips_post_processed/   # Post-processed clips when using --add-titles and/or --burn-subtitles

选项选择指南

Whisper 模型 — 默认的 base 适用于音频清晰的情况。背景噪声较多、说话者较多或口音明显时，使用 small。需要兼顾速度和准确性时，使用 turbo。仅在转录质量至关重要时使用 large/medium。

--force-whisper — 平台字幕为自动生成（通常不准确）、出现“未找到吸引人的片段”或内容使用非母语且平台字幕不可靠时使用。

--use-background — 适用于有固定人物（主播、主持人）且昵称和社区相关内容很重要的情况。该选项会读取 prompts/background/background.md。

多片段分析 — 拆分后的视频会按片段分别分析，然后汇总所有片段中最吸引人的前 5 个时刻。

--user-intent — 在按片段分析和跨片段汇总阶段引导大模型选择片段。若要查找特定主题的片段（例如“AI 安全预测”“搞笑时刻”），此选项会很有用。

--burn-subtitles — 将 SRT 字幕直接嵌入视频画面。若希望字幕始终可见（例如用于社交媒体），请使用此选项。与 --subtitle-translation 一起使用，可在原字幕下方添加翻译字幕轨道。

--speaker-references — 为访谈/播客启用说话人分离。提供包含 10–30 秒清晰 WAV 音频片段的目录（每位说话人一个），并以说话人姓名命名（例如 references/Host.wav）。

故障排除

错误	解决方法
“找不到 ffmpeg”／片段生成悄无声息地失败	安装 ffmpeg：brew install ffmpeg（macOS）或 sudo apt install ffmpeg（Ubuntu）
“未提供 API 密钥”	设置 QWEN_API_KEY、OPENROUTER_API_KEY、GLM_API_KEY 或 MINIMAX_API_KEY 环境变量
“视频下载失败”	检查网络/URL；尝试使用其他 --browser；或使用本地文件
“转录生成失败”	尝试使用 --force-whisper 或检查音频质量
“未找到吸引人的片段”	尝试使用 --force-whisper，以提高转录准确性
“片段生成失败”	确认分析已完成；检查是否存在分析文件