html-explainer-video

HTML 讲解视频

HTML 场景 · Fil 的 MCP 视频编辑器 · Playwright · ffmpeg。 无框架的场景引擎位于 scripts/explainer.js。

讲解视频由旁白和配合旁白剪辑的画面组成。此技能先编写旁白，再根据一个数字——影片的秒数——用 HTML 绘制每一幅画面。屏幕上的每个元素都会在点名它的词语出现时呈现，因为它的时间就是那个词语的时间（T.clock 就是旁白说出「clock」的时刻）。它看起来像动态设计，又是一个网页，因此它的风格、形状和镜头都是设置项，无需重新制作。

适用范围。 在网页上展示实时应用窗口（不生成视频文件），请使用 html-demo。要将现有帖子、视频或页面转换为保留其风格的 9:16 短视频，请使用 html-reel。要制作没有旁白的短片，请使用 website-to-motion-design。若交付内容是一部约一分钟、用于解释某件事的完整讲解影片，请使用此技能。

来源。 内容提取自 Fil 在 2026 年 10 月 31 日至 11 月 1 日制作的七部一分钟入门影片。每部影片都包含一个吸引点、一项收益、带编号标题的快速教程，以及一个行动号召；场景以 2× 和 60 fps 渲染，并在 Fil 的视频编辑器中合成。这些影片采用固定的深色风格、固定的形状（4:3）和一个镜头槽位，并基于 Fil 自己的演示组件制作。此处这三项都是输入，且不依赖 Fil 的组件。demo/ 中的影片是此技能自己的讲解影片：使用同一份脚本，采用四种风格和四种形状，镜头可开可关，场景无需改动。以下规则总结了制作这些影片时付出的经验成本。

运作机制

每一帧都是一个数字的纯函数，每个时间点都对应一个词。 场景根据 t（影片的秒数）设置所有内容。HTMLExplainer.times(WORDS) 会为旁白中的每个词命名（T.clock、T.clockEnd、重复出现的词 T.look2）。渲染器每帧调用一次 window.__frame(t) 并截屏；没有任何内容读取时钟。

// film.js: a scene. No colour, no font, no pixel of layout from the shape.
const T = times(window.WORDS);
const step3 = {
  id: 'step3', from: T.three - 0.12, tone: 3,
  draw(t, $, f) {
    show($('.x-head'), t, T.three);            // when; the look says how
    show($('#code'), t, T.clock);              // lands on the word "clock"
    ring($('#last'), t, T.word);               // a thin line, on "word"
    $('#code').textContent = `T.clock = ${T.clock.toFixed(2)}`;
  },
};
film({ words: window.WORDS, end: T.end + 2.4, scenes: [hook, step3, end] });

去掉这一机制，一切都会出问题。使用 CSS 时间线或计时器的场景会按自己的节奏播放，因此换一段旁白就意味着要重新制作动画，而且剪辑点每次都会偏移几帧。根据 t 绘制的帧每次运行都是同一幅画面，因此重新渲染时，只会改变你改动过的内容。

三项输入

这些输入都不会触及场景。可以询问用户，或使用默认值。

输入	设置方式	默认值	影响内容
风格	<html data-look="…"> 或 ?look=，一组 --x- 变量（references/looks.md）	从其网站读取，否则询问风格	字体、颜色、圆角、边缘、标题位置、窗口外观、图片处理方式、字幕，以及元素的移动方式
形状	shape: 或 ?shape=：4:3、16:9、1:1、9:16	根据发布平台确定；未说明时为 4:3	舞台（短边始终为 1080）以及每个区域：--pic-x、--head-y……
镜头	camera: 或 ?camera=on	关闭	关闭：无槽位，无固定角落，场景填满画面。开启：参阅 references/camera.md

show(el, t, at, leave) 能让不同风格以不同方式移动，而无需修改场景：场景指定时间，--x-motion（rise、fade、snap、wipe）指定方式。风格变量也可以应用于任意元素，这样影片就能并排展示三种风格。

工作流

开始前最多询问一个问题，且只有在缺少要讲解的内容时才询问。说明你采用的默认设置。

1. 编写 Explainer.md：说明它是什么、观众看完后应该记住的一个核心理念、适合哪些人、影片可能提及的每一项事实及其来源，以及要提出的请求。查阅产品官网、文档或源代码以核实这些事实。影片只能陈述此列表中的内容。
2. 设定视觉风格（references/looks.md）：运行 scripts/read-look.mjs <their site> --name brand，将其测量并生成 brand.css 和 brand.md；或者由他们指定风格，再由你编写样式块。对照他们的页面，目测检查效果。现在就收集他们真实的 Logo 和图片，并按画面中的显示尺寸准备好。
3. 编写脚本（references/format.md）：开场钩子、价值、快速教程、号召尝试。语速约为每秒 2.6 个词，也就是每分钟 140 至 155 个词。按听觉体验来写。每行台词下方都说明画面要做什么，以及要落在哪个词上。
4. 用免费时钟构建。 scripts/words.py --draft script.txt --out words 根据脚本中的字母和标点免费计时。场景按名称计时，因此换成真实配音后无需更改场景。
5. 构建场景，使用 scripts/explainer.js 和 explainer.css，每个场景对应一个 <section class="x-scene">，时长约 4 到 8 秒。第一帧就是封面。只使用变量和区域，不要固定使用属于某种视觉风格或形状的颜色或尺寸。边做边查看静帧：scripts/render.mjs film.html --stills 0,3,8,16 --out stills。至少进行三轮，且至少使用两种视觉风格：只能在一种风格下奏效的场景还不算完成。
6. 检查。 在所有要渲染的视觉风格、形状和摄像机设置下运行 scripts/check-film.mjs film.html：放大的画面、柔和的 3D、同时出现两个标题、位于边缘或摄像机下方的文字，以及每次运行都不一致的画面。
7. 先查看价格，再制作配音。 在 Fil 中，使用 eleven-v4 且设定 max_credits: 0 的音频节点可以显示价格。获得对方同意后再运行。字幕设置 look: { max_words: 1 } 可生成词语时间（约 ⚡1 分钟）；保存后，将 get_video 设置为 captions: "list"，再交给 scripts/words.py --voice voice.mp3 处理。继续之前，对照脚本逐字检查台词，尤其要核对名称和数字。
8. 放置音效。 window.SFX 会列出提示音，scripts/sfx.mjs film.html 会给出每个音效的版本、同步点和音量（references/sound.md）。
9. 预览。 scripts/preview.mjs film.html --voice voice.mp3 --music bed.mp3 --sfx sfx.json --out preview.mp4：以 1×、30 fps 播放完整影片，附带字幕和 −14 LUFS 的声音，并生成联系表。在这里评判效果：修改一次只需一分钟。
10. 渲染。 scripts/render.mjs film.html --scene all --fps 60 --scale 2 --out final 会为每个场景生成一个 MP4。请以低优先级在后台运行；每个场景需要几分钟。
11. 通过 MCP 在 Fil 中组装（references/fil-editor.md）：按顺序排列场景、配音、符合视觉风格的字幕、音乐、音效和章节。
12. 导出并验证文件，而不是时间线。然后交由盲评人员评分，并修复他们共同指出的问题（references/checks.md）。

使用摄像机时，第 7 步和第 11 步会有所不同，且最后才由本人录制：references/camera.md。

规则及其所防止的问题

• 每项说法都来自 Explainer.md。 源视频上的辅助人员发现了“一个按钮”（要按三次）、“点击一下”（要点两次）、“你自己的地址”（免费方案的地址是随机的）、“把画面拉宽”（形状选项）：这些说法听起来都没问题，却全是错的。逐一核对画面和旁白中的每项说法是否符合产品，并指出矛盾之处，而不是掩盖问题。
• 第一帧就是封面。 网格、信息流和 Fil 的编辑节点都会显示视频的第一帧。在 t = 0 时，钩子的标题和最佳画面就已呈现，没有任何入场动画。钩子若从空画面开始，就什么也没呈现。
• 钩子要呈现屏幕录制无法展示的东西。 先展示结果，再讲解过程。源视频中，这是一段铺满画面的场景；而在这里，画面本身被拆解成各个图层。
• 几乎每句台词都会带来变化，而且变化要卡在对应的字上。 这就是“引人入胜”的含义。镜头要平稳：移动要缓和，绝不追赶。结果要停留足够长的时间，让人看清。
• 时间点始终根据台词来定，并且始终使用名称。 任何视频的第一版若按语速计时，每个节拍都会提前或延后。使用 T.clock，绝不用 35.63。
• 场景中不指定颜色，也不指定字体。 固定值应放在外观中。如果只有一种外观需要某个值，就添加一个变量。否则，第二种外观会让你看清所有硬编码的值。
• 两种外观的构图必须不同，不能只换颜色。 盲测评审认为这支视频的外观初稿只是换皮：布局相同，只是换了字体。移动标题（--x-head-at）、重新绘制窗口、用不同方式处理图片。这样之后，评审就能区分它们。
• 绝不使用线框图。 用灰色条块代替“你的网站”，看起来像尚未完成的视频，两位评审都这么认为。从第一帧起就展示真实页面，并圈出正在讲解的内容。
• 结尾要保持动态，并让地址足够醒目。 只展示名称 7 秒，下面的地址又很淡，会让最关键的时刻变成冷场。在名称之后的台词处呈现内容。
• 场景应按区域布局，而不是按坐标定位。 使用 --pic-x、--pic-w 和容器单位，这样 9:16 格式和镜头角落就能正常适配。在一种画面形状中测量的位置，换到另外三种就会出错。
• 3D 场景中，任何元素都不得缩放到 1 以上。 Chromium 会按布局尺寸栅格化 perspective、preserve-3d 或 3D 矩阵中的任何元素，然后拉伸位图。因此，无论文件多大、设备缩放比例如何，卡片上的 scale(1.7) 都会变模糊。应按元素的实际绘制尺寸进行布局，再沿 Z 轴向后推。钩子部分最先显出这个问题。
• 图片的显示尺寸绝不能超过其实际像素尺寸。 以 2× 渲染时，图片的比例最高读数为 2.0。要么缩小显示，要么使用实际尺寸更大的文件。绝不对图片使用 CSS 锐化、放大或模糊。
• 高亮标记要贴合所标注的内容。 ring()：用 outline 和 outline-offset 绘制 1.5 px 的线条，周围留出均匀的 4 到 6 px 空隙。绝不能画成色带，文字也绝不能碰到线条。文字后面的填充色应紧贴文字，两侧各留约 0.14 em。绝不能让窗口裁掉填充色。
• 只使用真实标志和真实图片。 从当事人自己的文件中复制。绝不绘制或仿制公司的标志，也绝不使用 lorem 或占位内容。没有图片时，就用 HTML 绘制相应内容：窗口、图表、文字。
• 绘制的任何 UI 都必须使用真实文字。 从产品中复制每个标签、菜单项和数字。只要出现一个自创词（“正在处理…”），使用过该产品的人就会不再相信其他内容。任何为视频而编写的文字，都要在报告中说明。
• 指针要落在真实目标上。 pointer() 会以实际绘制的位置为准，指向选择器。点击前 0.3 到 0.6 秒到位，并按下 0.15 秒。硬编码的位置在另一种外观中会偏离目标。
• 标题绝不能重叠。 一个标题的离场时间加上 0.22 秒，必须不晚于下一个标题的起始时间。
• 大约每秒一个音效。 在按下、可见的到位动作和钩子的节拍处，根据测量出的同步点添加音效；150 ms 内最多两个，旁白下方要留有安静的间隔。宁少勿滥。
• 修改字幕时必须保持字数不变。 较长的 text 会占用下一条字幕的 id，并把两条合并。先使用 captions: "list" 读取 get_video；如果发生合并，就设置完整文本和 split_after。
• 大字显示时，绝不删除字幕。 使用偏移量为 400 的字幕范围将其隐藏。删除字幕会删掉提词器要读的字词，并使其余字幕重新编号。
• 除非有人要求，否则绝不生成真人。 摄像机的替代形象是绘制的剪影。需要露脸的视频会预留摄像机位置，由当事人自行录制。
• 未经告知价格并获准，绝不花费任何费用。 每次都先设置 max_credits: 0。语音费用约为每分钟 ⚡7 点。此技能的其他所有内容均免费，包括全部渲染和整个编辑过程。
• 绝不发布任何内容。 视频导出并检查完毕后，就算完成。发布是当事人自己的步骤。

源影片和本片中的数字

项目	数值
时长	57 至 60 s，每秒约 2.6 个词，共 146 至 155 个词
画布	短边为 1080：1440 × 1080、1920 × 1080、1080 × 1080、1080 × 1920；以 2× 渲染
帧率	剪辑使用 60 fps；草稿以 1× 使用 30 fps
部分	开场 3 至 6 s；优势 12 至 20 s；快速教程 22 至 30 s；试试看 6 至 14 s
场景	10 至 12 个，每个约 4 至 8 s
结尾	最后一个词结束后约 2.4 s
标题	4:3 为 62 px，16:9 为 76 px，9:16 为 78 px；双层语调：引入语和陈述句
音效	每秒约 1 个；本片 59 s 中有 64 个，其中 18 个是打字时的按键声
配音	ElevenLabs v4 使用预设语音朗读 146 个词，耗费 ⚡7
字幕	一分钟耗费 ⚡1
角落摄像头	374 × 210，距右侧和底部各 40 px（4:3、16:9）
响度	−14 LUFS

验证

• 第一帧就是封面：标题和最佳画面都已绘制完成。
• 在已渲染的每种外观、画布比例和摄像头设置下，check-film.mjs 检查结果全部通过。
• 画面和配音中的每项声明都在 Explainer.md 的列表中，并已对照产品核实。
• 至少以两种外观检查过场景静帧，而且两种外观下的效果都不错。
• 配音内容与脚本一致；尤其要核对名称和数字。
• 导出视频中的动作都与对应词语同步（以 0.25× 速度抽查几处）。
• 逐一检查所有高亮部分和开场的全尺寸裁剪图：没有模糊，也没有裁切。
• 从导出视频中每隔 0.5 s 抽取一帧：文字没有被裁切，字幕没有被大字遮挡。
• 综合响度为 −14 LUFS ± 1，真峰值低于 −1 dBTP。
• 章节标题标明各个部分。

文件

• scripts/explainer.js、scripts/explainer.css：引擎及其组成部分：film()、times()、按画布比例和摄像头划分的区域、show()、ring()、view()、pointer()、字幕和预览占位内容，以及控件。
• scripts/render.mjs：将场景渲染为 MP4、完整影片或静帧和图集，支持任意外观、画布比例和摄像头设置。
• scripts/check-film.mjs：放大图片、柔和 3D、两个标题、边缘、摄像头角落、可重复的帧。
• scripts/read-look.mjs：测量网站外观，并将其整理为变量块和一份说明，列出还需你完成的部分。
• scripts/words.py：计时工具：根据 Fil 的字幕列表计时，或根据脚本生成自由草稿。
• scripts/sfx.mjs：已放置并调好音量的音效片段，以及在 Fil 中添加这些音效的命令。
• scripts/preview.mjs：在本地生成带字幕、配音、音乐和音效的完整影片。
• references/format.md：四个部分、脚本、场景模板，以及如何讲解一个想法而非产品。
• references/looks.md：所有变量、如何读取或命名外观，以及已完成的外观示例。
• references/camera.md：开启摄像头：插槽、按关键帧布局、标题、提词器、录制片段。
• references/fil-editor.md：通过 MCP 在 Fil 视频编辑器中进行剪辑所需的全部命令。
• references/sound.md：音效片段、同步点和音量、音乐，以及试听方法。
• references/checks.md：检查内容、检查器无法识别的内容，以及盲测评审。
• sounds/：来自 earshot 发布套件的 24 个音效，附有测量得出的同步点（MIT 许可证）。
• demo/：此技能自己的影片，实时呈现：场景、四种外观、台词和配音，并可切换外观、画布比例和摄像头。

不使用 Fil。 剪辑属于 Fil，但影片不一定非得用 Fil 制作：scripts/preview.mjs 可在你自己的机器上，使用任意配音文件及其词语时间戳生成最终 MP4（words.py --json）。