Communitygithub.com

remotion-topic-explainer

指导 AI Agent 如何规划、构建或剪辑一段“Remotion 主题解说视频”,最终输出一个完整的短视频。流程涵盖 Remotion 主题解说视频技巧(60-90秒),1. 视频结构与节奏(60-90秒 / 1800-2700帧 @ 30fps),2. TTS 语音生成(`edge` | `cit`)。当新任务要求此类创作时使用。

remotion-topic-explainer 是什么?

该技能专为 AI Agent(如 Claude Code、Cursor、Codex)设计,用于在 Remotion 框架中自动生成 60-90 秒的短视频解说(TikTok / YouTube Shorts / Reels 格式:1080x1920 @ 30fps)。它集成了最佳的视觉动画实践(来自 `remotion-dev/skills` 的弹簧动画、安全插值、序列合成、排版层级)和 AI 语音合成(通过 `.env` 配置 `TTS_PROVIDER`,支持 `edge` 或 `cit` 两种服务)。技能详细规定了基于“钩子-问题-解决方案-价值-结尾”框架的6场景视频结构,并为每个场景给出了精确的时间范围和帧数。工作流程包括:用 TypeScript 脚本生成带时间戳的语音文件(自动缓存为 MP3/WAV 并输出 manifest),创建标准化的 Remotion 源代码目录结构(主组件、类型定义、音频数据、场景组件),以及用 `SfxTrack` 组件同步音效。最后,技能要求将合成注册到 `src/Root.tsx`,并通过 `npm run lint` 和 `npx remotion render` 进行验证与导出。

兼容平台✓Claude Code✓Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/hoangtuanqn/remotion-template/tree/HEAD/.agents/skills/remotion-topic-explainer

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Remotion 主题解说视频技巧(60-90秒)

本技能指导你从任意给定主题创建高质量、60-90 秒的短视频解说(TikTok / YouTube Shorts / Reels 格式:1080x1920 @ 30fps)。

它结合了:

  1. 视觉最佳实践:来自 remotion-dev/skills(帧精确的弹簧动画、插值钳制、序列合成、排版层级)。
  2. AI 语音合成:通过 .env 中的 TTS_PROVIDER 配置:edge(edge-tts-universal,在线,免费)或 cit(CIT Voice Studio,离线越南语工作室声线 - 下载 github.com/Cuongyd196/cit-voice-studio,API 文档:docs/cit-voice-studio.md)。
  3. 精确时间同步:将音频语音长度直接映射到 Remotion 帧序列。

1. 视频结构与节奏(60-90秒 / 1800-2700帧 @ 30fps)

一个引人入胜的短视频遵循 钩子 - 问题 - 解决方案 - 价值 - 结尾 框架:

场次名称时间帧范围 (@ 30fps)目的与视觉元素
1钩子0s – 6s~180 帧用数字提出引人好奇的承诺或问题,前2秒内说出。大标题,video-style 的钩子效果。
2背景/痛点6s – 17s~330 帧陈述问题或该主题为何重要的背景。两个对立卡片从两侧滑入。
3核心概念 第1部分17s – 32s~450 帧核心原理1:毛玻璃卡片,高亮关键词。
4核心概念 第2部分32s – 48s~480 帧工作原理:3步流程,连线逐步绘制。
5实际影响48s – 64s~480 帧实际应用、建议或数字递增。
6结尾与行动号召64s – 75s~330 帧一句有力总结,关注频道按钮。

如果需要延长到90秒,可在结尾前添加1-2个额外场景(例如具体例子、注意事项)。任何超过13秒的场景都应拆分。

总时长: 1800 – 2700 帧(约 60 – 90 秒)。


2. TTS 语音生成(edge | cit)

2.1 通过 .env 配置语音

确保 .env 文件已配置(完整示例见 .env.example):

TTS_PROVIDER=edge                    # edge | cit
TTS_OUTPUT_DIR=public/audio

# Edge TTS (TTS_PROVIDER=edge)
EDGE_TTS_VOICE=vi-VN-HoaiMyNeural    # 或 vi-VN-NamMinhNeural, en-US-ChristopherNeural
EDGE_TTS_RATE=+10%                   # +10% 到 +15% 有助于短视频节奏紧凑吸引人

# CIT Voice Studio (TTS_PROVIDER=cit)
CIT_TTS_BASE_URL=http://127.0.0.1:8001
CIT_TTS_VOICE=Hải Đăng               # 语音列表:docs/cit-voice-studio.md 或 GET /voices
CIT_TTS_SPEED=1.1                    # 0.5 - 2.0

当 TTS_PROVIDER=cit 时:

  • CIT Voice Studio 应用必须正在运行。脚本在生成音频前会自动调用 GET /health;如果报告无法连接,请提示用户打开该应用(或从 github.com/Cuongyd196/cit-voice-studio 下载)。
  • 脚本中可以插入情感标签 [cười]、[thở dài]、[hắng giọng] 和停顿标签 [nghỉ 0.5s](这些标签不会被读出声)。不要滥用:每个场景最多1个标签。
  • 错误 400 Voice not found = 语音名称错误(区分音调)。检查 CIT_TTS_VOICE。

2.2 生成音频文件的流程

当收到主题时,首先创建 src/<TopicName>/ 目录,因为 src/<TopicName>/audioData.ts 只会在该目录已存在时生成。然后创建 scripts/generate-<topic>-audio.ts 并运行它来生成音频:

import { generateTopicVoices } from "./generate-tts";

const scenes = [
  {
    id: "scene1_hook",
    text: "Bạn có biết Docker thực chất là gì và tại sao mọi lập trình viên đều cần nó?",
  },
  {
    id: "scene2_problem",
    text: "Trước đây, câu nói 'trên máy tôi vẫn chạy được' luôn là cơn ác mộng khi bàn giao sản phẩm.",
  },
  {
    id: "scene3_concept1",
    text: "Docker giải quyết việc này bằng Container - đóng gói toàn bộ code và môi trường vào một khối duy nhất.",
  },
  {
    id: "scene4_concept2",
    text: "Khác với máy ảo nặng nề, Docker chia sẻ chung nhân hệ điều hành, giúp khởi động chỉ trong tích tắc.",
  },
  {
    id: "scene5_impact",
    text: "Nhờ đó, bạn deploy ứng dụng mượt mà trên mọi máy chủ từ AWS, GCP cho đến VPS giá rẻ.",
  },
  {
    id: "scene6_outro",
    text: "Follow kênh để nắm trọn các kiến thức công nghệ ngắn gọn mỗi ngày nhé!",
  },
];

generateTopicVoices("DockerShort", scenes).catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

音频文件将自动保存到 public/audio/<TopicName>/<sceneId>.<ext>(edge 为 .mp3,cit 为 .wav),并附带一个 manifest.json 文件,精确记录每个场景的帧数(durationInFrames)和 audioPath。

  • 每个场景的可选项:voice(当前提供商的语音),rate/pitch/volume(仅 edge),speed 0.5-2.0(仅 cit)。
  • 已存在的文件会被重用(缓存)。若要在修改脚本或更换语音后重新生成,请先删除相应的音频文件。

3. Remotion 编码规则(来自 remotion-dev/skills)

在编写 Remotion 源代码时,强制遵守以下原则:

3.1 使用弹簧动画

不要使用 CSS keyframes/transitions 或无意义线性缓动。使用 spring():

import { spring, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

// 为卡片/图标使用平滑弹性的弹簧动画
const scale = spring({
  frame,
  fps,
  config: {
    damping: 12,    // 小于15产生自然弹性
    stiffness: 100,  // 刚度
    mass: 0.8,
  },
});

const entrance = spring({
  frame: frame - 10, // 延迟10帧
  fps,
  from: 50,
  to: 0,
});

3.2 安全的插值(始终钳制)

始终提供 extrapolateLeft: "clamp" 和 extrapolateRight: "clamp",以防止时间线超出范围时值溢出:

import { interpolate } from "remotion";

const opacity = interpolate(frame, [0, 15], [0, 1], {
  extrapolateLeft: "clamp",
  extrapolateRight: "clamp",
});

3.3 嵌入音频并同步 Sequence

Composition 中的每个场景应使用 <Sequence> 或 <Series> 来精确管理时间:

import { Audio, staticFile, Sequence } from "remotion";

// 在场景组件中 - 从 manifest 获取路径,不要硬编码 .mp3 后缀(cit 提供商输出 .wav):
<Sequence from={0} durationInFrames={sceneDuration}>
  <Audio src={staticFile(audioManifest.scenes[0].audioPath)} />
  <SceneContent />
</Sequence>
  1. 精简的场景切换缓冲(快速过渡缓冲):
    • 场景之间的缓冲应仅为 +3 到 +4 帧(约0.1秒),即在语音结束之后。
    • 避免过长的缓冲(+15 到 +20 帧),这会导致场景之间出现空白/节奏中断。下一个场景应在上一句结束时立即出现,以保持紧凑、吸引人的节奏。
// 计算 Series 中各场景时长的示例
// manifest 中的值已包含10帧缓冲,因此先减去再添加新缓冲。
const d1 = audioManifest.scenes[0].durationInFrames - 10 + 3;
const d2 = audioManifest.scenes[1].durationInFrames - 10 + 3;
// ...

3.4 视觉设计规范(竖屏 1080x1920)

整体风格(背景、毛玻璃卡片、品牌、字体大小、布局、字幕、动效、钩子)遵循 video-style 技能。从 src/ClaudeBugHunterRepo/ 复制 theme.ts 和 components/。不要在文字中使用 emoji 或装饰性图标。


4. 为 Antigravity / Codex 创建视频的分步流程

当收到请求:"创建关于 [主题 X] 的解说视频":

第1步:编写脚本

  1. 确定6个场景(钩子、问题、概念1、概念2、影响、结尾)。
  2. 编写自然、简洁的越南语脚本,句子简短(总计260-330词,每个场景35-50词)。场景1以承诺或具体结果开头;参考 video-style 中的钩子和脚本部分。

第2步:生成语音(TTS 生成)

  1. 读取 .env 中的 TTS_PROVIDER 以确定当前使用的是 edge 还是 cit。
  2. 创建目录 src/<TopicName>/,然后创建脚本 scripts/generate-<topic>-audio.ts 并调用 generateTopicVoices,运行 npx tsx scripts/generate-<topic>-audio.ts。
  3. 从 manifest.json / src/<TopicName>/audioData.ts 中获取实际帧时长列表。

第3步:创建代码目录 src/<TopicName>/

标准目录结构:

src/<TopicName>/
├── <TopicName>.tsx          # 主组合,组合多个 Series.Sequence
├── types.ts                 # Schema & Props
├── audioData.ts             # 音频时长元数据
└── scenes/
    ├── Scene1Hook.tsx
    ├── Scene2Problem.tsx
    ├── Scene3Concept1.tsx
    ├── Scene4Concept2.tsx
    ├── Scene5Impact.tsx
    └── Scene6Outro.tsx

音效:使用 src/sfx/SfxTrack.tsx 中的 <SfxTrack cues={...} />,放置在主组件中。音频文件位于 public/sfx/,通过 npx tsx scripts/generate-sfx.ts 重新生成。

何时音效
每个场景开头,提前3帧以落在新句子前的空白中(场景1在帧0)mallet
卡片或项目出现pop 或 tick
重点、结论ding
关注号召chime
  • 每个 cue 的 frame 是从视频开头算起的帧数,与该组件出现的时间一致。
  • 无需自行避免声音重叠:SfxTrack 会自动丢弃与前一个 cue 间隔小于0.4秒的 cue,并在同一声音立即重复时降低音量。
  • 不要从 myinstants 或不明许可证的网站下载音频。如需新的音效,请添加到 scripts/generate-sfx.ts。

第4步:将 Composition 注册到 src/Root.tsx

将新的 Composition 添加到 src/Root.tsx:

<Composition
  id="<TopicName>"
  component={<TopicName>}
  durationInFrames={totalFrames}
  fps={30}
  width={1080}
  height={1920}
  defaultProps={{}}
/>

第5步:检查与报告

  1. 运行 npm run lint 检查 TypeScript/ESLint 错误。
  2. 向用户报告在 Remotion Studio 中打开 Composition 的链接(http://localhost:3000)或渲染 MP4 的命令:
    npx remotion render <TopicName> out/<TopicName>.mp4
    

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能