make-explainer-video

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Make an explainer video

制作讲解视频

Make a narrated explainer video about a source project, the project the user wants explained, with the explainer studio, yahyabedirhan/explainer-studio. The source project is read-only: read what explains the subject, such as its code, docs and its own pull requests, and write nothing into it.

A video is a stack of layers. Each layer has options, and the video uses one option per layer. A preset is a named set of choices. Start from a preset, or choose each layer yourself.

使用 explainer studio yahyabedirhan/explainer-studio 制作一段讲解 源项目（source project）（即用户希望讲解的项目）的带旁白讲解视频。源项目是只读的：阅读所有能够说明该主题的内容，例如其代码、文档及其自身的 pull requests，并且不要向其中写入任何内容。

视频是若干 图层（layers） 的堆叠。每个图层都有一些选项，而视频在每个图层中使用一个选项。预设（preset） 是一组有名称的选择。可以从预设开始，也可以自行选择每个图层。

Parameters

参数

```
<studio>
```
: a checkout of the studio, e.g.
```
~/Developer/<owner>/explainer-studio
```
, or any worktree of it.

```
<studio>
```
：studio 的一个 checkout，例如
```
~/Developer/<owner>/explainer-studio
```
，或它的任意 worktree。

Layers

图层

references/layers.md says how layers combine.

Layer	Options	Choose
Renderer	`remotion` , `fframes`	one
Drawing	`dom` , `canvas`	one or both, scene by scene; `remotion` only
Look	`dark-ui` , `paper-blueprint` , `paper-havooch` , `pixel-thermal`	one
Effects	`grain` , `shaders`	none, one or both
Captions	`on` , `off`	one
Voice	`kokoro`	one
Sound	`synth` , `none`	one
Optional steps	`reference-study` , `process-page`	none, one or both

references/layers.md 说明各图层如何组合。

图层	选项	选择方式
渲染器（Renderer）	`remotion` 、 `fframes`	一个
绘制（Drawing）	`dom` 、 `canvas`	一个或两个均可，可按场景逐个选择；仅支持 `remotion`
视觉风格（Look）	`dark-ui` 、 `paper-blueprint` 、 `paper-havooch` 、 `pixel-thermal`	一个
特效（Effects）	`grain` 、 `shaders`	无、一个或两个均可
字幕（Captions）	`on` 、 `off`	一个
配音（Voice）	`kokoro`	一个
声音（Sound）	`synth` 、 `none`	一个
可选步骤（Optional steps）	`reference-study` 、 `process-page`	无、一个或两个均可

Presets

预设

```
studio
```
: products, interfaces, data and architecture, with real UI and bold type.
```
sketchbook
```
: a concept or process in under a minute, drawn on paper and blueprint.
```
havooch
```
: a video about Havooch, the sketchbook in Havooch's colours with Havuç the cat.

```
studio
```
：适用于产品、界面、数据和架构，采用真实 UI 和粗体字排版。
```
sketchbook
```
：用纸张和蓝图风格，在不到一分钟内讲解一个概念或流程。
```
havooch
```
：关于 Havooch 的视频，采用 Havooch 的配色和 sketchbook 风格，并加入 Havuç 猫。

Steps

步骤

Open the studio. Work in
```
<studio>
```
. Every checkout and worktree shares one videos root; references/videos-root.md says where a video's files go.
- When there's no clone: clone the studio to
```
<studio>
```
  , run
```
npm install
```
  ,
```
npm run setup:voice
```
  and
```
npm run setup:skills
```
  , and render the README's smoke-test video once to confirm it works. It needs
```
ffmpeg
```
  and
```
espeak-ng
```
  .
- When
  .claude/skills/remotion-best-practices/
  or
  fframes-video
  is missing: run
```
npm run setup:skills
```
  .
Learn the subject. Read the source project until you can explain what the user asked about, end to end.
Ask once. Ask in a single round, and only what the request and the project leave open: what the viewer should take away, the length, the preset or the layer choices. When nothing is open, ask nothing. Then work to the MP4 with no more check-ins. The one exception is the
```
shaders
```
effect: the user picks each effect from a prototype sheet in step 7.
- When nobody can answer, such as when you run as a sub-agent: decide, and write each decision into the brief.
Scaffold.
```
npm run new-video -- <project>-<topic>
```
creates
```
<root>/<slug>/
```
and prints its path. Pass
```
--fps <n>
```
when the preset or the brief sets one.
Choose the layers. Take the preset's choices, then apply the user's changes. Check each option's needs in its reference. Write the choices into the brief's Choices lines, and read the reference of every chosen option.
- When the look has no code for the chosen renderer or drawing: follow "A look in a new renderer" in references/layers.md.
- With
  reference-study
  : do it now, before the brief.
- With
  process-page
  : from here on, end every step with a snapshot, as references/steps/process-page.md says.
Brief and script. Fill
```
<root>/<slug>/brief.md
```
: the goal, the audience, the length, the look notes, one line of narration per scene, and every asset the scenes show. Kokoro speaks about 2.5 words a second, so budget the words against the length. Write for the ear: references/pronunciation.md.
- Done when each scene has its line, and every sentence names something that appears or moves on screen.
Asset sheet. Draw every character, prop, UI mock and diagram element on one still:
```
<root>/<slug>/Sheet.tsx
```
in Remotion, a frame of the project in FFrames (the renderer reference says how). Look at it, and fix what collides, reads badly or overflows.
- With
  shaders
  : draw the candidate effects on the sheet, and let the user pick: references/effects/shaders.md.
- Done when every asset in the brief is on the sheet and reads at a glance.
Voice. Put the narration in
```
voiceover.json
```
, one scene per line, and run
```
npm run voice -- <slug>
```
. Find each cue word in the scene's
```
words
```
.
- Done when every scene has
```
durationSeconds
```
  and
```
words
```
  , and the total is within about 10 % of the length.
Storyboard. Build each scene at its end pose, with no motion yet, and render a still of its last frame. Fix overlaps, text outside its shape and empty halves of the frame.
- Done when every end pose reads as the brief says.
Animate. Add the motion. Cue every reveal on the narration word it shows. Run the sound layer with the final length, then place the music and the sound effects, and add the effects the choices name.

Done when every reveal has a word cue, and
```
npx tsc -p "$(npm run --silent root)"
```
passes (in FFrames,
```
cargo build
```
).

Check and render. Look at stills at key frames, then render the MP4 to
```
<root>/<slug>/out/<slug>.mp4
```
, as the renderer reference says. Look at a contact sheet of the render (
```
npm run sheet -- <slug>
```
; add
```
--every 0.125
```
for a video under 15 seconds) and at stills two or three frames after the cues. For fast motion, render four stills a few frames apart. Look for:

a reveal off its word, or something appearing with no cue;
a stretch where the voice talks and nothing moves;
text outside its box, overlaps, a trail left after a flight;
a rotation fast enough to look frozen.
Done when a round of stills and the sheet finds none of these.

Final checks. Run
```
ffprobe
```
on the MP4.

Done when the frame count equals the summed scene frames, the size and fps match
```
config.ts
```
, and there is an audio stream.
With
process-page
: build the page now.

Hand over. Give the user the full path of the MP4 and of anything they asked for, the choices the video used, and
```
npm run dev
```
in the studio to preview or tweak it.

打开 studio。 在
```
<studio>
```
中工作。所有 checkout 和 worktree 共享同一个 videos root；references/videos-root.md 说明视频文件应放置的位置。
- 尚未 clone 时： 将 studio clone 到
```
<studio>
```
  ，运行
```
npm install
```
  、
```
npm run setup:voice
```
  和
```
npm run setup:skills
```
  ，并渲染一次 README 中的 smoke-test 视频以确认其正常工作。运行需要
```
ffmpeg
```
  和
```
espeak-ng
```
  。
- 当
  .claude/skills/remotion-best-practices/
  或
  fframes-video
  缺失时：运行
```
npm run setup:skills
```
  。
了解主题。 持续阅读源项目，直到能够从头到尾解释用户所问的内容。
只询问一次。 在单轮中提问，并且只询问请求和项目尚未明确的事项：观众看完应掌握什么、时长、preset 或 layer 选择。如果没有任何待定事项，则不要提问。此后持续制作到 MP4，不再询问。唯一例外是
```
shaders
```
特效：用户在第 7 步从 prototype sheet 中选择每个特效。
- 无人能够回答时（例如以 sub-agent 身份运行时）：自行决定，并将每项决定写入 brief。
搭建项目结构（Scaffold）。
```
npm run new-video -- <project>-<topic>
```
会创建
```
<root>/<slug>/
```
并打印其路径。当 preset 或 brief 指定了帧率时，传入
```
--fps <n>
```
。
选择图层。 先沿用 preset 的选择，再应用用户的修改。查看每个选项对应 reference 中的要求。将这些选择写入 brief 的 Choices 行，并阅读每个已选选项的 reference。
- 当所选 Look 没有适配所选 Renderer 或 Drawing 的代码时： 按照 references/layers.md 中的“A look in a new renderer”操作。
- 使用
  reference-study
  时：现在就执行，并在 brief 之前完成。
- 使用
  process-page
  时：从这里开始，每一步都以 snapshot 结束，正如 references/steps/process-page.md 所述。
Brief 和脚本。 填写
```
<root>/<slug>/brief.md
```
：目标、受众、时长、Look 备注、每个场景一行旁白，以及场景中会展示的每项素材。Kokoro 的语速约为每秒 2.5 个单词，因此要根据时长安排词数。写作时应考虑听感：references/pronunciation.md。
- 完成标准：每个场景都有对应台词，且每个句子都点明屏幕上会出现或移动的某个内容。
素材表（Asset sheet）。 在一张静态画面中绘制所有角色、道具、UI mock 和图示元素：Remotion 中为
```
<root>/<slug>/Sheet.tsx
```
，FFrames 中则放在项目的一帧中（具体做法见 renderer reference）。查看素材表，并修复元素重叠、可读性差或溢出的问题。
- 使用
  shaders
  时：将候选 effects 绘制在素材表上，让用户选择：references/effects/shaders.md。
- 完成标准：brief 中的每项素材都在素材表上，并且一眼就能看懂。
配音。 将旁白放入
```
voiceover.json
```
，每个场景一行，然后运行
```
npm run voice -- <slug>
```
。在该场景的
```
words
```
中找到每个 cue word。
- 完成标准：每个场景都有
```
durationSeconds
```
  和
```
words
```
  ，并且总时长与目标时长相差约 10% 以内。
故事板（Storyboard）。 将每个场景搭建成其结束姿态，暂不添加运动，并渲染最后一帧的静态图。修复元素重叠、文字超出其形状以及画面有一半空置等问题。
- 完成标准：每个结束姿态都符合 brief 的描述。
添加动画。 加入运动。让每次 reveal 都以它所对应的旁白词作为 cue。以最终时长运行 sound layer，然后放置 music 和 sound effects，并添加 choices 指定的 effects。
- 完成标准：每个 reveal 都有词 cue，并且
```
npx tsc -p "$(npm run --silent root)"
```
  通过（在 FFrames 中则运行
```
cargo build
```
  ）。
检查并渲染。 查看关键帧的静态图，然后按照 renderer reference 所述，将 MP4 渲染到
```
<root>/<slug>/out/<slug>.mp4
```
。查看渲染结果的 contact sheet（
```
npm run sheet -- <slug>
```
；对于短于 15 秒的视频，加上
```
--every 0.125
```
），并查看各个 cue 之后两三帧的静态图。对于快速运动，渲染间隔几帧的四张静态图。检查：
- reveal 与对应词错位，或有内容在没有 cue 的情况下出现；
- 旁白持续说话但画面没有任何动静；
- 文字超出文本框、元素重叠，或飞行后留下残影；
- 旋转速度快到看起来像卡住。
- 完成标准：一轮静态图检查和 contact sheet 检查未发现上述任何问题。
最终检查。 对 MP4 运行
```
ffprobe
```
。
- 完成标准：帧数等于所有场景帧数之和，尺寸和 fps 与
```
config.ts
```
  一致，并且存在音频流。
- 使用
  process-page
  时：现在构建页面。
交付。 向用户提供 MP4 及用户要求的其他内容的完整路径、视频使用的 choices，以及用于预览或调整的
```
npm run dev
```
命令。

Rules

规则

Timing comes from the voice. Scene lengths come only from
```
voiceover.json
```
after
```
npm run voice
```
; every reveal is cued on a spoken word. Type no scene length and no guessed cue frame.
One scene per file.
Look before you finish. A render command that succeeds proves nothing: look at the stills, the sheet and the
```
ffprobe
```
output.
Small edits for feedback. Change the part the user named, and keep the rest.
Free and local. No paid APIs and no keys. Draw art in code first. When code can't draw it, use a freely licensed file and note its source and licence beside it.
Videos stay private. A video's files stay in the videos root. Commit only studio code, never a video's files.

时序来自配音。 场景长度只能来自运行
```
npm run voice
```
后的
```
voiceover.json
```
；每个 reveal 都以说出的词作为 cue。不要输入场景长度，也不要猜测 cue 所在的帧。
每个文件一个场景。
完成前必须查看。 渲染命令成功并不能证明任何问题：务必查看静态图、contact sheet 和
```
ffprobe
```
输出。
针对反馈进行小范围修改。 只修改用户指出的部分，保留其余内容。
免费且本地运行。 不使用付费 API 和密钥。优先用代码绘制美术素材。当代码无法绘制时，使用采用自由许可的文件，并在文件旁注明来源和许可。
视频保持私密。 视频文件留在 videos root 中。只提交 studio 代码，绝不提交视频文件。

Where the official skills differ

官方 skills 存在差异时的处理方式

Use the official skill of each tool for the tool itself: Remotion's skills (

.claude/skills/remotion-best-practices/

and the references it routes to) and FFrames'

fframes-video

. Where one of them disagrees with this skill, this skill wins. When you find a disagreement the table doesn't list, follow this skill and add a row to this table.

Where the official skill says	Do this instead
Remotion `SKILL.md` , "Open the preview" and "Render the video": start Studio before building, and render only when the user asks	Finish with steps 11 and 12: stills you've looked at, then the MP4, checked with `ffprobe` . Start Studio ( `npm run dev` ) when the user asks to watch.
Remotion: render or take a still with `npx remotion render` or `npx remotion still`	`npm run render -- <slug>` and `npm run still -- <slug> <name>` , which write into `<root>/<slug>/out/` .
Remotion: write scene lengths as literal numbers	Lengths come from `voiceover.json` through `@studio/lib/timing` .
Remotion `remotion-markup/voiceover.md` : ElevenLabs, ask for an API key, size the composition with `calculateMetadata`	Kokoro through `npm run voice` , which needs no key. Lengths as above.
Remotion `remotion-markup/sfx.md` : `remotion.media` URLs, search the internet	Sound files are local, in the video's `assets/` : references/sound.md.
Remotion `remotion-markup/REFERENCE.md` : make components editable with `Interactive.withSchema` and `Interactive.Div`	Plain JSX components and `<div>` s.
Remotion `remotion-captions/` : transcribe with Whisper, show a copied caption element fed an inline array	Captions are the script: references/captions.md.
`fframes-video` : make a project folder of its own	The project is `<root>/<slug>/fframes/` , inside the video's folder.
`fframes-video` : time scenes in seconds or frames you choose	Timing comes from `voiceover.json` through `npm run fframes-sync` , which writes `src/timing.rs` .
`fframes-video` : voice and sound from other sources	Kokoro through `npm run voice` , and the sound layer's files.

对于每种工具本身，使用相应工具的官方 skill：Remotion 的 skills（

.claude/skills/remotion-best-practices/

以及其中路由到的 references）和 FFrames 的

fframes-video

。如果其中某个官方 skill 与本 skill 不一致，以本 skill 为准。如果发现本表未列出的分歧，遵循本 skill，并向表中新增一行。

官方 skill 的说法	改为这样做
Remotion `SKILL.md` 中的“Open the preview”和“Render the video”：在构建前启动 Studio，并且只在用户要求时渲染	改为完成第 11 和 12 步：查看静态图，然后生成 MP4 并用 `ffprobe` 检查。用户要求观看时再启动 Studio（ `npm run dev` ）。
Remotion：使用 `npx remotion render` 或 `npx remotion still` 渲染或截取静态图	使用 `npm run render -- <slug>` 和 `npm run still -- <slug> <name>` ，并将文件写入 `<root>/<slug>/out/` 。
Remotion：将场景长度写为字面数字	长度通过 `@studio/lib/timing` 从 `voiceover.json` 获得。
Remotion `remotion-markup/voiceover.md` ：使用 ElevenLabs，索取 API key，并通过 `calculateMetadata` 设置 composition 尺寸	改用 Kokoro，通过 `npm run voice` 运行，无需 key。长度同上。
Remotion `remotion-markup/sfx.md` ：使用 `remotion.media` URL，搜索互联网	声音文件保存在视频的 `assets/` 中，使用本地文件：references/sound.md。
Remotion `remotion-markup/REFERENCE.md` ：使用 `Interactive.withSchema` 和 `Interactive.Div` 创建可编辑组件	使用普通 JSX 组件和 `<div>` 。
Remotion `remotion-captions/` ：使用 Whisper 转录，并显示由内联数组驱动的复制字幕元素	字幕就是脚本：references/captions.md。
`fframes-video` ：创建独立的项目文件夹	项目是 `<root>/<slug>/fframes/` ，位于视频文件夹内。
`fframes-video` ：以自行选择的秒数或帧数对场景计时	时序来自 `voiceover.json` ，由 `npm run fframes-sync` 写入 `src/timing.rs` 。
`fframes-video` ：从其他来源获取 voice 和 sound	使用通过 `npm run voice` 生成的 Kokoro，以及 sound layer 的文件。