onetake

onetake

围绕产品打造的短片，由产品本身构建。它不是视频编辑器，也不是幻灯片生成器：而是一个合成作品（一个 HTML 文件，window.__seek(t)）、一个动态库（lib/motion.js）、从真实产品录制的素材、共享同一空间的声音调色板，以及一个预言器，用于在人类观看之前判断剪辑是否有节奏、是否连贯。

六部短片让它逐渐成形。motion-web 剪了三版：第一版和第二版都因节奏单一而被否决，评价是「PPT 式一个一个展示」——这就是节奏这一半。Pocket Weather Club 有节奏，却仍然像 PPT：v1 通过了所有节奏检查，却还是被否决，因为每个节拍都会取代前一个。v3 获得认可，因为每个节拍都从上一个节拍中生长出来——角色落在标题上，页面从卡片中延展出来，舞台从角色身边展开。这就是连贯这一半。One dot 补上了运镜：静止镜头下，评价是「就缺灵动的跟踪运镜」；镜头跟随每个节拍所呈现的内容——带着滞后、倾斜和停稳——则评价为「运镜、镜头和物理都没问题」。knockon 通过因果实现连贯：一台轻巧的台面机器，每个节拍都是引发下一个节拍的碰撞。clearing 通过尺度实现连贯：一个镜头从一年跨到半小时的空闲时间，再回到一年；镜头跟随屏幕上的锚点，让它在 1× 和 300× 下落在同一位置。overlap 让我们领悟了意义的重要性：它的第一版被评价为「美术挺棒但没看出来啥意思」，加上带标签的光标后反而更糟；只有当概念融入艺术作品本身时，它才变得易懂——两个噪声图层中藏着一个 &，在两层轨迹重合的瞬间显现。这里的一切，都是为了让下一部短片从这些短片结束的地方开始。

何时使用这项技能，何时不使用

• 为应用、页面、技能或功能制作的发布 / 预告 / 介绍短片——是。
• 介绍功能的旁白演示片（30–60 秒），展示产品的使用方式，可能包含多种语言——是：重建界面，而不是录制界面（§4，references/product-demo.md）。
• 用户有一段想要借鉴其感觉的参考片段——是，从 §1 开始。
• 长篇内容、真人访谈、用转场剪辑现有素材——不。
• 用户明确指定 HyperFrames 或 Remotion——使用他们指定的工具；否则使用这套流程。

流程——必须按顺序执行，不得跳过

1 · 先拆解参考内容，再动手做任何事（硬规则）

python3 scripts/analyze_ref.py ref.mp4 --out ana/     # energy map, cuts, stillness, contact sheets, motion line

阅读能量图和分析表，记下短片必须匹配的数值。能量图说明短片何时运动；motion: 这一行说明如何运动——t80 中位数（快速收紧还是 S 曲线）以及拖影（是否使用运动模糊渲染）。motion-web 短片的运动方式由这些数据决定：参考片有 34 % 的时间完全静止，分成两段出现 7 次硬切，而且所有元素都很小，留白很多。这些特点光看一遍很难察觉；没有测量就制作出来的短片，节奏会变得单一——而且发生了两次。references/reference-deconstruction.md。

2 · 概念——节拍表之前的三个核心想法（硬规则）

概念是关于画面而非产品的一句话：构成影片的唯一想法。写出三个在想法上各不相同的概念——而不是用同一组卡片讲三个故事：

• 一个元素贯穿始终并不断变形——一个点变成插入符号，分裂成技能列表，凹陷成加载环，展开成弹簧曲线，最后落在字标中 i 的点上；
• 一个镜头运动穿越不同尺度——从插入符号内部开始，拉远到输入框，穿过发送按钮潜入工作过程，再从完成的影片中出来（cases/clearing-15s：一年 → 一天 → 半小时 → 返回）；
• 前后分屏——左侧以幻灯片形式呈现相同节拍，右侧则将其延续，直到右侧融入左侧；
• 连锁反应——每个节拍都是引发下一个节拍的碰撞（cases/knockon-15s）；
• 或者采用实体隐喻、连续表面、字体系统……

对每个概念，说明钩子画面、贯穿每个边界的元素、它排除的做法（不用卡片？不用剪切？），以及视觉风格——选择 looks/ 中的预设（python3 scripts/look.py sheet → gallery/sheets/looks.png：paper、dusk、tabletop、ultramarine、riso、ember，均取样自已验收的影片）、产品自身的颜色（look.py from-shot shots/*.png --out look.json），或专为这部影片设计的风格。展示三个概念，让用户选择。模板中的故事——动态文字 → 输入提示词 → 不断跳动的清单 → 结果 → 急促的连续镜头 → 黑底字标——只是一个概念，绝不是默认方案：一个基于此方案制作的操作演示通过了所有 oracle 环节（carry 1.00），却被退回，理由是「和 motion web 很像…没有创造力」。

3 · 分镜兼顾节奏与延续性

将选定的概念写成节拍表：t · 节拍 · 运动元素 · 静止元素 · 延续到下一节拍的元素。

节奏。 镜头时长变化至少达到 4 倍（0.25 s 的文字镜头与 2.5 s 的停留镜头相邻）。画面和声音中至少有一段近乎静默的部分。讲述一个故事——概念本身的故事——而不是罗列内容。小元素，大场景。

延续性。 在每个段落边界处，指出延续下来并继续运动的元素：手、主体、变成下一场景的容器（morphRect）、从主体展开的舞台（iris）、推进卡片直至卡片成为场景的摄影机（zoomThrough）、折叠成标识的演员阵容（gather → seal）。如果没有任何元素延续，无论节奏如何，这就是幻灯片切换。硬切只适用于概念中包含的连续快节奏镜头和片尾卡。references/rhythm.md。

4 · 真实场景实拍——或根据截图重建界面

python3 scripts/record_footage.py footage.json --out footage/

使用 Playwright 实时操作真实页面（按墙上时钟节奏扫动、滚轮滚动、点击），按照成片展示尺寸录制，并在输入开始的瞬间注入洋红色标记，方便之后找到动作发生的帧。帧以 30 fps 的 JPEG 格式输出；同时保存指针路径，让合成过程可以重新绘制手部——观众必须看到原因，而不只是结果。配置格式见脚本的文档字符串。

或者重建界面。 当影片介绍应用的功能（尤其是有旁白或其他语言版本时），用户只录制或截取参考画面，再按照参考图自身的像素尺寸用 HTML 重建界面。所有字符串都存放在表格中，每个状态都由纯函数 set(state) 编写，副本位于同一平面上，摄像机可以任意缩放并拉近。高亮位置从其 DOM 中测量（lib/ui_kit.js）。旁白来自 scripts/vo_tools.py：试听、台词、词语时间点、字幕。第二种语言通过同一合成中的 ?lang= 指定，其旁白根据表达相同含义的词语上的 UIK.timeWarp 节点映射到已创作的时间线上，并使用 scripts/frame_diff.py 检查源语言画面是否逐像素一致。内容始终是产品的真实输出。方法、数据和具体内容：references/product-demo.md。这是一种制作手法，而非固定视觉风格：每次都在 §2 中重新选择调色板、舞台、镜头语法和转场。

5 · 合成——一个文件、时间的纯函数，以及从库中选用的动作

mkdir -p cases/my-film && cp templates/comp.html lib/motion.js cases/my-film/   # the template loads motion.js → window.OM
python3 scripts/probe.py my-film/comp.html        # as soon as it plays end to end: what carries each boundary, each move's curve

查看 gallery/sheets/<move>.png，观察动作随速度曲线变化的六帧展示，据此挑选动作。库中有 39 种动作：入场、移动、接触与实时模拟、摄像机及其投影辅助工具，还有一组流体效果（光场、涟漪、丝绸、传送带、SwiftUI 弹簧）；每种都是一个时间函数，返回用于 DOM 变换或 canvas 调用的数值。切勿用固定常数重新推导弹簧或缓动效果。模板是 motion-web 影片（动态文字、输入提示词、逐项勾选的清单、飞越镜头、实时模拟、停留、断续打击，以及所有模拟共用的一条连续手部路径）——仅当 §2 选定的概念适用时，才照搬它的节拍；否则保留其约定和辅助工具，并为该概念编写自己的节拍。一切都是 f(t)；模拟只需以 240 Hz 预模拟一次，再进行采样。使用 ?play 预览，使用 ?t=6.4&hud 固定时间点。参见 references/motion-library.md、references/composition.md。

视觉风格随合成文件一同交付。 运行 python3 scripts/look.py apply ember cases/my-film/comp.html（或指定一个 look.json），会在旁边生成 look.js：将八种颜色设为 CSS 变量和 LOOK.color，并内嵌三个 OFL 字体子集，这些子集仅包含合成文件实际使用的字形，以便 file:// 渲染能使用真实字体。请在合成文件的脚本之前加载它，并使用 var(--ink) / var(--display) 或 LOOK.font('display', 96) 编写样式；同时在 LOOK.ready 上串接 window.__ready。修改文案后请重新运行；如果字体缺少某个字符，脚本会指出该字符（中文 / 日文 / 韩文请使用 --cjk <font>）。

摄像机：设定关键帧，但要像操作摄像机一样运镜。 OM.camera(t, keys) 会将摄像机置于每个节拍所需的位置；要有操作员掌镜的感觉，关键在于关键帧的设置方式：使用 sineInOut，提前约 0.1 s 为主体设置关键帧，以跟随主体；使用 expoInOut，在快速移动前先为落点设置关键帧，让镜头迅速切向落点；加入手持效果（缓慢的双正弦浮动，停留时归零），并在每次落点时调用 OM.shake。在更远处绘制淡淡的 OM.lattice，或者在空旷地面上绘制，避免动作无法呈现清楚。使用摄像机时，__track 会返回屏幕坐标框（OM.projectBox），__motion 会向 render.py 提供移动轨迹，__meta.inFrame 则列出任何情况下都不能移出画面的内容。方法和代码见 references/composition.md → A camera。

6 · 渲染 — 1080p30 草稿，仅在验收后使用 4K60

python3 scripts/stills.py comp.html --times 0.7,2.4,3.8,6.2,9.9,12.7 --out stills.png   # look before you render
python3 scripts/render.py comp.html --out draft.mp4 --sfx sfx.wav            # 1920×1080 · 30 fps · 180° shutter
python3 scripts/render.py comp.html --out film.mp4 --final --sfx sfx.wav     # 3840×2160 · 60 fps, once the cut is accepted

快门带来真实的运动模糊：每个运动帧都会在快门开启期间多次跳转，并在线性光下取平均；检测到静止帧时则会跳过。一次截图是 Chrome 截图（约 150 ms；页面本身在 1 ms 内完成绘制），因此 render.py 会通过并行进程运行 --workers 个浏览器（默认核心数 − 2，最多 8 个）。定义了 window.__motion(t0, t1) 的页面——该函数表示屏幕上任何元素（包括相机）的最大移动距离——会为每帧采集足够多的画面，让保留的画面之间相隔 6 px（4–48）；固定使用 8 次采集曾让 one-dot 影片每帧 633 px 的开场出现条带。耗时估算：one-dot 的相机镜头在 8 个 worker 上采集 2,480 张画面耗时 103 s（单个浏览器：每张约 0.2 s，约 8.5 分钟）——开始长时间渲染前，请告知用户预计耗时。WebGL 合成使用 --gpu 渲染（Chromium 基于 ANGLE/Metal）；不启用时，无头 Chrome 会使用 SwiftShader 绘制，成本约为 4 倍（references/3d.md）。

7 · 声音 — 在同一个空间中运用一组音色，而非每个事件都配一声提示音

python3 scripts/sfx_palette.py --demo demo.wav     # quick pass: the synthetic palette (see templates/sfx_score.example.py)
python3 dump_events.py && python3 score.py         # the films since one-dot: the comp's __events() → recorded + synthesised mix

有两种做法，但遵循同一条规则。音色组由五种合成材质（空气、木头、玻璃、低音、气泡）构成，统一使用一种混响，峰值为 −8 dBFS，让音乐可以叠加其上——足以用于草稿。自 one-dot 以来，每部通过验收的影片都使用 score.py：将录制音源（Kenney 的 CC0 音效包、UIowa MIS、Voxengo IR——此处不提供，请自行下载）与合成音效叠加，根据 window.__events() 定时和声像定位，使用卷积混响，让音乐在音效出现时降低音量，并将响度母带处理到 −16 LUFS，同时将峰值上限设得足够低（−3.5 至 −4 dBTP），确保 AAC 渲染结果低于 verify 的 −3 dBFS。无论采用哪种方式，事件都应少于节拍：motion-web 的第一版曾为每个事件加上原始正弦波啵声，短短一分钟内就因质量低劣而被否决。在产品中使用任何录制音源前，请先检查其许可协议（Mixkit 不允许重新分发文件）。references/sound.md。

默认使用免版税音乐。 寻找获准重复使用的曲目（NCS、Pixabay Music、YouTube 音频库、采用允许重复使用的 CC 许可的 Free Music Archive），并将其来源和许可信息与配乐一同保存。只有用户提供商业音乐或受版权保护的音乐并明确要求使用时，才能将其加入；切勿自行选用。

8 · 展示前先验证

python3 scripts/verify_promo.py draft.mp4 --comp comp.html --ref ref.mp4 --shots 0,1.6,3.0,4.8,7.0,9.6,12.1,13.25,14.3

Rhythm 检查会因镜头时长过于均匀、长时间静止，以及音频削波或始终没有安静片段而失败。burst 仅在提供了 --ref、但影片中没有爆发段时才会失败；未提供参考时只会发出警告——没有冲击点的概念并非错误。continuity 会在节拍彼此替代时失败（衔接分数 < 0.5）——这是唯一一项让两个未通过的 Pocket Weather 剪辑都失败的检查（v1 为 0.00，v2 为 0.40），而通过验收的影片均通过了检查（v3 为 0.75；motion-web 为 0.56，仅发出警告）。curves 会在没有快门模糊的影片中出现快速移动（> 80 px/frame）时失败。framing 会在任意一帧中，__meta.inFrame 里的某个 id 位于画面外时失败（若标记为 'whole'，则在元素被切掉时失败）——one-dot 影片的首次相机渲染中，一个快照遮住了圆点，其他检查都没发现。提供 --ref 时，还会同时打印参考影片的能量图和运动曲线。

硬性规则（每违反一条都要返工）

• 绝不默认沿用模板的故事。 三个核心创意各不相同的概念；由用户选择 （§2）。如果新影片沿用模板的节拍，无论制作多精良，读起来都会像模板。
• 绝不把上一部影片的视觉风格带到下一部。 调色板、舞台、镜头语言、转场：工具 （复刻、旁白、时间扭曲）可以复用，视觉风格不行。在概念讨论阶段明确这些选择。按名称选定 looks/ 中的预设没有问题；默默套用默认值不行。
• 第二种语言绝不能另开一个构图版本。 ?lang=、时间扭曲版和源剪辑必须逐像素一致。复制一份合成会让之后的每次修复都要做两遍。
• 绝不按节拍器剪辑。 镜头时长相同，无论每个镜头多精良，都会让影片看起来像幻灯片。
• 绝不替换一个节拍——要让它延续下去。 每个章节交界处，都要有屏幕上的某个元素延续下来，并以可见的移动或缩放融入下一个节拍。互斥场景（通过 display:none 切换）即使节奏完美，也还是幻灯片。 例外情况是快速连续的硬切镜头，以及片尾卡。
• 绝不把页面缩成缩略图，指望观众看出它的动态效果。 要么让页面连同手部一起铺满画面，要么让其中的一个组件在卡片中实时呈现。缩小的整页卡片毫无表现力。
• 绝不让画面始终处于运动状态。 静止段落能衬托出动势爆发；参考影片有三分之一的时间是静止的。
• 小元素，大留白。 该类型的画面有 70 % 是白色。全屏出血画面是例外（只静置一个片段），不是常规做法。
• 必须让原因清晰可见。 可以是沿录制路径绘制的手，也可以是概念自身的主体——一个分裂的点、一颗落地的球。没有任何原因却产生反应的页面，看起来就像屏幕保护程序。
• 动作取自库，曲线按 t80 选择。 到处使用同一个手工编写的 smootherstep，会让每个动作都变成同一种柔和的 S 曲线；快速收尾（ease.expoOut，t80 .23）和弹簧效果才更有冲击力。
• 快速移动需要快门效果。 每帧移动超过 80 px 而没有动态模糊，就会频闪出重影。render.py 的默认快门设置可以解决这个问题；CSS 模糊不行。
• 摄像机要追随主体，而且绝不能让主体出画。 静止摄像机让单点影片显得「就缺灵动的跟踪运镜」；而追随每个节拍中所框定主体的摄像机方案得到了认可。声明 __meta.inFrame；对于快速收尾，先设置落点，再开始移动。
• 草稿以 1080p30 输出。 剪辑获批之前，不要以 4K60 输出。
• 不要使用粒子、纸屑或斑点爆发效果。 它们看起来像模板。如果某个节拍需要点缀，让字体本身带有挤压和摇摆效果。
• 音效只用一套材质，且空间统一。 每个事件都配一种合成音色，就是幻灯片的音频版本。
• 所有内容都必须确定。 两次调用 __seek(t) 必须得到同一帧——快门效果依赖这一点；模拟须使用固定种子预先计算；渲染路径中不得调用 Math.random()（使用 OM.rng(seed)）。

文件

path	内容
lib/motion.js	动作库 → window.OM：曲线、弹簧、入场、承接、接触、模拟、相机、流体
looks/looks.json	六种初始外观（八个颜色令牌，每种三个面孔），根据通过验收的影片测量得出；looks/fonts/ 中是 OFL 字体及其许可证
scripts/look.py	使用 list / sheet / check 查看外观；使用 from-shot 从产品截图生成外观；使用 apply → look.js，其中包含并内嵌面孔子集
lib/ui_kit.js	→ window.UIK：在平面上重建的 UI（stage、domLocal、rectCache、flow）、贴合内容的 glowRing、易读性（screenPx、zoomFor）、语言（tr、loadFont）、旁白与创作时间轴之间的 timeWarp、subAt
gallery/gallery.html	每个动作各有一个实时演示（?demo=ribbon&play）；gallery/sheets/<move>.png 为六帧画面 + 速度图；gallery/sheets/looks.png 为外观
scripts/analyze_ref.py	参考素材 → 能量图、切镜、静止段、联系表、运动线（t80、拖影）、JSON
scripts/record_footage.py	配置 → 实时录制并带有动作标记 → 30 fps 帧 + 路径
scripts/probe.py	合成片段 → 逐帧显示的画面 → 每个边界处的连续性、每个动作的曲线
scripts/render.py	合成片段 → mp4：默认输出 1080p30 草稿，--final 输出 4K60，按 __motion 设置快门运动模糊，使用并行 --workers，使用 --gpu 启用 WebGL，生成 .render.json
scripts/stills.py	合成片段 → 所选时间点的联系表
scripts/vo_tools.py	旁白：tts（Kokoro，通过假名读音生成英语和日语语音，提供试听）、words（faster-whisper）、plan（台词起始时间）、subs（分块并定时）
scripts/frame_diff.py	在所选时间点对比两个合成片段（或带 ?lang= 的一个片段）→ 判断是否相同，并生成差异图像
scripts/sfx_palette.py	声音素材、空间、Score 助手、--demo
scripts/verify_promo.py	验收判定工具：节奏支点，以及使用 --comp 检查连续性、曲线和构图
scripts/gallery.py	画廊演示 → 图页
scripts/test_motion.js	node scripts/test_motion.js — 动作库的数值
templates/comp.html	基于动作库的合成片段骨架（motion-web 影片）
templates/footage.example.json	motion-web 影片使用的素材配置
templates/sfx_score.example.py	motion-web 声音评分
references/reference-deconstruction.md	如何用数字解读参考素材
references/rhythm.md	节奏（motion-web 的三次剪切）和承接（Pocket Weather 的三次承接）
references/motion-library.md	所有动作、将动作应用于 DOM 或 canvas、曲线表，以及各边界适用的承接方式
references/composition.md	f(t) 架构、基本元素、手部路径、探测、渲染和快门
references/sound.md	音色、空间、音量，以及听起来廉价的部分
references/product-demo.md	无需录屏的功能演示：复刻、易读性、从 DOM 提取高亮、旁白、语言与时间变速、品牌结尾片段，以及失误之处
references/3d.md	3D 影片：Blender（MCP）模型 → GLB → 合成片段中的 three.js、用于 file:// 的 IIFE 包、--gpu（使用它进行渲染：SwiftShader 会使成本增加约 4 倍）、实例化 LOD、不使用物理效果而以 f(t) 表示的链条、3D 相机、必须能读清的场景文字
cases/motion-web-15s/README.md	案例 1：节奏影片 — 节拍表和数值
cases/one-dot-15s/README.md	案例 3：一颗点构成整部影片 — 概念步骤、操作员的相机、录制 + 合成声音
cases/knockon-15s/README.md	案例 4：灯光连锁反应影片 — 因果承接、从阴影表现高度、根据合成片段的 __events() 定位声音
cases/clearing-15s/README.md	案例 5：一镜到底的尺度穿越 — 用各自的单位绘制层级、适用于 1×–300× 的屏幕空间相机、由缩放速度驱动的声音
cases/pith-21s/README.md	案例 6：反向穿越 — 从一个磷光像素放大 440× → 缩小至 0.52×，将产品自身的暗→亮主题切换作为影片唯一的转场，以吉祥物特写打破节奏，并用屏幕上已有的七个物体构建论点
cases/ebb-15s/	案例 7：一镜穿过五个地点，由光场承载 — 带手部动作、抖动和景深的关键帧相机、里程计数字、漫过画面并以环形退去至下一场景的洪水、在三个深度的传送带上移动的丝绸卡片
cases/domino-25s/README.md	案例 9：12,346 部手机，每部占一个像素 — 经过测量的 Blender 模型在 three.js 中实例化，在音乐节拍网格上设置触发时间，跟随节拍进行 FPV 飞行和阶梯式拉远，密集链条的拟音群
cases/infra-25s/README.md	案例 10：每张图像都始于热量 — 用参考素材自身的运动语言制作 2D 影片，在真实照片上通过 SVG 滤镜实现热成像伪彩色和逐像素冷却（不使用 canvas），在经过测量的音乐网格上安排画面，并通过测量修正混音（一段 141 ms 的重音，随后是共用一个低频段的拟音和配乐）
cases/clawd-desktop-19s/README.md	案例 11：吉祥物就是指针 — 将 macOS 桌面呈现为 three.js 中的玻璃桌面，通过透射效果制作 Liquid Glass 窗口，每项 UI 操作都由角色的身体触发（点击、输入、拖动、窗口的“拒绝”），相机跟随 Dock 移动，并在 Mission Control 出现时升高，配乐自身的骤停则成为高潮前的呼吸
cases/<film>/	使用此技能制作的每部影片：影片和一份 README（节拍表、数值、被舍弃的内容及原因）。另有：overlap、unbroken、skill-demo，以及 onetake 自己的宣传影片。不包含影片的源代码
需要：带有 playwright（chromium）、numpy、scipy、Pillow、matplotlib、fonttools + brotli（用于视觉效果）的 python3；用于运动线的 opencv-python；ffmpeg / ffprobe；用于库测试的 node。旁白：faster-whisper（python3）和 Kokoro（kokoro-onnx、soundfile，以及用于日语的 misaki[ja] 和 unidic-lite），安装在 ~/.cache/kokoro/venv 中。