---

name: swift-package-demo description: Use when creating demo GIFs for Swift package READMEs, recording iOS simulator videos, or setting up demo apps for SwiftUI libraries allowed-tools: Read, Grep, Glob, AskUserQuestion

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

Copydigraph 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

Demo App Setup

Create demo/DemoApp/ with Xcode project that imports your package locally:

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

Copy# 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:

CopyQuestion: "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)

Copyffmpeg -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)

Copyffmpeg -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 keeps 55% height starting at 12% from top.

README Integration

Copy<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    between images, width 240-280px each.

.gitignore

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

Common Mistakes

Target Sizes