Communitygithub.com

flutter-demo-reel

将 Flutter 应用转换为循环播放的推广或演示视频(16:9 和 9:16,60 fps),用于社交媒体。

flutter-demo-reel 是什么?

该技能将 Flutter 应用构建为一个独立的 macOS Flutter 项目(位于 <app>/demo),通过逐帧离线渲染并编码,生成简短的循环推广视频。视频使用应用的真实界面、素材、字体和内容,通过 flutter_scene(基于 Metal 的 Flutter GPU)添加 3D 层,配备 2D 粒子与标题工具包,并能与配乐同步剪辑。它支持 macOS 平台,需要安装 Flutter(含 macOS 桌面支持)、ffmpeg 以及 Python 3 与相关库(Pillow、numpy)。工作流程包括:与用户沟通确定长度、格式、配乐与信息重点;研究应用主题与素材;分析配乐生成节拍与提示点;编写分镜脚本;搭建脚手架项目;逐段构建并预览;最后导出为 H.264 和 ProRes 格式。该技能的核心原则是每一帧都是时间 t 的纯函数,确保无缝循环和可预测渲染。适合用于制作应用宣传片、演示视频、预告片、社交视频或动画展示。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vlidholt/flutter-skills/tree/HEAD/skills/flutter-demo-reel

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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. 沟通

在开始前先提问,为每项提供一个默认值以便用户快速回答:

  1. 时长与循环(默认 30 秒,无缝循环),格式(横屏 1920x1080 和竖屏 1080x1920,竖屏设计用于 Reels、TikTok 和 Shorts),60 fps。
  2. 配乐:一个文件(带歌词?)或无,以及谁拥有版权。
  3. 信息:要展示的 3-5 个要点,行动号召(URL、应用商店徽章),要声明的信息(免费?评分?数量?)。
  4. 视觉与语气:夸张程度、应用的品牌、任何参考。
  5. 真实界面:哪些界面,以及是否可以运行应用来截取它们(测试账号、种子数据)?是否也需要虚构的氛围镜头?
  6. 屏幕文字:仅关键词(默认)或完整字幕,产品名称的拼写,避免使用的词汇。
  7. 特殊要求:彩蛋、角色、绝不能展示的内容。

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 中设置摄影机命中点。按节逐步构建:

  1. 使用工具包(references/kit.md)和 flutter_scene(references/flutter-scene.md)编写该节(3D 帧,以及其下方和上方的 2D 层)。
  2. 运行 flutter build macos --profile,然后以两种格式渲染该节关键时刻的静态图像:tool/run.sh stills "t1,t2,..." both。
  3. 为每种格式制作一个联系人表并检查,对于细节重要的地方还要单独查看静态图像: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/:脚手架复制的启动工具包。

相关技能