html-video

html-video — 模板驱动视频生成

概述

基于 html-video 引擎的视频生成技能。核心能力：

• 23+ 模板库：覆盖标题动画、数据可视化、产品宣传、结尾 CTA、社交短视频等场景
• 多画面比例：9:16、16:9、1:1、4:5 等
• Content-Graph IR：结构化分镜（nodes + edges + topo-sort）
• 确定性渲染：animation freeze → font loading → duration probe → Chromium 录制 → ffmpeg 编码
• 全项目导出：逐帧渲染 → 帧拼接 → 音频混合（ducking + fades）

TTS/BGM 说明：音频生成由 openclaw 的 MiniMax 扩展提供（speech-2.8-hd / music-2.6），不使用 html-video 内置的 MiniMax provider。生成后的音频文件作为项目资产注入 html-video 的 applySoundtrack。

CLI 调用

⚠️ 调用规范（必须遵守）

• 必须通过 ./skills/html-video/scripts/hv.sh <command> 调用，hv.sh 内部自动解析 CLI 路径并 exec node
• 禁止直接 node .../bin.js — 路径易错且绕过 allowlist
• 禁止 python3 .../bin.js — bin.js 是 ESM JavaScript，不是 Python 脚本
• 禁止 bash hv.sh 或绝对路径调用 — 使用工作区相对路径 ./skills/html-video/scripts/hv.sh
• 禁止直接 ffmpeg / ffprobe — 由 hv.sh 内部 subprocess 调用，agent 直接调有 CPU 卡死风险

所有操作通过 hv.sh 包装脚本调用：

# 环境检查
./skills/html-video/scripts/hv.sh doctor

# 模板搜索
./skills/html-video/scripts/hv.sh search-templates --intent "title animation"

# 查看模板详情
./skills/html-video/scripts/hv.sh inspect-template frame-glitch-title

# 项目管理
./skills/html-video/scripts/hv.sh project-create --name "my-video" --aspect "9:16"
./skills/html-video/scripts/hv.sh project-set-template <project-id> --template <template-id>
./skills/html-video/scripts/hv.sh project-set-var <project-id> --key title --value '"文案"'
./skills/html-video/scripts/hv.sh project-set-var <project-id> --key duration_sec --value 4

# 渲染
./skills/html-video/scripts/hv.sh project-render <project-id> --output /path/to/output.mp4

# 项目查询
./skills/html-video/scripts/hv.sh project-list
./skills/html-video/scripts/hv.sh project-show <project-id>

画面比例

创建项目时通过 --aspect 指定，未指定默认 9:16。

工作流

1. Content-Graph 生成

分析脚本内容，自行决定分段，生成 content-graph.json：

{
  "schemaVersion": 1,
  "intent": "promo",
  "synopsis": "视频概要",
  "nodes": [
    {
      "id": "hook-title",
      "kind": "text",
      "frameIntent": "intro",
      "durationSec": 4,
      "templateRef": "frame-glitch-title",
      "variables": { "title": "...", "subtitle": "..." },
      "hasTts": true,
      "ttsText": "配音文案"
    },
    {
      "id": "product-clip",
      "kind": "entity",
      "frameIntent": "image-pan",
      "durationSec": 8,
      "templateRef": "video-clip-916",
      "variables": { "videoSrc": "assets/clip.mp4" },
      "hasTts": true,
      "ttsText": "产品介绍文案"
    }
  ],
  "edges": [
    { "from": "hook-title", "to": "product-clip", "kind": "sequence" }
  ]
}

2. 素材预获取

素材类节点（如 video-clip）需要先获取素材 MP4：

获取优先级（按顺序尝试，成功即停）：

1. 用户预置素材：assets/ 中已有对应素材 → 直接使用
2. video_generate 工具：根据画面需求撰写 prompt，生成后验证时长
3. siliconflow-video-gen：AI 视频生成（每次 5 秒，可能需多次生成后拼接） ⚠️：siliconflow-video-gen只要失败一次，第二次马上降级使用pexels-footage或者pixabay-footage，绝不允许连续多次调用siliconflow-video-gen，以避免触发系统锁死
4. pixabay-footage：从 Pixabay 免费素材库搜索下载
5. pexels-footage：Pixabay 无合适结果时，从 Pexels 搜索下载

素材下载规则：

• 一次只下载一个视频：pixabay-footage 和 pexels-footage 脚本已强制 --max-clips=1
• 时长精准匹配：根据节点目标时长设置 --min-duration 和 --max-duration，不下载远超需求的素材
• 下载后用 ffprobe 确认实际时长，写入节点 duration 字段

3. 模板变量注入

所有节点的变量通过 project-set-var 注入 html-video 项目。素材节点的 videoSrc 替换为 Step 2 获取的 clip.mp4 路径，duration 替换为 ffprobe 检测的实际时长。

4. TTS 生成

• 主力：openclaw MiniMax 扩展（speech-2.8-hd，5 种中文音色）
  • 通过 tts 工具调用
  • TokenPlan 订阅 key: MINIMAX_CODE_PLAN_KEY
• Fallback：SiliconFlow TTS (MOSS-TTSD-v0.5)
  • 通过 siliconflow-tts 技能调用，详见 siliconflow-tts/SKILL.md
• BGM：openclaw MiniMax 扩展（music-2.6）
  • 通过 music_generate 工具调用
• 生成的音频文件写入项目资产目录，html-video 的 applySoundtrack 负责最终混音

5. 全项目渲染

./skills/html-video/scripts/hv.sh project-render <project-id> --output final/video.mp4

html-video 自动完成：逐帧渲染 → 帧拼接 → 音频混合。

可用模板

标题 / 呈现类（presentation）

数据可视化类（data-viz）

产品 / 营销类（marketing / product-demo）

讲解 / 氛围类（explainer / ambient）

素材帧类（stock-clip）

本地 workspace 模板（templates/ 目录下）使用 <name>-<aspect> 命名，由 registry.py 解析。html-video CLI 模板使用 frame- 前缀。在 content-graph 的 templateRef 中使用对应的模板 ID。

结尾类（intro-outro）

模板选择提示：使用 hv.sh search-templates --intent "<意图>" 搜索最匹配的模板。例如 --intent "product launch" 会推荐 frame-liquid-bg-hero 和 frame-product-promo。

环境变量