Flutter 演示视频
为 Flutter 应用构建一个简短的循环推广视频,作为独立的 macOS Flutter 应用存放在 <flutter app>/demo 中,逐帧离线渲染并编码。该视频使用应用的真实界面、素材、字体和内容,通过 flutter_scene(基于 Metal 的 Flutter GPU)提供 3D 层,配备 2D 粒子与标题工具包,并能与音乐同步剪辑。
以下路径均相对于此技能的文件夹(即包含本 SKILL.md 的文件夹)。在 Claude Code 中,该文件夹为 ${CLAUDE_SKILL_DIR}。
基本规则
- 绝不修改原应用。 将所需内容(素材、字体、截图、数据、主题颜色)复制到
demo/中。脚手架仅向父包的 analyzer 排除列表添加demo/**。 - 每一帧都是
t的纯函数。 帧之间无状态,无Random(),无时钟,无模拟:仅使用封闭形式的运动与确定性随机。这是 scrubbing、分块导出、运动模糊和无缝循环得以实现的基础。在编写镜头前请阅读 references/kit.md。 - 遵循项目的语气规则(AGENTS.md、CLAUDE.md 等):应用从不使用的词汇、产品如何自称、语调。
- 先确认再构建。 与用户沟通,然后编写一份他们认可的分镜脚本。
- 仅限 macOS。 需要安装 Flutter(含 macOS 桌面支持)、ffmpeg(
brew install ffmpeg)以及 Python 3 与 Pillow(联系人表)和 numpy(音频分析)。
工作流程
1. 沟通
在开始前先提问,为每项提供一个默认值以便用户快速回答:
- 时长与循环(默认 30 秒,无缝循环),格式(横屏 1920x1080 和竖屏 1080x1920,竖屏设计用于 Reels、TikTok 和 Shorts),60 fps。
- 配乐:一个文件(带歌词?)或无,以及谁拥有版权。
- 信息:要展示的 3-5 个要点,行动号召(URL、应用商店徽章),要声明的信息(免费?评分?数量?)。
- 视觉与语气:夸张程度、应用的品牌、任何参考。
- 真实界面:哪些界面,以及是否可以运行应用来截取它们(测试账号、种子数据)?是否也需要虚构的氛围镜头?
- 屏幕文字:仅关键词(默认)或完整字幕,产品名称的拼写,避免使用的词汇。
- 特殊要求:彩蛋、角色、绝不能展示的内容。
2. 研究应用
阅读应用的主题(颜色、字体)、素材(标志、角色、图标)、内容(真实名称、数字、要展示的数据)及其主要界面。记录其独特之处。规划截图并截取它们,或向用户索要(参见 references/craft.md 中的“真实截图”)。
3. 分析配乐
python3 scripts/analyze_audio.py <track>
将其节奏、节拍相位、段落和人声线路转换为命名提示点,如 references/audio-sync.md 中所示。如果没有配乐,仍需选择一个节奏并按其网格进行剪辑。
4. 编写分镜脚本
制作一个带时间戳的表格,为每个镜头包含:音乐或歌词、横屏图片、竖屏图片以及屏幕文字(模板见 references/craft.md)。标记出钩子、高潮、结尾卡片和循环接缝。获得用户的批准,并迭代直到他们说可以。
5. 搭建脚手架
zsh scripts/scaffold.sh <flutter app dir>
使用此技能 scripts/ 文件夹的完整路径运行;它可以从任何目录工作。它会:
- 在
<app>/demo下用flutter create --platforms macos创建项目; - 添加 flutter_scene、vector_math 和 audioplayers,并运行
flutter_scene:init; - 启用 Flutter GPU(
FLTEnableFlutterGPU)并关闭应用沙盒(导出器运行 ffmpeg); - 从
assets/template/复制启动工具包,创建art/、art/screens/、audio/和fonts/,并忽略out/; - 将
demo/**从父包的 analyzer 中排除。
它在 pub workspaces 内也能工作(demo 保持为独立包),并且拒绝覆盖现有文件夹。
然后配置:
lib/core/timeline.dart:kDuration、kBpm、kBeatPhase以及Cue列表。lib/core/format.dart:从应用主题获取的Palette,以及Fonts(将字体文件复制到demo/fonts/并在pubspec.yaml中声明)。- 资源:
art/(在pubspec.yaml中列出子文件夹)和audio/track.wav(48 kHz PCM)。
构建一次并渲染示例的静态图像以证明设置有效:
cd <app>/demo && flutter build macos --profile && tool/run.sh stills "0.3,2.3,9" both
6. 构建视频
将 lib/shots/example.dart 替换为每个脚本部分的一个节,在 Director.sections 中列出它们,并在 Director._hits 中设置摄影机命中点。按节逐步构建:
- 使用工具包(references/kit.md)和 flutter_scene(references/flutter-scene.md)编写该节(3D 帧,以及其下方和上方的 2D 层)。
- 运行
flutter build macos --profile,然后以两种格式渲染该节关键时刻的静态图像:tool/run.sh stills "t1,t2,..." both。 - 为每种格式制作一个联系人表并检查,对于细节重要的地方还要单独查看静态图像:
python3 tool/sheet.py out/l.png 4 480 out/stills/landscape_*.png。如果无法查看图像,告诉用户应检查哪些静态图像以及关注什么。修复并重复。
在导出前,对整个视频执行 references/craft.md 中的检查清单。用户可以在预览应用中观看包含音乐的完整视频(open build/macos/Build/Products/Profile/*.app);静态图像无法展示时间控制。
7. 导出
tool/export.sh draft both # 1x,无运动模糊:快速全面检查
tool/export.sh final both # 2x 超采样,4 样本运动模糊
最终导出对于 30 秒视频,每种格式大约需要 10-15 分钟。在后台运行(如果你的环境允许),并且不要轮询。完成后,使用 ffprobe 验证文件:帧数应为 kDuration * kFps,时长正确,且包含音频流。从 MP4 中抽取几帧,包括最后一帧和第 0 帧(循环接缝)。
8. 交付与迭代
向用户提供路径(demo/out/final/<format>.mp4 用于上传,<format>_master.mov ProRes 用于编辑)、文件大小以及需要检查的内容。预计会有修改意见。常见的修改意见及其修复方法见 references/craft.md:文字停留时间过短、文字被遮挡、多余字幕、轮廓接缝、生硬的光线、看起来相同的物品集合、竖屏措辞。在重新渲染前,一次性修复所有意见。
文件
- references/kit.md:启动工具包的架构和 API。
- references/flutter-scene.md:flutter_scene 的设置、外观和离线注意事项。
- references/audio-sync.md:从音轨获取的节奏、相位、歌词和提示点。
- references/craft.md:分镜脚本模板、文字规则、特效配方、截图、检查清单。
scripts/scaffold.sh:创建演示应用。scripts/analyze_audio.py:节奏、节拍相位、每小节响度、起始点。assets/template/:脚手架复制的启动工具包。