# Producing a Demo Video with SmoothCapture (agent recipe)

The happy path from nothing to a polished MP4. Prereqs: the CLI server is enabled (`cli enable` or the Settings toggle) and SmoothCapture has Screen Recording permission (a human grants it once).

```bash
SC="/Applications/SmoothCapture.app/Contents/MacOS/SmoothCapture"

# 0. Sanity check - auto-launches the app in the background
"$SC" cli ping

# 1. Pick a capture source
"$SC" cli devices --json          # note the display id, or the window id of the app you'll demo

# 2. Start recording (starts immediately; no countdown)
"$SC" cli record start --window 5533
#    ...or: record start --display 3 [--area x,y,w,h] [--microphone <id>] [--system-audio]

# 3. Drive the product being demoed
#    Use your UI-automation tool of choice (AppleScript, cliclick, XCUITest, etc.).
#    IMPORTANT: use real mouse clicks and deliberate pacing - clicks are what smart zoom
#    keys off. Pause ~1s on important UI before/after clicking; avoid frantic cursor motion.

# 4. Stop - returns the project bundle path
BUNDLE=$("$SC" cli record stop --json | jq -r '.data.bundlePath')

# 5. Smart zoom - auto-generates cinematic zooms at your click moments
"$SC" cli project autozoom --path "$BUNDLE"

# 6. Optional polish
#    a) Apply a saved editor preset (human-curated look):
#         "$SC" cli project presets
#         "$SC" cli project apply-preset --path "$BUNDLE" --preset "Brand"
#    b) Or edit effects directly in $BUNDLE/project.json - background, padding,
#       webcam layout, extra zooms, trims... see project-json-reference.md.

# 7. Export
"$SC" cli export --path "$BUNDLE" --output demo.mp4 --preset 1080p30 --json

# 8. (Optional) eyeball a frame
ffmpeg -y -ss 2 -i demo.mp4 -frames:v 1 frame.png
```

## Tips for a good result

- **Clicks drive the cinematography.** Each mouse-down becomes a zoom anchor; a click-free recording produces zero zoom effects. Interact with the UI the way you want the camera to move.
- **Trim dead time** by editing `videoSegments` in project.json (split around waits/loads) before exporting.
- **Aspect ratio** for social formats: set `previewAspectRatio` in the bundle's `take-settings.json` (e.g. `portrait9x16`), then re-export.
- **Retakes are cheap**: `record cancel` discards a bad take instantly.
- A recording left open in the editor blocks headless operations (`PROJECT_OPEN_IN_EDITOR`) - close the editor window first.

## Failure handling

| Error | What to do |
|---|---|
| `SERVER_DISABLED` (exit 3) | Run `"$SC" cli enable`, or ask the human to flip Settings -> General -> Command-line control |
| `PERMISSION_SCREEN_RECORDING` (exit 4) | Ask the human to enable SmoothCapture in System Settings -> Privacy & Security -> Screen Recording |
| `DEVICE_NOT_FOUND` | Re-run `devices`; window ids change every launch of the target app |
| `PROJECT_OPEN_IN_EDITOR` | Close the editor window, retry |
| Connect timeout (exit 7) | Check the app can launch; look for a crash dialog |