Flutter demo reel
Build a short looping promo for a Flutter app as its own macOS Flutter app in
<flutter app>/demo, render it offline frame by frame, and encode it. The reel
uses the app's real screens, art, fonts and content, a 3D layer on
flutter_scene (Flutter GPU on Metal), a 2D particle and title kit, and cuts on
the music.
Paths below are relative to this skill's folder (the folder containing this
SKILL.md). In Claude Code that folder is ${CLAUDE_SKILL_DIR}.
Ground rules
- Never modify the app. Copy what you need (art, fonts, screenshots,
content data, theme colours) into
demo/. The scaffold only addsdemo/**to the parent package's analyzer excludes. - Every frame is a pure function of
t. No state between frames, noRandom(), no clocks, no simulation: closed-form motion, seeded randomness. This is what makes scrubbing, chunked export, motion blur and a seamless loop work. Read references/kit.md before writing shots. - Follow the project's voice rules (AGENTS.md, CLAUDE.md or similar): words the app never uses, how the product names itself, tone.
- Agree before building. Interview the user, then write a script they approve.
- macOS only. Needs Flutter with macOS desktop, ffmpeg (
brew install ffmpeg), and Python 3 with Pillow (contact sheets) and numpy (audio analysis).
Workflow
1. Interview
Ask before you start, offering a default for each so the user can answer fast:
- Length and loop (default 30 s, seamless loop), formats (landscape 1920x1080 and portrait 1080x1920, portrait designed for Reels, TikTok and Shorts), 60 fps.
- Soundtrack: a file (with lyrics?) or none, and who owns the rights.
- The message: the 3–5 things to show, the call to action (URL, store badges), claims to make (free? ratings? counts?).
- Look and tone: how over the top, the app's brand, any references.
- Real screens: which ones, and may you run the app to capture them (test account, seeded data)? Invented atmospheric shots too?
- On-screen text: key words only (default) or full captions, spelling of the product name, words to avoid.
- Anything special: easter eggs, characters, things never to show.
2. Study the app
Read the app's theme (colours, fonts), assets (logos, characters, icons), content (real names, numbers, data to show) and its main screens. Note what makes it distinctive. Plan the screenshots and capture them, or ask the user for them (see "Real screenshots" in references/craft.md).
3. Analyse the soundtrack
python3 scripts/analyze_audio.py <track>
Turn its tempo, beat phase, sections and vocal lines into named cues, as in references/audio-sync.md. Without a soundtrack, still pick a tempo and cut on its grid.
4. Write the script
Make a timed table with, for each shot: the music or lyric, the landscape picture, the portrait picture and the on-screen text (template in references/craft.md). Mark the hook, the drop, the end card and the loop seam. Get the user's approval, and iterate until they say go.
5. Scaffold
zsh scripts/scaffold.sh <flutter app dir>
Run it with the full path to this skill's scripts/ folder; it works from
any directory. It:
- creates
<app>/demowithflutter create --platforms macos; - adds flutter_scene, vector_math and audioplayers, and runs
flutter_scene:init; - enables Flutter GPU (
FLTEnableFlutterGPU) and turns off the app sandbox (the exporter runs ffmpeg); - copies the starter kit from
assets/template/, createsart/,art/screens/,audio/andfonts/, and ignoresout/; - excludes
demo/**from the parent package's analyzer.
It works inside pub workspaces (the demo stays a standalone package), and it refuses to overwrite an existing folder.
Then configure:
lib/core/timeline.dart:kDuration,kBpm,kBeatPhaseand theCues.lib/core/format.dart:Palettefrom the app's theme, andFonts(copy the font files intodemo/fonts/and declare them inpubspec.yaml).- Assets:
art/(list subfolders inpubspec.yaml) andaudio/track.wav(48 kHz PCM).
Build once and render the example's stills to prove the setup works:
cd <app>/demo && flutter build macos --profile && tool/run.sh stills "0.3,2.3,9" both
6. Build the reel
Replace lib/shots/example.dart with one section per part of the script, list
them in Director.sections, and set the camera hits in Director._hits. Work
section by section:
- Write the section (3D frame, and 2D layers under and over it) using the kit (references/kit.md) and flutter_scene (references/flutter-scene.md).
- Run
flutter build macos --profile, then render stills at the section's key moments in both formats:tool/run.sh stills "t1,t2,..." both. - Make one contact sheet per format and inspect it, plus single stills up
close where detail matters:
python3 tool/sheet.py out/l.png 4 480 out/stills/landscape_*.png. If you cannot view images, tell the user which stills to check and what to look for. Fix, and repeat.
Run the review checklist in references/craft.md over the
whole reel before exporting. The user can watch it with the music in the
preview app (open build/macos/Build/Products/Profile/*.app); stills cannot
show timing.
7. Export
tool/export.sh draft both # 1x, no motion blur: a quick full check
tool/export.sh final both # 2x supersampled, 4-sample motion blur
A final export takes roughly 10–15 minutes per format for 30 s. Run it in the
background if your environment allows that, and do not poll it. Afterwards,
verify the files with ffprobe: the frame count is kDuration * kFps, the
duration is right, and there is an audio stream. Pull a few frames from the
MP4s, including the last frame and frame 0 (the loop seam).
8. Deliver and iterate
Give the user the paths (demo/out/final/<format>.mp4 for upload,
<format>_master.mov ProRes for editing), the file sizes, and what to check.
Expect notes. Typical ones, with fixes, are in
references/craft.md: text held too briefly, text
covered, unwanted subtitles, seams in outlines, hard light rays, a set of items
that look the same, portrait wording. Fix all notes in a round before
re-rendering.
Files
- references/kit.md: the starter kit's architecture and APIs.
- references/flutter-scene.md: flutter_scene setup, look and offline gotchas.
- references/audio-sync.md: tempo, phase, lyrics and cues from a track.
- references/craft.md: script template, text rules, effect recipes, screenshots, the review checklist.
scripts/scaffold.sh: creates the demo app.scripts/analyze_audio.py: tempo, beat phase, loudness per bar, onsets.assets/template/: the starter kit that the scaffold copies.