---
name: video-recording-production
description: "Plan, capture, edit, narrate, and validate engineering demo videos built from real CLI and product UX footage. Use for OBS recording, coding-agent demos, screen-capture troubleshooting, narration synchronization, or final video QA."
---

# Engineering Demo Video Production

Create trustworthy, smooth engineering demos from real CLI and product UX footage.

## Use this skill when

- Recording GitHub Copilot CLI, Codex CLI, Claude Code CLI, or another coding agent.
- Demonstrating a workflow that ends in a product UX such as Microsoft Fabric.
- Troubleshooting OBS black screens, letterboxing, unreadable terminal text, or RDP capture.
- Editing long-running commands into a concise 3-5 minute story.
- Synchronizing narration, captions, agent labels, and visible actions.
- Reviewing a final MP4 for silence, black frames, repetition, incorrect claims, or aspect-ratio distortion.

## Non-negotiable output contract

1. **Real actions, truthful claims**: never narrate an action that the visible agent did not perform.
2. **One story state**: each segment must show the notebook or artifact state that existed at that point in the workflow.
3. **Explicit agent identity**: label every CLI segment with the actual CLI being shown.
4. **Readable capture**: terminal text must remain legible at the delivery resolution.
5. **No geometric distortion**: preserve aspect ratio; letterbox when source and target aspect ratios differ.
6. **Constant narration speed**: synthesize every line with one voice and one rate; do not use `atempo`.
7. **Measured QA**: validate streams, duration, black frames, silence, timeline transitions, and checksum before delivery.

## Workflow

### Phase 0: Write the story contract

Define the workflow before recording:

| Field | Required content |
|---|---|
| Business scenario | What data or artifact exists, and why the user needs the demo |
| Agent sequence | Which CLI appears, in what order, and why |
| Prompt contract | Exact prompt shown to each agent |
| Expected actions | Commands, mutations, execution, and verification actually expected |
| State after segment | Exact persisted artifact state at the handoff |
| Failure disclosure | How rate limits, auth failures, or unavailable tools will be described |
| Final UX | The product page that proves the result |

Use `templates/storyboard-template.md`.

### Phase 1: Preflight the capture

1. Set the delivery format first: normally H.264, 1920x1080, 30 FPS, AAC.
2. Increase terminal font size before recording; do not rely on post-production sharpening.
3. Record a 10-second test and verify:
   - capture is not black;
   - terminal text is readable;
   - the full application window is visible;
   - no OBS window or recording controls appear;
   - mouse and window switching are captured.
4. On RDP or multi-monitor machines, validate the chosen OBS capture method after every display change.
5. Record separate clips per agent or story phase. Independent clips are easier to replace than one monolithic take.

Use `templates/capture-checklist.md`.

### Phase 2: Capture authentic execution

- Show the exact prompt before execution.
- Keep real commands and progress visible.
- Print short progress lines before long operations.
- Record the product UX immediately after the CLI creates or changes the artifact.
- Capture a clean, stable final UX view for at least 5-10 seconds.
- If an agent hits a usage limit, show the error and describe it transparently. Do not fabricate successful output.
- Keep a raw manifest containing purpose, duration, file size, and SHA-256 for every clip.

### Phase 3: Build the edit

1. Cut waiting, repeated polling, blank pages, OBS controls, and accidental window switches.
2. Keep the semantic order:

   `prompt -> commands -> progress -> result -> persisted product UX -> next agent`

3. Speed up waiting sections, not the key prompt, result, or final UX.
4. Prefer continuous source ranges. Avoid replaying a range or freezing a terminal for a long narration block.
5. When the source is wider than 16:9:
   - scale to the target width while preserving aspect ratio;
   - pad the unused height;
   - never independently force both width and height.
6. A later product state must not appear in an earlier segment.
7. Open the final product UX once. After it is stable, hold the same frame instead of replaying the page-open sequence.

Recommended FFmpeg pattern for a wide source:

```text
crop=<active-width>:<active-height>:0:0,
scale=1920:-2:flags=lanczos,
pad=1920:1080:0:(oh-ih)/2:color=black,
setsar=1
```

### Phase 4: Narration and captions

- Use one voice, one rate, and one volume for every line.
- Narration should begin 1-3 seconds after a new agent or UX appears.
- Describe what is visible now, not what will appear later.
- Do not read resource names, GUIDs, or internal IDs unless they are the subject of the demo.
- Keep ordinary breathing gaps around 2-5 seconds.
- Treat unexplained silence over 7 seconds as a review finding.
- Keep captions concise; narration may provide the extra context.
- Add 2-3 seconds of quiet hold after the final narration.

### Phase 5: Validate before delivery

Run:

```powershell
pwsh -NoLogo -NoProfile -NonInteractive `
  -File scripts\validate_video.ps1 `
  -VideoPath .\final.mp4 `
  -TransitionTimes 18,38,58,82,105,125,149,163,177
```

The validator generates:

- stream and duration metadata;
- black-frame results;
- silence durations;
- five-second timeline sheets;
- frames around requested transition times;
- SHA-256 manifest.

Review every generated timeline sheet. Automation catches black and silent spans, but only a human review catches:

- a Claude label over a Copilot window;
- narration that claims an action was not performed;
- a final-state notebook shown during the baseline phase;
- repeated page-open animations;
- OBS windows embedded in the capture;
- vertically stretched terminal or browser footage.

## Decision tree

```text
Capture is black?
  -> Change OBS capture method/source and record a 10-second test.

Text is unreadable?
  -> Re-record with larger terminal font.
  -> Crop only if the complete application remains visible.

Source does not fill 16:9?
  -> Preserve aspect ratio and pad.
  -> Never stretch height independently.

Long command wait?
  -> Keep the first visible action and final result.
  -> Accelerate or cut the middle.

Agent failed due to quota/auth?
  -> Show the real failure briefly and narrate it transparently.

Narration and picture disagree?
  -> Treat the visible source as truth.
  -> Rewrite narration or replace the clip.

Product UX opens more than once?
  -> Keep one opening sequence.
  -> Freeze/hold the stable final page.
```

## Validated lessons from the FNTK cross-agent demo

Verified on 2026-08-06 against a real 1920x1080, 30 FPS, narrated CLI demo:

- Automated OBS capture under RDP was not reliable enough; manual per-agent capture was the safer fallback.
- A 4K desktop fitted into a 1080p canvas made terminal text too small; capture-time font sizing matters more than sharpening.
- Cropping a terminal without inspecting its true active canvas cut off content.
- Scaling a wide active canvas directly to 1920x1080 introduced vertical distortion; proportional scaling plus padding fixed it.
- Reusing a final Fabric frame in the baseline segment leaked later Claude content into an earlier state.
- Replaying the page-open source caused an obvious loop; a stable hold removed it.
- Labels and narration drifted as the edit changed; both must be derived from the final timeline, not the original storyboard.
- Fixed-rate narration initially left 7-16 second gaps. Rewriting useful narration reduced the longest gap to about 6.5 seconds without changing speech rate.
- Five-second contact sheets plus transition frames exposed errors that duration and black-frame checks could not detect.

See `references/lessons-learned.md` for the detailed postmortem.

## Files

- `scripts/validate_video.ps1` - repeatable FFmpeg/FFprobe QA.
- `templates/storyboard-template.md` - story and state contract.
- `templates/capture-checklist.md` - OBS and capture preflight.
- `references/lessons-learned.md` - detailed evidence and anti-patterns.