openclaw-video-highlight

name	openclaw-video-highlight
description	当用户希望分析视频主题、寻找高光时刻、突出吸睛片段、用 ffmpeg 裁剪高光并生成字幕文件（.srt）时使用。触发词：openclaw skill, video highlight, short clip, highlight reel, subtitle generation, ffmpeg editing。

OpenClaw 视频高光技能

目标

构建一个端到端的视频高光剪辑流程：

1. 分析输入视频并推断核心主题。
2. 选出最能吸引注意力的高光片段。
3. 通过 ffmpeg 对高光片段进行裁剪与拼接。
4. 生成与最终高光成片时间线对齐的字幕文件。

输入

• 源视频路径。
• 可选目标平台（抖音、Bilibili、YouTube Shorts、Reels）。
• 可选成片时长目标（例如 30-90 秒）。
• 可选风格目标（动感、信息向、情绪向、戏剧化）。

输出

• highlights.json：已选高光片段及其入选原因。
• highlight_reel.mp4：最终拼接完成的高光视频。
• highlight_reel.srt：与最终成片时间线对齐的字幕文件。
• 可选 analysis_report.md：每个片段的筛选依据说明。

自动分析脚本

使用 assets/analyze_highlights.py 自动生成 highlights.json。

命令

python .github/skills/openclaw-video-highlight/assets/analyze_highlights.py `
   --input "path/to/input.mp4" `
   --output-json "path/to/highlights.json" `
   --output-report "path/to/analysis_report.md" `
   --topic "可选：视频主题" `
   --transcript-srt "path/to/full_transcript.srt" `
   --min-count 4 `
   --min-gap 0.8 `
   --qwen-model "qwen-vl-max-latest"

功能说明

1. 使用滑动时间窗与字幕锚点生成候选片段（不使用 CV 场景切换算法）。
2. 每个候选片段抽取多帧画面，并将画面+字幕上下文送入 Qwen 多模态模型。
3. 由 Qwen 输出画面冲击力、情绪强度、主题相关性、信息密度、钩子强度等维度评分。
4. 根据 Qwen 给出的建议起止偏移微调片段边界并生成标题/理由。
5. 导出互不重叠的已选高光片段。

片段筛选原则

使用以下标准对候选片段进行排序：

1. 主题相关性：片段是否强支撑核心主题。
2. 信息密度：是否包含明确价值点、结果兑现或关键揭示。
3. 情绪或视觉峰值：是否出现惊喜、冲突、幽默、反转或明显画面变化。
4. 钩子潜力：前 1-3 秒是否能快速抓住注意力。
5. 去冗余控制：避免多个片段表达重复信息。

推荐工作流

1. 检查媒体信息：
   • 使用 ffprobe 读取时长、fps、音轨和分辨率。
2. 构建字幕文本：
   • 若没有字幕，运行 Whisper/faster-whisper 生成 full_transcript.srt。
3. 提议候选片段：
   • 结合字幕分段与视觉事件线索（转场、运动峰值、响度峰值）。
4. 评分并筛选：
   • 片段时长通常控制在 3 秒到 15 秒。
   • 优先组合“开场钩子 + 价值峰值 + 结果兑现”。
5. 导出方案：
   • 按以下结构将已选片段保存为 highlights.json：

{
  "input_video": "input.mp4",
  "segments": [
    {
      "start": 12.4,
      "end": 20.9,
      "title": "意外反转揭示",
      "reason": "核心主题兑现且画面变化强烈",
      "score": 0.91
    }
  ]
}

6. 裁剪与拼接：
   • 运行 assets/highlight_pipeline.py 中的辅助脚本。
7. 生成字幕：
   • 若存在 full_transcript.srt，将字幕重映射到新的高光时间线。
   • 否则使用片段标题生成兜底字幕提示。

必需命令

在工作区根目录执行：

本地独立测试脚本（不依赖 OpenClaw 命令入口）

可直接运行工作区根目录下的 local_video_pipeline_test.py：

# 单入口全流程：仅传 mp4
# 要求同目录存在同名配文（.txt/.md/.copy.txt）
python local_video_pipeline_test.py `
   --input-video "path/to/input.mp4" `
   --output-duration 45 `
   --qwen-api-key "your_api_key"

说明：

1. 脚本会自动执行：高光分析 -> 高光剪辑字幕 -> 竖版包装（标题与摘要字幕）。
2. 同名配文会同时参与字幕与标题生成。
3. --output-duration 可直接控制最终高光成片总时长（秒）。

第 1 步：自动生成高光规划

python .github/skills/openclaw-video-highlight/assets/analyze_highlights.py `
   --input "path/to/input.mp4" `
   --output-json "path/to/highlights.json" `
   --output-report "path/to/analysis_report.md" `
   --topic "可选：视频主题" `
   --transcript-srt "path/to/full_transcript.srt" `
   --segment-length 8 `
   --stride 4.4 `
   --max-analyze-windows 24 `
   --output-duration 60 `
   --frame-count 3 `
   --qwen-model "qwen-vl-max-latest"

Qwen API Key（必需）：

$env:QWEN_API_KEY="your_api_key"

或在工作区根目录创建 .env（会被脚本自动读取）：

QWEN_API_KEY=your_api_key

说明：

1. API Key 可通过 --qwen-api-key 传入，或使用环境变量/.env 的 QWEN_API_KEY / DASHSCOPE_API_KEY。
2. 也可以在 assets/qwen_global_config.py 中配置 QWEN_API_KEY_GLOBAL，供多个脚本全局复用。
3. 当前高光分析完全依赖 Qwen 多模态能力，不再回退到旧的 CV 评分逻辑。

第 2 步：裁剪并生成字幕

python .github/skills/openclaw-video-highlight/assets/highlight_pipeline.py `
  --input "path/to/input.mp4" `
  --segments "path/to/highlights.json" `
  --output-video "path/to/highlight_reel.mp4" `
  --output-srt "path/to/highlight_reel.srt" `
   --transcript-srt "path/to/full_transcript.srt" `
   --copy-dir "path/to/folder_with_copy" `
   --subtitle-mode "summary" `
   --subtitle-style "news"

字幕模式：

1. summary（默认）：剪辑后结合同名文案（.txt/.md）与字幕内容生成摘要字幕。
2. remap：将原始字幕提示重映射到高光时间线。
3. fallback：仅使用片段标题生成字幕。
4. auto：优先 summary，失败则 remap，最后回退到标题模式。

字幕风格：

1. entertainment / 娱乐风格
2. info / 资讯风格
3. news / 新闻风格
4. neutral（默认）

第 3 步：结合文案与字幕进行批量竖屏包装

当你有一个包含视频与同名文案文件（.txt / .md）的目录时，使用该步骤。

python .github/skills/openclaw-video-highlight/assets/vertical_package_pipeline.py `
   --input-dir "path/to/folder_with_videos" `
   --output-dir "path/to/output_folder" `
   --title-style-template "cctv" `
   --subtitle-style "news" `
   --title-anchor-ratio 0.22 `
   --qwen-enable `
   --qwen-model "qwen-plus-latest"

可选：直接通过参数传入 API Key

python .github/skills/openclaw-video-highlight/assets/vertical_package_pipeline.py `
   --input-dir "path/to/folder_with_videos" `
   --output-dir "path/to/output_folder" `
   --qwen-enable `
   --qwen-api-key "your_api_key"

行为说明：

1. 输出格式固定为竖屏（1080x1920）。
2. 横屏源视频会加蓝色底层，标题位于顶部。
3. 竖屏源视频保持原视频风格，标题叠加在视频上。
4. 字幕来源优先级：同名 SRT -> whisper 自动 ASR -> 文案兜底 SRT。
5. 最终输出阶段会调用 ffmpeg 将字幕硬编码到 .vertical.mp4 画面中（默认不再输出旁挂 SRT）。
6. 如需保留旁挂字幕文件，可额外传入 --keep-sidecar-srt。
7. 标题渲染带边界保护，避免文本超出画面。
8. 长标题在必要时自动换行成两行。
9. 默认标题字体统一为方正大黑简体；可用 --font 覆盖。
10. 标题由文案与视频内容线索（字幕/转写）联合生成，而非仅使用文案。
11. 标题块默认位于 1080x1920 画面上方约六分之一处。
12. --title-anchor-ratio 可在上方区域内调整标题块的纵向位置（上移/下移）。
13. 启用 --qwen-enable 后，会调用 Qwen API 综合分析视频关键帧、配文与字幕线索，生成标题与摘要字幕文案。

标题样式模板：

1. single（默认）：单行标题。
2. cctv：双行标题样式（黄色主标题 + 白色副标题）。

长标题处理规则：

1. 如果未显式提供副标题且主标题过长，会自动换成两行显示。
2. 自动换行后的第二行与第一行保持同色，保证视觉一致性。

代理行为规则

• 始终解释每个入选片段为何具备吸引力。
• 确保总输出时长符合用户约束。
• 尽可能在关键语音边界处进行干净切点。
• 避免选择信息量低的过渡填充片段。
• 如果置信度不足，提供两套方案（conservative 与 aggressive）供用户选择。

约束条件

• 需要在 PATH 中可用 ffmpeg 与 ffprobe。
• 生成字幕文本时，需要 Whisper/faster-whisper 或已有字幕文件。
• 运行高光分析时，需要可用的 Qwen API Key 与联网能力。
• 本技能不会上传媒体，全部处理均在本地完成。