app-demo-agent

What this skill does

# App Demo Producer

Turn raw screen recordings into polished app demo videos with AI-generated voiceover, device frames, and background music.

**This is an orchestrator skill** that combines:
- Screen recording analysis (FFmpeg frame extraction + Claude vision)
- Voiceover script generation (Claude)
- Device framing (device-framer)
- Voice synthesis (Gemini TTS / OpenAI TTS / ElevenLabs)
- Background music (Lyria / Suno / Udio)
- Final assembly (FFmpeg via media-utils)

## Workflow

### Step 1: Gather Requirements (REQUIRED)

⚠️ **DO NOT skip this step. DO NOT start processing until you have ALL answers.**

**Use interactive questioning** — ask ONE question at a time, wait for the response, then ask the next.

#### Question Flow

⚠️ **Use the `AskUserQuestion` tool for each question below.**

**Q1: Screen Recording**
> "I'll turn that into a polished demo! First — **where's the screen recording?**
>
> *(provide the file path, e.g., ~/Desktop/recording.mp4)*"

*Wait for response. Verify the file exists.*

**Q2: What does the app do?**
> "Give me a quick overview of what this app does and what the recording shows.
>
> *(e.g., 'It's a task management app. The recording shows creating a task, setting a due date, and marking it complete.')*"

*Wait for response. This context dramatically improves the voiceover script.*

**Q3: Device Frame**
> "Should I wrap it in a device frame?
>
> - **Yes** — iPhone 16 Pro (default)
> - **Yes, specific device** — *(I'll show you options)*
> - **No** — Keep as-is"

*Wait for response. If they want a specific device, run `--list-devices` and let them pick.*

**Q3b: Device Color** *(if device frame selected)*
> "What color for the [device name]?
>
> *(list the available colors for the selected device)*"

*Wait for response. Show the actual color options from the device registry.*

**Q3c: Background Color** *(if device frame selected)*
> "What background color for the video?
>
> - **Dark** (`#0a0a0a`) — cinematic, great for social media
> - **White** (`#ffffff`) — clean, good for presentations/websites
> - **Transparent** — for compositing *(note: output will be WebM, not MP4)*
> - **Custom** — specify a hex color"

*Wait for response. If transparent, set output format to WebM with alpha. If custom, validate the hex color.*

**Q4: Voiceover**
> "How should we handle the voiceover?
>
> - **Generate** — I'll analyze the recording and write a script that narrates what's on screen
> - **You provide** — Give me the script text
> - **None** — No voiceover"

*Wait for response.*

**Q5: Voice Style** *(if voiceover enabled)*
> "What kind of voice?
>
> **Tone:**
> - Professional / polished
> - Friendly / conversational
> - Energetic / excited
> - Calm / reassuring
> - Or describe your own tone
>
> **Gender preference:**
> - Male
> - Female
> - No preference"

*Wait for response.*

**Q6: Voice Selection** *(if voiceover enabled)*

Based on the user's tone and gender preference, recommend a specific voice and let them confirm or pick another:

> "Based on your preferences, I'd recommend **[voice name]** ([provider]). Here are some options:
>
> | Voice | Provider | Tone |
> |-------|----------|------|
> | Kore | Gemini | Friendly, clear, female |
> | Charon | Gemini | Professional, authoritative, male |
> | Puck | Gemini | Upbeat, energetic, male |
> | Aoede | Gemini | Breezy, warm, female |
> | nova | OpenAI | Friendly, natural, female |
> | onyx | OpenAI | Deep, professional, male |
>
> Want to go with **[recommendation]**, or pick a different one?"

*Wait for response.*

**Q7: Background Music**
> "Want background music? If so, what vibe?
>
> - **Modern / minimal** — clean, tech-forward
> - **Upbeat / positive** — energetic, fun
> - **Corporate / professional** — polished, confident
> - **Ambient / calm** — soft, relaxed
> - **Custom** — describe the vibe you want
> - **No music** — voiceover only (or silent)"

*Wait for response.*

**Q8: Output**
> "Where should I save the final video?
>
> *(default: same directory as the input, with `_demo` suffix)*"

*Wait for response.*

#### Quick Reference

| Question | Determines |
|----------|------------|
| Screen Recording | Input file |
| App Overview | Context for voiceover script |
| Device Frame | Whether to use device-framer and which device |
| Device Color | Color variant for the selected device |
| Background Color | Background behind the device frame |
| Voiceover | Generate script vs user-provided vs none |
| Voice Style | Tone and gender preference |
| Voice Selection | Specific TTS voice and provider |
| Background Music | Whether to generate music and what style |
| Output | Where to save final video |

---

### Step 2: Analyze the Screen Recording

Extract keyframes from the recording. **Use scene detection** to capture frames at actual screen transitions rather than fixed intervals — this gives you frames at the moments that matter.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/app-demo-agent/scripts/extract_frames.py \
  INPUT_VIDEO \
  -o ~/demo_project/frames/ \
  --scene-detect \
  --timestamps
```

If scene detection doesn't find enough transitions (e.g., scrolling content), fall back to fixed intervals:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/app-demo-agent/scripts/extract_frames.py \
  INPUT_VIDEO \
  -o ~/demo_project/frames/ \
  --interval 2 \
  --max-frames 20 \
  --timestamps
```

**Options:**
| Option | Default | Description |
|--------|---------|-------------|
| `--scene-detect` | off | Detect actual screen transitions instead of fixed intervals |
| `--scene-threshold` | `0.3` | Scene sensitivity 0.0-1.0, lower = more sensitive |
| `--interval` | `2` | Seconds between frame captures (fixed interval mode) |
| `--max-frames` | `20` | Maximum number of frames to extract |
| `-o, --output` | `./frames/` | Output directory for frames |
| `--timestamps` | off | Also output a `timestamps.json` mapping |

This creates numbered PNG screenshots: `frame_001.png`, `frame_002.png`, etc. The `timestamps.json` maps each frame to its exact timestamp in the video.

**Now read each frame image** using the Read tool to understand the screen flow. Build a mental timeline:

```
0s  - App opens, home screen visible
2s  - User taps "New Task" button
4s  - Task creation form appears
6s  - User types task name
8s  - User sets due date
10s - User taps "Save"
12s - Task appears in list with checkmark
```

Use the user's app description (Q2) combined with what you see in the frames to understand the full flow.

---

### Step 3: Write the Voiceover Script

⚠️ **This is the most important step.** The voiceover must match what's happening on screen at every moment. A generic script that doesn't align with the visuals will feel disconnected and unprofessional.

**First, get the exact video duration:**
```bash
ffprobe -v quiet -show_entries format=duration -of csv=p=0 INPUT_VIDEO
```

**Then write a timed script** that maps narration to the frame timeline you built in Step 2. Every line of the script should correspond to what's visible on screen at that moment.

#### Script Rules

1. **Content must match the screen** — if the user is tapping a button at 4s, the narration at 4s should describe that action. Never narrate something that isn't visible.
2. **Fill the full video duration** — the voiceover should naturally span the entire recording. Not too short (dead silence at the end), not too long (audio gets cut off). Aim for the TTS output to be within 2-3 seconds of the video length.
3. **Flow with transitions** — when the screen transitions between views, use that moment for a brief pause or transitional phrase. Don't talk over a screen change.
4. **Be natural and conversational** — not robotic marketing speak.
5. **Highlight key features** — call out what makes the app special as those features appear on screen.

#### Write the script as a timed outline first

Map each line to the timestamp where it should be spoken:

```
[0-3s]   "Meet TaskFlow — the simplest way to stay on top o