xiaoma-studio

# xiaoma-studio 一句话：**每一帧都是时间 t 的纯函数，先看拼图再出片。** 这份 skill 把 30 条高赞 Opus 5.5 视频（抖音 12 / X 10 / YouTube 8，最高 60 万赞、64 万播放）归纳成可执行的工作流、审美规则和一套渲染引擎。照着做，任何模型都能产出同一标准的视频和幻灯片。 ## 环境 ```bash cd <skill>/engine && npm install # 只装 playwright-core；浏览器复用本机 Chrome / Playwright 缓存 # 另需：ffmpeg、python3 + numpy（scipy 可选，加速音频合成） ``` 找不到浏览器时：`npx playwright install chromium-headless-shell`，或设 `CHROME_PATH`。 ## 工作流（不要跳步） 1. **Brief**：弄清楚主题、时长、画幅（16:9 / 9:16 / 1:1）、受众、有没有品牌素材 / 音乐 / 旁白。缺的按默认值来，不要卡住（默认值：16:9、30–60 秒、纯音乐 + 字幕叙事）。 2. **选风格原型**：从 `references/aesthetics.md` 的 10 个原型里选一个，整片只用这一个。题材和原型的对应关系见同一文档开头的选型表。 3. **写 STORYBOARD.md**：按 `templates/STORYBOARD.md` 写。要有一句话 logline、钩子、按拍排的镜头表、每个镜头要让观众「读到」什么、转场、首尾怎么呼应。写完先对照 `references/storyboard.md` 的检查表自查。有用户在场时，先给用户看分镜。 4. **搭合成**：`node engine/init.mjs <项目目录> video|slides` 建一个自包含项目（模板 + 运行时 + STORYBOARD.md），只改内容和镜头函数，不改 engine。动效写法见 `references/motion.md`，引擎 API 和坑见 `references/code-rules.md`。 5. **拼图自检循环**（最关键的一步）： ```bash node engine/render.mjs comp.html --sheet out/sheet.jpg # 默认每拍一帧；--every 1 = 每秒一帧 ``` 再跑一遍不需要看图的自动检查（每轮都跑，不能读图的模型更要靠它）： ```bash node engine/lint.mjs comp.html # 确定性（乱序渲染 = 顺序渲染）/ 文字对比度 / 文字重叠 ``` **能读图就打开图片亲自看**；不能读图的模型以 lint 全绿 + `--stills` 关键帧的像素统计为准，并在报告里写明「未目视检查」。按 6 项各打 1–10 分：前 2 秒钩子、手机尺寸可读性、动效质量、变化密度、风格一致、声画同步。修最差的 3 处，重出拼图，直到每项 ≥ 8 才进下一步。单个时刻用 `--stills 2.5,7.0 --dir out/stills` 看原尺寸。 6. **声音**：默认纯音乐 + 卡点音效。用 `engine/audio.py synth cues.json` 从零合成；用户给了音乐就先 `audio.py analyze` 拿到 BPM 和拍点，再把镜头对到拍上。需要旁白时看 `references/audio.md`（TTS 选型、逐字时间戳、闪避混音）。 7. **出片 + 体检**： ```bash node engine/render.mjs comp.html --out out/video.mp4 --audio out/audio.wav [--fps 60 --subframes 2] python3 engine/qa.py out/video.mp4 # 规格 / 响度 / 单帧跳变 / 静止段 node engine/lint.mjs comp.html # 交付前必须全绿 ``` 渲染整片可能要几分钟：放后台跑，或者分段跑（`--from/--to`），等 ffprobe 能读出时长再验收，别在文件写完之前就去跑 qa。 跳变和静止段要么修掉，要么能说清楚是故意的。 幻灯片：`node engine/render.mjs deck.html --slides out/slides --pdf out/deck.pdf`；同一个文件直接 `--out deck.mp4` 就是视频版。 ## 七条硬规矩（来自 30 条样本的共性） 1. **不剪，变。** 25 条成片里 11 条一次硬切都没有。镜头靠形变、泛洪、遮罩升起、推镜穿越、匹配剪辑衔接。硬切只用在卡点 MV 和对比类内容，而且必须落在拍点上。 2. **一底、一字、一强调色。** 一个底色、一个前景色、一个强调色。一个标题字体加一个正文 / UI 字体，最多再加一个等宽体放元信息。16/25 用暗底。 3. **字幕就是旁白。** 14/25 没有人声，只用音乐加屏幕文字讲完故事。字幕底部居中、逐字出现，中文下面压一行小号英文斜体（纪录片质感）。 4. **前 2 秒必须有一个物件在动**：骰子落地、金币分裂、红点弹出、光标点击。不要用「渐变底 + 居中标题淡入」开场。 5. **每 2–4 秒发生一件新事，一次只让观众读一件事。** 快动作，慢意义：动作可以很快，但它的意思要留够时间被看懂。 6. **首尾呼应。** 最后一帧要呼应第一帧：同一个物件、同一句话或同一个形状，状态变了。 7. **帧 = f(t)，先拼图后整片。** 见下方渲染合约。 **事实**：片子里出现的数据、年份、人名、研究结论，必须能说出处。查不到原始数字就不写具体数字（用「更多 / 更少」、趋势图代替），不准编。引用研究时把作者、年份写在画面上。 **禁用清单**：渐变底居中标题、所有元素都用同一种淡入、通用粒子背景 / 粒子爆炸、冲击波圆环、RGB 分离、镜头抖动、镜头光晕、霓虹发光（霓虹原型除外）、网格地板、闪烁背景、UI 上的弹跳缓动、四角乱贴科技标签（HUD 原型除外）、屏幕文字带句号、任何一眼就像模板的东西、超过 1 秒的无意义停顿、一个画面同时冒出两件事。 ## 渲染合约 - 画面只由 `MS.render(t => …)` 决定，同一个 t 永远画出同一帧。渲染器会乱序 seek，看拼图时尤其如此。 - 禁止 CSS transition / animation、setTimeout、在渲染里用 requestAnimationFrame、`Math.random()`、帧间状态。随机用 `MS.rng(seed)` / `MS.hash(i)`，弹簧用闭式解 `MS.spring()`。 - **跨镜头存在的层（canvas、全局元素）每帧都要设值或清空**，不能只在某个镜头里画。否则跳着 seek 时会残留别的镜头的画面。 - **转场层画在内容之上**（泛洪、擦除），新场景的元素在转场铺满之后才入场；否则 `qa.py` 会报单帧跳变。 - 外部视频素材先 `ffmpeg -g 1` 转成全帧内编码，再用 `MS.videoAt(video, t)` 精确 seek。 ## 什么时候读哪份参考 | 要做的事 | 读 | |---|---| | 选风格、配色、字体、版式、手机可读字号 | `references/aesthetics.md` | | 写分镜、排节奏、选叙事结构（纪录片 / 闯关 / showreel / 发布片 / MV / 角色科普） | `references/storyboard.md` | | 转场、形变、文字动画、数据可视化动画、角色动画原则 | `references/motion.md` | | 引擎 API、渲染 CLI、坑、性能 | `references/code-rules.md` | | 配乐、音效、拍点、旁白 TTS、混音 | `references/audio.md` | | 用 GPT Image 2 / 2.5、Seedance 生成素材后合成 | `references/ai-assets.md` | | HTML 幻灯片 | `references/slides.md` | | 直接可抄的 prompt（给用户，或给子 agent） | `references/prompts.md` | | 30 条样本明细、数据与出处 | `references/research.md` | ## 搭配外部模型（推荐，不强制） 纯代码就能出片。下面几类模型补的是代码做不好的部分： - **GPT Image 2 / 2.5**：角色设定图、写实背景板、纸张 / 笔触纹理、主视觉。代码负责让它们动起来。 - **Seedance 2.x**：真人表演、自然景观、写实 B-roll。代码在上面叠 UI、字幕和数据图。 - **配音**：豆包 TTS（中文，能拿逐字时间戳对字幕）、Fish Audio、ElevenLabs、Gemini TTS、MiniMax。**配乐**：Lyria、MiniMax Music，或直接用 `audio.py` 合成。 具体怎么调用、怎么写素材 prompt、怎么合成，见 `references/ai-assets.md` 和 `references/audio.md`。 ## 交付清单 **清单没全部打勾之前，不要结束回合、不要输出「最终报告」。** 中途汇报进度可以，但汇报完要接着干。（实测：较弱的模型常常在「接下来我会渲染……」这句话之后就停了。） - [ ] STORYBOARD.md 写过，且对照检查表自查过 - [ ] 至少一轮拼图自检，6 项都 ≥ 8，修改记录写进 STORYBOARD.md 末尾 - [ ] `qa.py`：0 处未解释的跳变 / 静止段，响度 −14 LUFS 左右 - [ ] `lint.mjs` 全绿（视频和幻灯片都要跑） - [ ] 画面里的每个数字都有出处 - [ ] 交付 mp4（+ 幻灯片的 PDF），并告诉用户怎么改：改哪个文件、改哪个常量