视频生成

基于 JSON 驱动的视频生成流水线，使用 Remotion 构建。通过结构化 JSON 编写时间线，支持主题系统、TTS 旁白、转场效果和完整的组件库，渲染输出为 MP4 格式 — 全部通过命令行操作。

默认启用：是 AI 与媒体

快速参考

CLI 命令

所有命令均在 skills_ref/video/ 目录下运行。输出默认存放在 /tmp/remotion-render/ — 渲染输出应保持在源代码目录之外。

流水线用法

# 同步模式（默认） — 阻塞直到渲染完成
node skills_ref/video/scripts/pipeline.mjs \
  --timeline timeline.json \
  --output /tmp/remotion-render

# 使用预设覆盖（timeline.meta.preset 是权威来源）
node skills_ref/video/scripts/pipeline.mjs \
  --timeline timeline.json \
  --preset Portrait-1080p

# 异步模式 — 立即返回，后台渲染
node skills_ref/video/scripts/pipeline.mjs \
  --timeline timeline.json \
  --async

# 检查异步状态
node skills_ref/video/scripts/pipeline.mjs \
  --status /tmp/remotion-render/render-result.json

时间线编写

视频通过 JSON 时间线定义，包含一个 meta 块（标题、预设、帧率、时长）和一个 elements 类型化幻灯片数组。每个元素指定其类型、时间、属性和可选的转场效果。

最小示例

{
  "meta": {
    "title": "My Video",
    "preset": "Landscape-1080p",
    "fps": 30,
    "totalDurationSec": 15
  },
  "elements": [
    {
      "type": "title",
      "startSec": 0,
      "durationSec": 5,
      "props": { "title": "Hello World", "subtitle": "A demo" },
      "transition": { "type": "fade" }
    },
    {
      "type": "content",
      "startSec": 5,
      "durationSec": 5,
      "props": {
        "header": "Key Points",
        "bulletPoints": ["Fast", "Safe", "Beautiful"]
      },
      "transition": { "type": "slide", "direction": "from-right" }
    },
    {
      "type": "code",
      "startSec": 10,
      "durationSec": 5,
      "props": {
        "code": "const x = 42;",
        "language": "typescript",
        "title": "Example"
      },
      "transition": { "type": "fade" }
    }
  ],
  "audio": []
}

主题系统

每个视频应通过 meta.theme 定义独特的视觉风格。字体通过 @remotion/google-fonts 加载，以确保跨平台渲染一致。默认主题使用 Chakra Petch（展示字体）、Outfit（正文字体）和 JetBrains Mono（代码字体），搭配深蓝色背景和青色强调色。

{
  "meta": {
    "theme": {
      "aesthetic": "brutalist tech",
      "font": { "display": "Chakra Petch", "body": "Outfit" },
      "color": { "accent": "#FF6B35", "bg": "#0A0A0A" },
      "gradient": {
        "hero": "radial-gradient(circle at 20% 30%, rgba(255,107,53,0.2) 0%, transparent 60%)"
      }
    }
  }
}

内容设计规则

推荐做法

• 使用简洁的标题，不加表情符号
• 要点写成短语形式（最多 8 个词），每张幻灯片 3–4 条
• 变化幻灯片类型：title、content、code、content — 避免单调
• 混合使用转场效果：fade、slide、wipe（避免同一类型连续出现 3 次以上）
• 在代码幻灯片上展示真实代码，而非伪代码
• 选定一种主题美学风格，并贯穿始终

应避免的做法

• 在幻灯片标题或头部使用表情符号
• 单张幻灯片超过 5 条要点
• 使用通用标题，如 "Key Features"、"Getting Started" 或 "Summary"
• 在 meta.theme 中使用 Inter、Roboto 或 Arial 字体

内容密度

画布尺寸较大（1920x1080 或 1080x1920）。稀疏的内容会造成空白区域。应添加更多内容块 — 而非增大字号或增加内边距。每张幻灯片应至少使用画布面积的 70%。

短视频 (Portrait-1080p)

• 60 秒内最多 8–10 个元素
• 首张幻灯片 = 吸引眼球（最多 5 个词）+ 描述性副标题
• 末张幻灯片 = 行动号召或令人难忘的结尾 + 标语
• 每张内容幻灯片 5–6 条要点，代码幻灯片 6–10 行
• 每张内容幻灯片都搭配使用 content + bulletPoints

分辨率预设

默认值：Landscape-1080p。智能体会根据关键词自动选择 — "reels"、"shorts" 或 "TikTok" 触发 Portrait-1080p；"Instagram" 触发 Square-1080p。

组件库

Remotion 项目提供 11 个幻灯片组件及辅助功能。每个组件对应时间线 JSON 中的一个 type 值。

幻灯片组件

功能特性

TTS 集成

提供三个 TTS 提供商。默认使用 Gemini。流水线会自动检测时间线元素中的 narration 字段，并生成对应每个片段的音频文件。

草稿到终稿工作流

1. 编写 timeline.draft.json，包含 narration 和可选的 voiceControl 字段。
2. 流水线自动检测旁白字段，为每个片段生成音频。
3. 生成 timeline.final.json，包含 audio[] 条目和校正后的 durationSec。
4. 使用同步音频渲染最终时间线。

带旁白的草稿时间线

{
  "elements": [
    {
      "id": "intro",
      "type": "title",
      "durationSec": 11,
      "narration": "Welcome to the analysis report.",
      "voiceControl": {
        "tonePrompt": "Calm, professional news anchor tone"
      },
      "props": {
        "title": "Tech Trends",
        "subtitle": "2026 Edition"
      }
    }
  ]
}

时长估算

• 韩语：约 6.5 字符/秒 — Math.ceil(narration.length / 6.5) + 0.5
• 最终 durationSec 在 TTS 生成后通过 ffprobe 测量自动校正

渲染验证 — 三级门控

所有三级门控必须全部通过，渲染才被视为成功。

node scripts/validate-artifact.mjs /tmp/remotion-render/TimelineVideo.mp4 --preset Landscape-1080p

FFmpeg 模式

FFmpeg 负责 Remotion 之外的确定性剪切、批量处理和预处理操作。以下模式可在视频流水线中使用。

按时间戳提取片段

ffmpeg -i raw.mp4 -ss 00:12:30 -to 00:15:45 -c copy segment_01.mp4

从编辑决策列表批量剪切

#!/bin/bash
# cuts.txt 格式：start,end,label
while IFS=, read -r start end label; do
  ffmpeg -i raw.mp4 -ss "$start" -to "$end" -c copy "segments/${label}.mp4"
done < cuts.txt

拼接片段

for f in segments/*.mp4; do echo "file '$f'"; done > concat.txt
ffmpeg -f concat -safe 0 -i concat.txt -c copy assembled.mp4

创建代理文件以加速编辑

ffmpeg -i raw.mp4 -vf "scale=960:-2" -c:v libx264 -preset ultrafast -crf 28 proxy.mp4

提取音频用于转录

ffmpeg -i raw.mp4 -vn -acodec pcm_s16le -ar 16000 audio.wav

音频响度标准化

ffmpeg -i segment.mp4 -af loudnorm=I=-16:TP=-1.5:LRA=11 -c:v copy normalized.mp4

场景检测

# 检测场景变化（阈值 0.3 = 中等灵敏度）
ffmpeg -i input.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync vfr -f null - 2>&1 | grep showinfo

社交媒体画面裁切

# 16:9 转 9:16（居中裁切，适用于 TikTok/Reels）
ffmpeg -i input.mp4 -vf "crop=ih*9/16:ih,scale=1080:1920" vertical.mp4

# 16:9 转 1:1（居中裁切，适用于 Instagram）
ffmpeg -i input.mp4 -vf "crop=ih:ih,scale=1080:1080" square.mp4

ElevenLabs 语音（补充）

对于 Remotion TTS 流水线之外的专业配音需求，可通过 API 直接使用 ElevenLabs。当需要高保真英语旁白、声音克隆或超出 Gemini/Supertone 能力范围的情感控制时使用。需要设置 ELEVENLABS_API_KEY。

import os, requests

resp = requests.post(
    f"https://api.elevenlabs.io/v1/text-to-speech/<voice_id>",
    headers={
        "xi-api-key": os.environ["ELEVENLABS_API_KEY"],
        "Content-Type": "application/json"
    },
    json={
        "text": "Your narration text here",
        "model_id": "eleven_turbo_v2_5",
        "voice_settings": {"stability": 0.5, "similarity_boost": 0.75}
    }
)
with open("voiceover.mp3", "wb") as f:
    f.write(resp.content)

最终润色 (Descript / CapCut)

对于代码驱动渲染处理不佳的任务，可使用传统编辑器作为最后一步：

• 节奏 — 调整过快或过慢的剪切点
• 字幕 — 自动生成后手动清理
• 调色 — 基础校正和氛围调整
• 最终音频混合 — 平衡语音、音乐和音效电平
• 导出 — 针对不同平台的格式和质量设置

依赖项

视频流水线需要 Node.js、pnpm、FFmpeg 和 Chromium 浏览器（由 Remotion 自动安装）。

环境变量

引导安装

# 首次设置：安装包并确保 Chromium 可用
node scripts/ensure-remotion.mjs

# 验证设置
cd remotion-project && pnpm exec remotion studio

项目结构

skills_ref/video/
+-- SKILL.md
+-- reference/                     # visual-quality.md, tts-integration.md, components.md
+-- scripts/
|   +-- pipeline.mjs               # CLI 入口（同步/异步/TTS）
|   +-- tts.mjs                    # TTS 编排器（多提供商）
|   +-- tts-providers/             # gemini.mjs, supertone.mjs, supertonic.mjs
|   +-- ensure-remotion.mjs        # 运行时引导
|   +-- validate-artifact.mjs      # 门控 3：ffprobe 验证
|   +-- presets.mjs                # 分辨率预设 (ESM)
+-- remotion-project/
    +-- public/example-timeline.json
    +-- src/
        +-- components/            # 11 个幻灯片组件 + 导出桶
        +-- timeline/              # JSON 转 React 引擎

"~해줌" 使用示例

以下是通过自然语言调用视频任务的实际示例。韩语和英语均可使用。

故障排除

找不到 Remotion Chromium

如果 remotion render 报浏览器错误，请确保 Chromium 已安装：

node scripts/ensure-remotion.mjs
# 或手动执行：
cd remotion-project && pnpm exec remotion browser ensure

找不到 FFmpeg

安装 FFmpeg 和 ffprobe：

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install -y ffmpeg

# 验证
ffmpeg -version && ffprobe -version

TTS 认证错误

检查所选提供商对应的环境变量是否已设置：

# Gemini（默认）
echo $GEMINI_API_KEY

# Supertone
echo $SUPERTONE_API_KEY

# Supertonic 无需密钥（离线运行）

渲染输出为空或损坏

运行产物验证器进行诊断：

node scripts/validate-artifact.mjs /tmp/remotion-render/TimelineVideo.mp4 --preset Landscape-1080p

如果门控 3 未通过，请检查 Remotion 日志中的渲染错误。常见原因：缺少字体、无效的时间线 JSON，或大型合成时内存不足。

TTS 后时长不匹配

流水线在 TTS 生成后通过 ffprobe 测量自动校正 durationSec。如果时长仍有偏差，请验证旁白文本长度是否符合估算公式：韩语文本使用 Math.ceil(text.length / 6.5) + 0.5。