Kinetic Cut Video

---
name: kinetic-cut-video
description: 制作"卡点快剪"风格的短动效视频（片头、开场、产品/品牌/活动宣传、学校或机构介绍、个人或项目介绍、数据亮点、年会暖场等任何主题）：每秒一个满屏镜头，硬切 + 闪白 + 镜头冲击，带运动模糊、辉光、色散和合成配乐，输出 1080p60 MP4。镜头、运镜、转场、配色、字体、配乐、文案每次都从题材重新设计，不套模版。用户要"炫酷/有冲击力/动效感强的视频、片头、kinetic typography、motion graphics、快剪"时使用。需要 node + Playwright(Chromium) + ffmpeg + python3/numpy。
---

# 卡点快剪动效视频

用一个 HTML 页面（Canvas 2D，画面是时间 t 的纯函数）+ Playwright 逐帧截图 + ffmpeg 合成，做 10–30 秒的快剪动效片。本 skill 提供**引擎和零件**（镜头冲击、运动模糊、辉光色散、文字与绘图零件、渲染与配乐脚本），**画面内容每次从题材本身设计**。

> **目标：每一条片子在动效、运镜、转场、美术风格、配色、字体、配乐、文案、开场和收尾上都是新的。** 本 skill 的默认值（120 BPM、D 大调、陶土橙配色、取景框 HUD、闪白 + 色散）只是能跑通的起点，不是风格。
>
> **最常见的失败是"换皮"：** 拿演示片换文案和配色就交付。这样做出来的视频，把文案换成任何别的题材也一样成立——观众一眼就能看出是模版。下面第 2 步的母题流程和第 5 步的换皮测试就是为了防止这一点，不能跳过。

## 文件

| 路径 | 作用 |
|---|---|
| `assets/template/` | **新工程的起点**：`engine.js` 引擎 + 空骨架 `index.html` + 配乐骨架 `audio.py` |
| `references/motif-method.md` | **母题方法**：怎么从题材找视觉元素、写分镜、做换皮测试、写新技法（含两个示例）——**写分镜前必读** |
| `references/fx-api.md` | 引擎函数与 `FX.*` 配方速查 |
| `examples/showreel/` | 18 秒技法演示片：每个镜头展示一个 `FX` 配方。**只用来查函数怎么调用，不要从它起步，不要照搬它的镜头顺序** |
| `scripts/render.mjs` | Playwright 渲染：`info` / `stills` / `frames` |
| `scripts/build.py` | 抽帧联系表、并行渲染（可续渲）、配乐、编码、成片联系表 |
| `scripts/brief.py` | 创意方向抽签：美术风格、配色、字体、节奏结构、BPM、配乐风格、调式、运镜、转场、后期质感、文案语气、开场、收尾、装饰层各抽一项 |
| `scripts/audio_lib.py` | numpy 合成器：pad / piano / bell / pluck / lead / sub / kick / snare / clap / hat / tick / boom / riser / whoosh / vinyl；`chord()` `scale()`、`beat(pattern, swing)`、`arp()`、`chord_hit()`；`render(rms=)` 按目标响度混音 |

## 流程

### 1. 明确内容（缺什么问什么，问一次）
主题与用途、时长（默认 20 秒）、要出现的文案/数字/名称、品牌色或标志（以及能否使用）、画幅（默认 1920×1080）。信息够就直接做。事实性内容（年份、名称、口号）要有出处；容易过时的数字（人数、排名）不放，或请用户提供。

### 2. 创意方向、母题与分镜（写进工程目录的 `storyboard.md`）
先跑 `python3 <skill>/scripts/brief.py "<主题>"` 抽一组创意方向，把每一项怎么落到这个题材上写下来。抽签是为了打破惯性：和题材明显冲突的项可以重抽（换 seed）或改，但要写理由；不要因为"麻烦"就退回默认的那一套。然后按 `references/motif-method.md`：

1. **母题清单**：这个题材独有的 8–12 个视觉元素（器物与仪器、材料与纹理、符号与记号、界面与图表、地点与历史、动作与过程），选出一条贯穿全片、首尾呼应的主线母题。
2. **分镜表**：`时间 | 时长(拍) | 画面 | 来自哪个母题 | 技法（新写 / 改造的 FX.x）| 构图 | 文字入场 | 明暗/主色 | 文案 | 怎么接到下一镜`。后四列是为了让你在动手前就看出全片内部有没有重复。
3. **硬性要求**：
   - 至少一半镜头的技法是为这个题材**新写**的；复用的 `FX.*` 每个最多一次，而且要改造成题材的样子。
   - 不照搬演示片的镜头顺序和节奏结构。
   - 开场、收尾必须是题材专属画面；转场优先用母题做匹配剪辑（波形变走线、走线汇成芯片……）。
   - `FX.star` 近似 Claude 标志，只在介绍 Claude 时使用。其他题材用自己的标志（获准使用时用 Canvas 路径画出）或文字标。不要仿冒真实品牌的标志或页面。

全片内部也不能重复（每个镜头都新写了画法，片子仍可能显得单调，原因多半在这里）：
- **时长有起伏**：镜头长短混用（1 / 2 / 4 / 8 拍），整体有一条节奏曲线——铺垫、加速、喘息、高潮、定格。不要每个镜头都是同样的拍数。
- **构图不重复**：给每个镜头标构图（左物右字、居中、满版、出血裁切、上下分、对角线、大面积留白、分屏……），同一种最多用两次；至少一个镜头文字大到被画框裁掉，至少一个镜头大面积留白。
- **文字入场有 3 种以上**：砸入、逐字打出、由母题组成（点阵、走线、粒子）、遮罩擦出、翻转、拉伸……不要所有标题都用同一个入场函数。
- **明暗与色彩有节奏**：全片至少有一次亮底、反相或强调色铺满全屏；**高潮镜头要打破前面建立的视觉系统**（换底色、换尺度、换节奏），否则"最重的一下"看起来和其他镜头一样。
- **每个镜头内部两层动作**：主动作（入场、变形）之外，还要有持续的次级运动（缓慢运镜、呼吸、粒子、扫描），镜头后半段再安排一个小事件，避免文字落定后画面停住。

节奏规则：
- **节拍网格**：按 brief 定 BPM。切点、砸字、重击落在拍点上；平均每 1–2 秒一个新镜头或新事件；高潮段可 0.25 秒一切；开头 0.5 秒内要有第一个冲击。
- **判断标准**：任意暂停一帧都像一张海报，任意一秒都有新东西发生。
- **文案极少、字极大**：主文字 300–620px、最粗字重；每个镜头最多一句副文案（≥40px）。
- **配色、字体、后期质感、装饰层**：按 brief 和题材定，写进 `KCONF`（`palette` `fonts` `caBase` `caHit` `flash` `punch` `vignette`）和 `hud`。HUD 默认关闭，取景框 + 时间码只是装饰层的一种选择。
- **运镜和转场**：按 brief 选一种运镜语法做全片主调（固定机位硬切、持续推进穿越、横移、俯冲旋转、分屏……），但每个镜头的方向、速度、尺度要有变化，全片至少 3 种运镜；转场家族也统一而有变化。不要每个切点都只是"闪白 + 推一下"，也不要每个镜头都是同一个推拉。
- **文案**：语气、句式、信息密度按 brief 定，用题材自己的说法；不要沿用演示片的"一个词一镜 + 一句副文案"结构到每个镜头。

### 3. 建工程并逐镜实现
```bash
cp -r <skill>/assets/template <工程目录>     # engine.js + 空骨架 index.html + audio.py
```
- `window.KCONF`：尺寸、帧率、`palette`、`fonts`（先 `fc-list | grep -iE "Noto|CJK|Mono"` 确认字体存在且有粗字重）。
- 每个镜头一个函数 `(g, t, u)`：`t` 绝对秒，`u` 镜头内秒。**只能依赖 t/u**——不用 `Date.now()`、`Math.random()`（用 `rng(seed)`）、CSS 动画或跨帧状态，否则无法分段并行渲染。
- 新技法用零件拼：`drawOn`（按进度描线）、`noise1`（平滑噪声）、`stg`（错峰进度）、`cjk` / `word`（逐字变换）、`layer`（遮罩）、`FX.sample` + `FX.assemble`（任意形状的粒子聚合）、`blobs`（光斑背景）。写好一个技法先单独抽 2–3 帧确认，再接下一个。
- `K.start({duration, hud:{title}, shots:[[起,止,函数,{label,hud,bloom,samples}]...], hits:[[时间,强度,震屏px]...]})`：
  - `bloom`：深底 0.5–0.6，强调色底 0.12–0.14，浅底 0.07–0.1。
  - `hud`：HUD 颜色（深底 `PAL.paper`，浅底 `PAL.ink`，上下不同传 `[上,下]`，可传函数，`false` 关闭）。HUD 的标题、标签也按题材写。
  - `hits`：每个切点一条（强度 1），半拍小切 0.5–0.6，最重的 1–2 处 1.3–1.4 并加 12–26px 震屏。引擎据此自动加镜头推进、色散、闪白、辉光脉冲。
- 重击落在切点那一帧：下落/砸入让"落地瞬间 = 镜头起点"，之后只做回弹（`FX.slam`）。入场用 `ex`（急停）或 `spr`（回弹），蓄力/吸走用 `ei`。

### 4. 抽帧预检（全片渲染前必须做）
```bash
python3 <skill>/scripts/build.py <工程目录> stills          # 每个镜头自动取 2 个时刻，拼成 stills_sheet.jpg
python3 <skill>/scripts/build.py <工程目录> stills 6.6 12.5  # 或指定时刻
```
看联系表，再挑 2–3 张 `stills/NN.png` 看原尺寸：文字出框/重叠、辉光发灰、浅色镜头发脏、相邻镜头雷同、每个镜头是否一眼能读懂。控制台出现 `PAGEERROR` 说明页面脚本报错。

### 5. 换皮测试 + 快速预览（全片渲染前）
逐个镜头问：把文案换成另一个题材，这个画面还成立吗？成立的镜头回去换成母题画面；超过三分之一的镜头成立就重做分镜。再对照演示片：如果镜头顺序或技法组合和它基本一致，也要重做。

然后出一版快速预览（12 fps、无运动模糊，20 秒片约 2 分钟），看整体节奏并读质检报告：
```bash
python3 <skill>/scripts/build.py <工程目录> preview     # → preview.mp4 + qa_report.txt
```
质检报告量的是抽几张静帧看不出、又听不到的东西：镜头时长是否单一、每个镜头最长的近静止时长、各镜头的亮度和色相是否几乎不变、每个切点和强重击处有没有音频起音。报告里的每条警告都要处理，或者在交付说明里写明为什么保留。构图和文字入场是否重复、是否来自母题，报告量不了，要对照分镜表自己检查。

### 6. 配乐
从 `audio.py` 骨架写起。**风格、BPM、调式、和弦进行、节奏型、音色组合都按 brief 定**：例如 lo-fi 用 96 BPM + swing + `vinyl` + `pluck` 和弦；synthwave 用 `lead` + `arp` + `sub`；纪录片质感用 `pad` + 稀疏 `pluck` + `boom`；芯片音乐用低 `cutoff` 的 `lead`。和弦用 `chord('Em9')`，旋律音用 `scale('E','dorian')`。不变的只有一条：**切点必须有声音落点**（重音、鼓、冲击或音色变化），段落切换前有铺垫（`riser` 或停顿）。时间直接抄镜头表；`build.py` 会自动运行它。写法可查 `examples/showreel/audio.py`，但不要沿用它的和弦、音色和节奏。

### 7. 全片渲染与编码
```bash
nohup python3 <skill>/scripts/build.py <工程目录> render > <工程目录>/build.log 2>&1 &
# 轮询（单条命令不要超过 10 分钟）：
for i in $(seq 1 55); do grep -qE "video:|failed|missing|Error" <工程目录>/build.log && break; sleep 10; done; tail -5 <工程目录>/build.log
```
- 按 CPU 核数并行，已渲染的帧会跳过，中断后重跑同一命令即可续渲。改了页面后再渲染时，如果 `frames/` 比 `index.html` 旧，脚本会停下提醒：加 `--force` 全部重渲，或删掉改动镜头对应帧号的 PNG。预览遇到这种情况会自动重渲。
- 速度约 0.6–1.5 秒/帧；20 秒成片在 2 核机器上约 10–15 分钟。
- 输出 `out.mp4` + `qa_sheet.jpg`（每半秒一帧）+ `qa_report.txt`（同预览的质检，只是对成片再跑一次）。默认把文件压到 28MB 以内（`--max-mb`）；`--grain 0` 关颗粒；`--range A B` 只出某段帧；只改了配乐用 `encode` 模式重新合成。

### 8. 检查并交付
看 `qa_sheet.jpg`、`qa_report.txt` 和 ffprobe 输出（时长、帧数、有无音轨），然后发送 MP4，附逐秒镜头表。说明里如实写：
- 本次的创意方向（brief 结果及取舍）、每个镜头来自哪个母题，哪些是新写技法、哪些复用了 `FX.*`，换皮测试结果；
- 质检报告的结论（以及保留的警告和理由）；画面抽帧检查过；配乐是代码合成的、无法试听，切点落点已由质检确认，但听感需要对方确认；
- 用了哪些事实性内容及其来源；没用官方标志时说明用什么代替；为控制体积降了码率也要说。

## 常见问题

- **整体"像模版"**：回到第 2 步，母题清单是不是太泛（"科技感""光效"不是母题），新写技法是不是不到一半，配色/配乐/装饰层是不是又用了默认值。
- **整体"不够炫"**：通常是镜头太长、字太小、技法重复、切点没有重击。先查分镜表，不要靠堆后期特效补救。
- **每个镜头都新写了，但整体还是单调**：看分镜表的时长、构图、文字入场、明暗四列有没有重复，看 `qa_report.txt` 的警告；常见原因是每镜等长、都是"物体在一侧 + 大字在另一侧"、所有标题同一种砸入、全片一个色相没有亮暗变化。
- **快速运动出现条纹**：给该镜头加 `samples: 24`（或函数 `t => ...` 只在高速段提高）。
- **深色镜头发灰/文字发糊**：降低该镜头 `bloom`。**浅色镜头四角发脏**：`bloom` 设到 0.2 以下，引擎会自动减弱暗角。
- **镜头缩放或震屏露出黑边**：底色用 `fillAll`，自绘背景要多画出画面 200px 以上。
- **文件太大**：颗粒和高速粒子最吃码率，降 `--grain` 或 `--max-mb`。
- **不要边截图边把帧管道给 x264**（会抢 CPU，慢数倍）；`build.py` 已是先落盘再编码。
- **不要用 `pkill -f render.mjs`**（可能杀掉当前 shell）；用 `pgrep -fa node` 找到 PID 再 `kill`。
- **竖版 / 其他画幅**：改 `KCONF.W/H` 即可渲染，但 `FX.*` 的默认坐标按 1920×1080 调过，需通过各自的 `cx/cy/size` 参数重新排版并抽帧确认。
- `shadowBlur`、大字号 `strokeText`、全屏渐变都很慢，每个镜头只用在一两个元素上。