有逐用户数据表、要批量生成 Wrapped…

当你有一张每用户/账户/年度的统计数据表，需要把它变成可截图分享、同模板不同数字的 9:16 Wrapped 回顾视频（单条或批量）时使用。

适用场景

解决思路

1. 采用“一个模板 × 一张数据表 → 多支个性化视频”的模式：模板只写一次，然后为每一行数据渲染一支独有影片。
2. 硬性要求 1：数据驱动一切。所有标题、数字、姓名、颜色都来自 props，绝不硬编码；无法由数据行填满的场景不要放进 Wrapped。
3. 硬性要求 2：为截图而设计。每个场景必须 2 秒内读完，冻结帧也要好看；为暂停画面而不是播放过程做设计。
4. 使用固定的 Wrapped 场景语法：由每个约 2.5–4 秒的短场景类型组成；每年语法相同，只换数据和调色板。
5. 从以下场景类型中选 5–7 个并按递进顺序编排：Intro/“Your 2026, wrapped”（name, year）；Big-number reveal（一个主数字 + 单位 + 标签）；Top-X list（按 1→5 排名交错进入，数组 {rank,label,value}）；Superlative/persona（计算出的层级/标签）；Comparison（百分位或比例）；Time/heatmap（序列或峰值）；Outro/share card（姓名、handle、CTA、静止）。
6. 按渐强顺序排列：先小背景，最大/最个人化统计作高潮，最后放静止分享卡。
7. 按五拍故事弧编排：Build-up（“{name}, your {year}”）；Escalating reveals（Top-X、类型、时间模式）；The “big number”（主统计最大规模、停留最久）；Personalized superlative（命名“你是谁”，不只是做了什么）；Shareable payoff（静止海报）。
8. 将统计按情感冲击力排序（原始大小、稀有度、讨喜程度），从小到大、从弱到强播放；绝不以主数字开场，否则后面像降级。
9. 最高潮统计保持最大且停留最久；它之前的一切都是铺垫。
10. 前 2 秒建立“这是关于你”的钩子：以用户名字开场，使用每用户 accent，所有文案用第二人称（如 “You listened to 412 artists”）。
11. 避免通用文案；把 “Top genre: Indie” 改写成 “You're an Indie kind of person.”；如果同一帧对两个不同用户读起来一样，就没有价值。
12. 先设计最终分享帧：outro 不是字幕，而是回报：重述头条最高级/主数字、姓名 + @handle、logo、一个短 CTA，完全静止 ≥2 秒，让截图或自动循环干净落位。
13. 以最终分享帧为目标构建整个渐强。
14. 为单条记录定义类型化 schema（如 zod），整支视频是该记录的纯函数；示例字段包括 name, year, minutesListened, topArtists[{rank,label,value}], topGenre, percentile, accent。
15. 在 composition 上注册 defaultProps + schema，使每次渲染只需替换 props。
16. 在 Root 中注册 Composition：id、component、schema、durationInFrames（如 30*22，22s@30fps）、fps、width 1080、height 1920（9:16 竖屏）、defaultProps。
17. 实现大数字计数器：用 useCurrentFrame() 驱动，绝不用 setState/setInterval（会闪烁）；用 spring 缓动，用 toLocaleString() 格式化。
18. 大数字组件中使用 spring({ frame, fps, config:{ damping:200 } })，用 interpolate 将 progress 映射到 0→value，并用 scale 从 0.6→1 弹入。
19. 使用 tabular-nums，防止数字滚动时宽度抖动。
20. 对 Top-X 列表，为每个条目复用一个 spring，并通过 delay 交错进入（rank 1 先出）。
21. 渲染 1080×1920 竖屏 9:16；为 Stories/Reels/TikTok 裁切和 UI 覆盖留安全区。
22. 所有文字和关键数字保持在高度中心 80% 内，避开顶部 12% 和底部 18%。
23. 每帧只表达一个大胆想法，使用超大字号、高对比度 accent，在纯色/渐变背景上；每用户 accent 颜色使分享更个人化。
24. 批量渲染：用 renderMedia 把每一行数据渲染成自己的 MP4，把该行作为 inputProps 传入。
25. 生成 CSV/JSON 任务列表，循环，按记录命名文件（如 out/wrapped-${user.id}.mp4）。
26. 批量脚本：bundle entryPoint，读取 users.json，循环 users；对每行用 wrappedSchema.parse(user) 校验；用 selectComposition 选择 composition；用 renderMedia 指定 codec: h264、inputProps、outputLocation。
27. 数千行时，分发到多台机器/Lambda，并对相同 prop 集去重。
28. 建立构建检查清单：每个可见字符串/数字来自 props；5–7 场景按渐强顺序；最大/最个人化统计为高潮。
29. 检查数字计数：useCurrentFrame + spring、tabular-nums、locale 格式化。
30. 检查 9:16 1080×1920，关键内容在中心 80%，避开顶部 12%/底部 18%。
31. 检查每个场景 <2 秒可读且冻结好看（会被截图）。
32. 检查一个 schema 在渲染前校验每一行；批量脚本按记录命名文件。
33. 交付与验证：使用 packaged helper scripts：用 scripts/contact-sheet.sh sheet.png f-hook.png f-mid.png f-end.png 拼贴静帧，再用 scripts/probe-mp4.sh out.mp4 [WxH] [fps] 校验编码；参见 scripts/README.md。
34. 利用 Remotion 帧确定性：任何精确帧都可无 seek harness 地 headless 渲染；交付物是携带每个人精确数字的 MP4，批量前先用一个代表行验证。
35. 输出契约：Remotion 项目注册 composition（<Composition> + zod schema + defaultProps），所有运动帧驱动（无 timers / Date.now() / Math.random()，计数用 useCurrentFrame + spring）。
36. 输出契约：交付 out/wrapped-*.mp4 每行一个，并保留项目以便任意行重渲染。
37. 输出契约：每用户统计写入 props 并在渲染前由 schema 校验；9:16 1080×1920。
38. 若时长依赖数据，在 calculateMetadata 中计算，不要手工写。
39. 验证循环：先渲染一个代表用户的帧（便宜，不编码），检查布局/数据 bug 一次而不是 N 次。
40. 用 npx remotion still Wrapped out/f-start.png --frame=0 --props='{...one user...}' 渲染起始静帧。
41. 用 npx remotion still Wrapped out/f-mid.png --frame=N --props='{...one user...}' 渲染中间静帧。
42. 用 npx remotion still Wrapped out/f-end.png --frame=L --props='{...one user...}' 渲染结束静帧（L = durationInFrames - 1）。
43. 检查：每个可见字符串/数字来自该行且精确（大数字 reveal 落在真实值，Top-X 排名/标签正确）；关键内容在中心 80%，避开顶部 12%/底部 18%。
44. 代表静帧通过后，才批量渲染所有行：npx tsx render-all.ts。
45. 用 npx remotion compositions 读取 durationInFrames/fps 来选择结束帧和大数字稳定帧。
46. 免费获得 README demo GIF：npx remotion render Wrapped out/demo.gif --codec=gif --props='{...}'。
47. 完成前检查：npx remotion still 在代表行的 frame 0、中间、最后干净渲染 — 无错误、无缺失资产/字体。
48. 完成前检查：大数字 reveal 在稳定帧落在精确 prop 值；Top-X 排名/标签/值匹配该行。
49. 完成前检查：9:16 关键数字/文字在中心 80%，避开顶部 12%/底部 18%；每个检查帧冻结可读。
50. 完成前检查：仅帧驱动 — 无 Date.now()/Math.random()/timers；schema 在批量前校验每一行。
51. 完成前检查：代表 MP4 已编码且可播放；然后批量所有行（每条记录一个文件）；可选为 README 生成 GIF。
52. 参考文件：references/scene-grammar.md（完整 7 场景 storyboard、frame timings、build/crescendo 逻辑、superlative/percentile 文案模式、9:16 safe-area map）。
53. 参考文件：references/remotion-recipes.md（可运行场景组件：staggered top-X list、percentile bar、<Series> 场景排序、transitions、fonts、no-flicker 动画规则）。
54. 参考文件：references/batch-pipeline.md（CSV/JSON → many MP4s：schema validation、render loop、concurrency、Lambda fan-out、file naming）。

适用边界 · 注意事项

• 没有数据表或没有逐记录数据时，不要用此模式；应改用其他技能。
• 交付物需要手工精剪的影片而非数据驱动的模板化视频时，不适用。
• 不能使用 Remotion 或等价的代码化、帧驱动视频渲染栈时，不适用。