应用宣传视频 (Remotion + 真实 iPhone + 真实 UI)
此方法在四个小型 iOS 应用（Unblock、Talljakt、Georama 和 Quiz）上开发，并可针对任何应用重复使用。所有与应用特定的内容都位于 examples/ 中。可复用部分位于 templates/ 中。详细技术、陷阱和可调变量在 references/techniques.md 中。在开始构建之前请先阅读该文档。
语言： 使用用户所使用的语言与用户交流。如果用户用挪威语开始，就用挪威语回答。视频中文本的语言是一个单独的选择（下面的问题 3）。
0. 首先进行简短访谈
一起询问这些问题（使用 AskUserQuestion 或单条消息）。提供默认值，以便用户可以直接回答“默认”：
- 时长： 20–60 秒。默认约 30 秒。
- 格式： 9:16 竖屏 1080×1920。默认 60 fps。也可以是 1:1 或 16:9？
- 屏幕文本的语言。
- 用途： 私人分享、社交媒体（Reels/TikTok，注意安全区域）或 App Store 预览。App Store 预览必须是真实录制，最长 30 秒，且不允许使用虚构的 3D 效果，因此此方法不太适合。
- UI 元素从屏幕中“飞出”的程度： 无（低调：仅真实录制、焦点缩放和 app 自身的转场，参见
examples/kjop）、轻微（一到两个高光时刻）、中等 或 完全（所有元素都飞出）。默认是 轻微到中等；无 适合普通的日常应用（列表、表单、设置）。完全 适合其组件本质上是物理对象的应用（游戏方块）；对于普通应用（列表、表单、卡片），仅让 1–3 个关键元素飞出，其余保留在屏幕上。 - 创意自由度： 是否让代理自行构思创意？
- 音乐： 代码生成（默认，无需许可）还是使用用户自己的曲目？为每个应用提供其独特的音色，以确保两个视频听起来永远不会相同（参见
references/techniques.md#sound）。 - 要展示哪些功能（3–5 个），以及应用的“核心”元素或时刻是什么？
- 结尾： 两个经过验证的选项；根据应用选择，如果不明确则询问用户。 (a) 使用应用自身元素构建的 Logo 组合（Unblock：Logo 由 3D 方块组装而成，黄铜方块最后落下）。 (b) 手机上的主屏幕，上方带有一句标语，图标 + 名称是最后一行（Talljakt：“六个数字。 / 一个目标。 / [图标] Talljakt。”）。
- 手机颜色： 宇宙橙、深蓝或银色。选择与 app 强调色相匹配的颜色。
这些答案主要决定概念、元素飞出屏幕的程度、节奏（bpm）和颜色。
0a. 预检：检查工具链
在开始构建之前，检查已安装的内容并以一个简短列表报告。提供安装缺失组件的选项，并且仅在用户同意后才安装（这些是系统更改）。跳过已存在的任何内容。
| 工具 | 检查命令 | 安装方式 |
|---|---|---|
| Xcode + 命令行工具 | xcodebuild -version, xcode-select -p | App Store (Xcode), 然后 xcode-select --install |
| 包含 iPhone 17 Pro 设备类型的 iOS 模拟器运行时 | xcrun simctl list runtimes, `xcrun simctl list devicetypes | grep "iPhone 17 Pro"` |
| baguette | baguette --version | brew install baguette |
| Blender | ls /Applications/Blender.app | brew install --cask blender |
| Node 22 | node --version | nvm install 22 (或 brew install node@22) |
| ffmpeg | ffmpeg -version | brew install ffmpeg |
| Python 3 + Pillow | python3 -c "import PIL" | python3 -m pip install --user pillow |
| Homebrew (用于上述安装) | brew --version | 来自 brew.sh 的官方安装脚本，由用户运行 |
然后设置 Remotion 项目（references/techniques.md#setup）并转换 iPhone 模型一次（下面的步骤 6）。两者都是项目本地的，无需超出在仓库中工作的额外权限。
0b. 交付文件夹（每台 Mac 一次）
完成的视频会交付到机器上的一个固定文件夹，而不仅仅是项目的 out/ 文件夹。选择存储在每个 Mac 的 ~/.config/app-promo/destination（一行，完整路径）中。
- 在开始时读取该文件。如果存在，无需询问直接使用该文件夹。
- 如果缺失，询问一次（AskUserQuestion）：
~/Movies/App Promos（推荐）、项目的out/文件夹、桌面或自定义路径。创建文件夹并将路径写入~/.config/app-promo/destination。 - 用户可以随时通过询问来更改；更新文件。
1. 工作流程
- 阅读应用。 README、颜色标记（搜索
Color(,hex, 主题结构体）、字体、文案。在视频中，如果应用的文案合适，优先使用它们。 - 查找调试入口点 以展示无需播放的状态：启动参数（
--design-*）、URL scheme（myapp://design-home?state=...）或固定数据（fixtures）。如果没有，在向应用中添加仅用于 DEBUG 的钩子之前先询问用户。 - 在专用的 iPhone 17 Pro 模拟器上构建并安装。 截图必须是 1206×2622，否则无法匹配手机模型的屏幕。参见
references/techniques.md#simulator。 3b. 对于真实屏幕录制： 阅读 references/recording.md。首先准备好场景和点击点，进行短时间录制，录制期间不要进行 UI 检查、构建或视频分析，并在 Remotion 之前检查原始时长。整个流程的单一连续录制（如examples/quiz中所示）可以保持每个数字、进度条和历史记录的一致性。 - 截取每个状态的截图。 对于静态/裁切序列，使用真实点击播放序列，并在每次点击后截图（参见
references/consistency.md）。对于视频，在单独的预演中进行检查，切勿在最终录制期间进行。锁定状态栏（9:41、100%、放电状态或绿色充电指示器）。使用baguette describe-ui获取元素框架。 - 裁切 UI 元素 使用特定于应用的
tools/prep_<app>.py，该脚本使用templates/tools/prep_helpers.py：精灵图、空白背景和矩形坐标的 JSON。在每套视觉元素上进行视觉检查（在洋红色背景上合成）。 - 转换 iPhone 模型 使用 baguette（USDZ 格式）和 Blender（
templates/tools/convert_model.py）转换为 GLB 格式。 - 设置 Remotion 项目，或复用现有项目：复制
templates/src/three/*、Title.tsx、brand.ts、remotion.config.ts、tools/sheet.sh和tools/prep_helpers.py。 - 编写节拍表（
timeline.json），以帧为单位，基于 bpm 网格（120 bpm 在 60 fps 下 = 每拍 30 帧）。图像和声音都读取此文件。 - 将场景构建为连续“一镜到底”： 相机保持静止，手机支架移动。屏幕变化通过转场隐藏：旋转、应用自身的导航、从元素开始的变焦或擦除、推进、翻转、甩镜头、匹配剪辑或快进。变化使用，每个视频最多两次旋转。参见
references/techniques.md#transitions。 - 通过关键帧的联系表进行迭代（
tools/sheet.sh f1 f2 …）。查看它们。渲染完整视频（快速：约 1–2 分钟用于 30 秒的视频）。 - 检查点： 在构建其余部分之前，向用户展示前约 12 秒。
- 生成配乐（
tools/<app>_audio.mjs，从示例复制）使用相同的节拍表。渲染、测量响度（ffmpeg -af ebur128，目标为 −14 到 −16 LUFS）并为用户打开文件。
12b. 一致性检查（交付前必需）。 手机屏幕上的内容与屏幕外高亮显示的内容不匹配看起来像是 AI 伪影。仔细检查 references/consistency.md，并在每个转场、屏幕变化和元素飞出周围 ±2 帧渲染联系表。
13. 分享文本： 编写一段简短的文本，用于粘贴到视频分享的任何地方（格式如下）。将其复制到剪贴板（pbcopy），并在回复中将其显示在代码块中。不要将其保存为文件。
14. 交付： 将最新批准的渲染复制到交付文件夹（0b），命名为 <App> promo.mp4。覆盖同一应用的先前交付；版本历史（-v2、-v3 …）保留在 out/ 中。在回复中提供已交付文件的路径。
分享文本格式
文本通常在 Slack 中发布，因此使用 Slack 格式（mrkdwn）：标题用 单个星号 加粗，项目符号用“• ”（粘贴的“- ”不会变成列表）。使用视频的语言编写。
*<App> – <标语，2–4 个短句/单词，最好是视频中的那个。>*
<一句话：应用是什么，面向谁或用做什么。>
• <要点：核心操作，具体且主动>
• <要点：应用提供的选择（主题、模式、区域、节奏...）>
• <要点：...>
• <要点：奖励/分享/独特之处>
规则：4–5 个要点，要点末尾不加句号，直接面向读者，使用具体动词，无营销套话。从应用的实际使用方式开始：前 2–3 个要点具体解释机制，然后是选项和附加功能。然后描述应用能让用户做什么，而不仅仅是视频显示了什么：按要点对选项进行分组（“练习国家、首都或旗帜”），以便读者看到范围。使用应用自己的名称，并在代码中检查每种模式的实际作用（README 可能过时）。参见 examples/*/share.txt。
2. 一个行之有效的概念模板
一个核心、一个贯穿始终的动作、应用自身的文案：
| 部分 | Unblock | 通用 |
|---|---|---|
| 钩子 0–2.5 秒 | 方块降落到漂浮在黑暗中的面板上，没有手机。“卡住了。” | 应用解决的问题，使用应用自身的元素展示，不出现手机 |
| 揭示 | 手机在元素周围自行构建，同时相机向后拉 | 同一元素原来在应用内部 |
| 核心循环 | 在节拍上执行 4 步移动，屏幕外显示计数器 | 在 3–4 个节拍内完成主要动作 |
| 高光时刻 | 核心元素飞出屏幕并飞向相机，闪现黄铜色光芒 | 一个大的时刻（飞出屏幕效果，或应用自身最佳动画的慢动作） |
| 回报 | 结果屏幕，3D 星星弹出 | 奖励或结果 |
| 功能（之间使用多种转场） | 关卡选择器、每日卡片、分数 | 2–3 个功能，每个功能有一个高亮元素 |
| 结尾 | 由 3D 方块构建的 Logo，标语 | 应用元素的 Logo 组合，或带有标语 + 名称的主屏幕 |
如果应用有一个真正出色的自有动画（Quiz：“显示答案”按钮撕裂成错误/正确），将其作为核心：近距离变焦、使用速度曲线放慢、赋予其独特音效、不加字幕。
2b. 优秀应用宣传视频中的视觉手法
好的参考使用屏幕和内容，而不仅仅是布局。每个视频计划至少使用 3–4 个：
- 裁剪屏幕： 足够靠近，只显示一个部分（计时器、按钮行、方程式）。手机被画面边缘切割。使用
focus姿态。 - 屏幕旁或屏幕前的内容卡片： 来自应用的真实卡片或海报（分享卡、结果卡、建议）作为扁平、略微旋转的平面放置在手机后面或前面。
- 同时显示多个内容卡片： 扇形展开 3–5 个变体（页面、解决方案、海报）。
- 多个设备： 当故事是关于分享或“对所有人都一样”时，并排放置两部手机，上方带有名称标签。如果应用支持，放置手机 + Watch/iPad（baguette 有 iPad 和 Watch 模型）。
- 应用的元素作为装饰： 真实方块、按钮、芯片或图标在背景中漂浮（模糊 = 远距离），或放大为手机上方的大号排版。一个主题化纹理（脉冲线、蜡笔笔触、方格纸）。
- 应用生成的内容作为物体： 打印件、海报、卡片，理想情况下不出现手机。
- 对话气泡或想法气泡 用于发生在手机外部的事情（Quiz：说出答案从卡片旁弹出，然后落到正确/错误按钮上以“按下”它）。
2c. 文本和框架
- 顶部居中大标题承载信息： 每行 2–4 个字，最多两行，第二行或关键词使用强调色。
- 底部小标题，谨慎使用，仅在需要澄清标题时使用（在 30 秒视频中使用 2–3 次）。它们必须可读：至少约 50 像素，置于带有浅色背景和阴影的芯片中（而非松散文本），放置位置低，使其永远不会穿过手机框架，可见时间至少 2 秒。
- 只声称应用实际能做的事情。 在撰写之前检查某个功能的真实情况。
- 支持全屏文本卡片： 一个彩色表面（应用的主色），带有居中的大号两行标题，从最后一个聚焦的元素擦入，并通过滑向下一场景擦出。在结尾之前使用一个作为喘息或过渡，最好是一个挑战观众的问题（“你能及时找到它吗？”）。不要从激烈的动作直接跳到结束屏幕。参见
examples/talljakt和examples/quiz中的QuestionCard。 - 不要在角落固定显示应用图标和名称。 仅在结尾处显示名称，作为 Logo 或标语的最后一行。
- 保持画面简洁：每个场景一个想法。 如果一个功能没有什么可展示的（一个设置），将其整合为另一个场景中的字幕或简短焦点，而不是为其单独设立场景。避免同时显示标题 + 放大手机 + 一行元素 + 字幕。
- 节奏：无停顿时间。 每个场景在开始后约 1 秒内都有一个事件，并且没有标题会在静态屏幕上停留超过约 1.5 秒。重复的步骤（例如测验中的问题 2–13）可以快进。
- 将选择展示为动作，而非文本。 如果应用有模式或设置，显示默认被选中（卡片略微抬起）、点击替代选项（它抬起，屏幕改变状态），然后点击开始进入该模式。
- 否则可能不清晰的交互（打开菜单、选择选项）会获得一个点击指示器（一个按下并向外扩散涟漪的圆圈），放置在应用实际响应的内容上。
3. 原则
- 真实 UI 优于复刻 UI。 使用截图、录制和裁切元素，而不是应用 HTML 副本。必须更改的文本（计数器、分数）使用应用的字体通过 PIL 绘制，并与原始内容进行验证。
- 适量使用“飞出屏幕”效果。 它起调味作用。默认是一个核心时刻和 1–2 个飞出的功能。
- 变焦和聚焦是强调的主要工具。 将镜头移动到屏幕的特定部分...