Communitygithub.com

flutter-demo-reel

Turns a Flutter app into a looping promo or demo reel video for social media (16:9 and 9:16, 60 fps). Builds it as a separate macOS Flutter app in <app>/demo with 3D on flutter_scene (Flutter GPU), a 2D particle and title kit, cuts synced to a soundtrack, and offline export to H.264 and ProRes with ffmpeg. Use when the user asks for a promo, demo reel, trailer, teaser, launch video, social video or animated showcase of a Flutter app.

What is flutter-demo-reel?

flutter-demo-reel is a Claude Code agent skill that turns a Flutter app into a looping promo or demo reel video for social media (16:9 and 9:16, 60 fps). Builds it as a separate macOS Flutter app in <app>/demo with 3D on flutter_scene (Flutter GPU), a 2D particle and title kit, cuts synced to a soundtrack, and offline export to H.264 and ProRes with ffmpeg. Use when the user asks for a promo, demo reel, trailer, teaser, launch video, social video or animated showcase of a Flutter app.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vlidholt/flutter-skills/tree/HEAD/skills/flutter-demo-reel

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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 adds demo/** to the parent package's analyzer excludes.
  • Every frame is a pure function of t. No state between frames, no Random(), 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:

  1. Length and loop (default 30 s, seamless loop), formats (landscape 1920x1080 and portrait 1080x1920, portrait designed for Reels, TikTok and Shorts), 60 fps.
  2. Soundtrack: a file (with lyrics?) or none, and who owns the rights.
  3. The message: the 3–5 things to show, the call to action (URL, store badges), claims to make (free? ratings? counts?).
  4. Look and tone: how over the top, the app's brand, any references.
  5. Real screens: which ones, and may you run the app to capture them (test account, seeded data)? Invented atmospheric shots too?
  6. On-screen text: key words only (default) or full captions, spelling of the product name, words to avoid.
  7. 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>/demo with flutter 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/, creates art/, art/screens/, audio/ and fonts/, and ignores out/;
  • 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, kBeatPhase and the Cues.
  • lib/core/format.dart: Palette from the app's theme, and Fonts (copy the font files into demo/fonts/ and declare them in pubspec.yaml).
  • Assets: art/ (list subfolders in pubspec.yaml) and audio/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:

  1. 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).
  2. Run flutter build macos --profile, then render stills at the section's key moments in both formats: tool/run.sh stills "t1,t2,..." both.
  3. 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.

Related Skills