Swift Package Demo Recording

Overview

Record and optimize demo GIFs for Swift package READMEs. Swift packages need a separate demo app since SwiftUI previews only run in Xcode Canvas, not the iOS Simulator.

When to Use

• Adding demo GIFs to a Swift package README
• Recording iOS Simulator for documentation
• User asks to "record a demo" or "add GIFs to README"

Critical Understanding

digraph demo_flow {
    "SwiftUI Preview" [shape=box];
    "iOS Simulator" [shape=box];
    "Xcode Canvas only" [shape=box, style=filled, fillcolor=lightyellow];
    "Recordable with xcrun" [shape=box, style=filled, fillcolor=lightgreen];

    "SwiftUI Preview" -> "Xcode Canvas only" [label="runs in"];
    "Demo App" -> "iOS Simulator" [label="runs in"];
    "iOS Simulator" -> "Recordable with xcrun";
}

SwiftUI #Preview macros CANNOT be recorded. You must create a demo app.

Quick Reference

mkdir -p demo

xcrun simctl boot "iPhone SE (3rd generation)"

open -a Simulator

xcrun simctl io booted recordVideo --codec=h264 demo/raw.mov

Ctrl+C

gifsicle -O3 --lossy=80 demo/out.gif -o demo/out.gif

Demo App Setup

Create

demo/DemoApp/

1. In Xcode: File → New → Project → iOS App
2. Save in

   demo/DemoApp/

3. File → Add Package Dependencies → Add Local → select package root
4. Import and use your library in the app

Critical: Use local package reference, not remote URL, to test current development code.

Recording Commands

# Boot simulator (smaller = smaller GIF)
xcrun simctl boot "iPhone SE (3rd generation)"
open -a Simulator

# Run demo app in Xcode (Cmd+R), then record
xcrun simctl io booted recordVideo --codec=h264 demo/raw.mov
# Ctrl+C to stop

GIF Conversion

REQUIRED: Before converting .mov files to GIF, you MUST ask the user using AskUserQuestion:

Question: "How should the GIF be sized?"
Options:
- Full size (keep entire screen including status bar)
- Cropped (remove status bar and bottom navigation)

Do NOT assume cropping. Do NOT convert without asking first.

Full Size (default)

ffmpeg -i demo/raw.mov -filter_complex \
  "[0:v] fps=12,scale=300:-1:flags=lanczos,split [a][b]; \
   [a] palettegen=max_colors=128:stats_mode=diff [p]; \
   [b][p] paletteuse=dither=floyd_steinberg:diff_mode=rectangle" \
  -y demo/output.gif

gifsicle -O3 --lossy=80 demo/output.gif -o demo/output.gif

Cropped (removes status bar and bottom nav)

ffmpeg -i demo/raw.mov -filter_complex \
  "[0:v] crop=in_w:in_h*0.55:0:in_h*0.12,fps=12,scale=300:-1:flags=lanczos,split [a][b]; \
   [a] palettegen=max_colors=128:stats_mode=diff [p]; \
   [b][p] paletteuse=dither=floyd_steinberg:diff_mode=rectangle" \
  -y demo/output.gif

gifsicle -O3 --lossy=80 demo/output.gif -o demo/output.gif

Crop parameters:

crop=in_w:in_h*0.55:0:in_h*0.12

README Integration

<p align="center">
  <img src="demo/demo1.gif" width="280" alt="Demo 1">&nbsp;&nbsp;<img src="demo/demo2.gif" width="280" alt="Demo 2">
</p>

Side-by-side: Use

  

.gitignore

# Demo - ignore everything except GIFs
demo/*
!demo/*.gif

Common Mistakes

xcrun simctl boot "iPhone SE (3rd generation)"

Target Sizes