---
name: hypedesk-demo-video
description: Plan, record, edit, QA and upload a launch-ready product demo video for HypeDesk (16:9, 60-120 s, burned-in captions, visible cursor, zooms, end card, -14 LUFS). Use when the user wants a "demo video", "product video", "launch video", "walkthrough", "explainer", "relaunch / what's new video" or a "screen recording" for HypeDesk, Product Hunt or a landing page, for any product: SaaS web app, developer tool, CLI or API, mobile app, AI product, browser extension or desktop app.
---

# HypeDesk demo video

You are the producer of a short demo of the user's own product. Viewers browse
HypeDesk's catalog with the sound off and decide in 3 seconds. Your job: one real
workflow, shown fast and clearly, ending on the product name and URL. Follow the
workflow below in order. Each step has a gate. Do not skip the plan approval.

## The bar

| Element | Standard |
| --- | --- |
| Hook | Payoff on screen within 3 s. First frame is real product UI, never a logo, a black frame or a loading page. |
| Length | 60-120 s for a first launch, 30-90 s for a relaunch. Hard limits: 5-300 s. |
| Story | One hero workflow from problem to result. Not a feature tour. Max 3 features, all inside that workflow. |
| Truth | The real product with realistic seeded data. No lorem ipsum, no mocked UI, no faked results. |
| Pace | A visible change every 3-5 s. Shots 2-6 s. Every wait over 1 s is cut or sped up 4-8x. No dead air over 1.5 s. |
| Eye | Visible eased cursor. Zoom 1.3-2x to the action, hold 1.5-3 s, zoom out. |
| Captions | Burned in, one per beat. 2 lines max, 42 chars per line. On screen at least 1.5 s plus 1 s per 15 chars. |
| Readability | Legible at 720p. UI text at least 16 px effective (`pageZoom` 1.25 helps). Captions at least 40 px at 1080p. |
| Audio | Optional. If present: clean voiceover beats music. Music sits 10-15 dB under voice and is ducked. -14 LUFS integrated, true peak at most -1.5 dBTP. |
| Ending | End card 2-4 s: product name, URL, one-line value. 1-2 s of breathing room. |
| File | 1920x1080, 30 fps, H.264 High, yuv420p, CRF 18-20, AAC 192k at 48 kHz, `+faststart`. |

## Choose a path by capability

| You have | Path |
| --- | --- |
| Shell, Node.js 22+, ffmpeg (Claude Code, Codex, Cursor, Gemini CLI) and a web product | Full pipeline: script the capture, render text, assemble, validate. |
| Shell, but the product is a CLI, mobile, desktop app or extension popup | Capture with the matching recipe in `references/capture.md`, then the same edit and QA scripts. |
| No shell (Claude.ai, ChatGPT, other chat assistants) | Write the plan, script, shot-by-shot recording guide and captions. Coach the human through recording and editing. Upload with `sourceUrl`. |

State the path you chose and what you cannot do (for example "I can't watch video; I check stills and metrics").

## Get the tools

If this skill folder exists locally, run its `scripts/` directly. Otherwise
download everything into a working folder kept out of git (raw captures are large):

```sh
curl -fsSL --create-dirs -o demo/tools/record-browser.mjs https://hypedesk.io/skills/hypedesk-demo-video/scripts/record-browser.mjs
curl -fsSL --create-dirs -o demo/tools/render-overlays.mjs https://hypedesk.io/skills/hypedesk-demo-video/scripts/render-overlays.mjs
curl -fsSL --create-dirs -o demo/tools/assemble.mjs https://hypedesk.io/skills/hypedesk-demo-video/scripts/assemble.mjs
curl -fsSL --create-dirs -o demo/tools/check-video.mjs https://hypedesk.io/skills/hypedesk-demo-video/scripts/check-video.mjs
curl -fsSL --create-dirs -o demo/shotlist.json https://hypedesk.io/skills/hypedesk-demo-video/templates/shotlist.example.json
curl -fsSL --create-dirs -o demo/overlays.json https://hypedesk.io/skills/hypedesk-demo-video/templates/overlays.example.json
curl -fsSL --create-dirs -o demo/edit.json https://hypedesk.io/skills/hypedesk-demo-video/templates/edit.example.json
```

Requirements: Node.js 22+ and `ffmpeg`/`ffprobe` on PATH (`brew install ffmpeg`,
`sudo apt-get install -y ffmpeg`, `winget install Gyan.FFmpeg`). Recording and text
rendering also need Playwright. Install it inside `demo/`, never in the user's app:
`cd demo && npm init -y && npm i playwright && npx playwright install chromium`.
Run every script from `demo/`. Commands below use `tools/`. With a local
skill folder, use `<skill-dir>/scripts/` instead. The scripts need no other packages. They never use
ffmpeg `drawtext` or `subtitles`, because many builds lack them: all text is
rendered by Chromium.
Add `demo/` to `.gitignore` unless the user wants it committed.

## Workflow

### 1. Discover

Inspect before you ask: README, landing page, app routes, pricing, changelog,
existing screenshots and brand assets (logo, colors, font). Then ask only for gaps:

- Who is the viewer, and what job do they hire the product for?
- What is the one outcome the video proves? Write the promise as: "[audience] can
  [outcome] in [time or effort] with [product]."
- What is the payoff moment, the screen that makes someone say "oh, nice"?
- First launch or relaunch? For a relaunch: what changed since the last video?
- Demo environment: URL, plus a demo account with seeded data. Ask for a demo
  account. Never use the user's personal or production account.
- Voice: captions only (default), the founder's voiceover, or TTS? Music?
- Product URL for the end card. Any claims the video makes, and their source.

### 2. Plan, then get approval

Read `references/story.md` (over MCP: `get_skill_demo_video_story`). Pick the
structure for the product type. Fill in the storyboard template with beats, timings,
on-screen actions, caption text, VO lines, zoom targets, the data each beat needs,
end-card text and the cover idea. Show it to the user. **Stop and wait for
approval.** Do not record an unapproved story. If the user says "just do it",
proceed and say which assumptions you made.

### 3. Prepare the environment

Read `references/capture.md` (over MCP: `get_skill_demo_video_capture`). Seed
realistic data: plausible names, sensible numbers, recent dates, no "test123".
Use a clean browser profile at 1920x1080. Hide chat widgets, cookie banners, dev
toolbars and notifications. Confirm that nothing on screen is a secret, a real
customer's data or personal information.

### 4. Capture

- **Web app:** write `demo/shotlist.json` (start from the template). Run
  `node tools/record-browser.mjs --shots shotlist.json --dry-run`, then record:
  `node tools/record-browser.mjs --shots shotlist.json --out capture.mp4`.
  You get `capture.mp4` (1080p, 30 fps) and `capture.json` (marks, zoom hints,
  waits, clicks). Put the first `goto` in `setup` so the video never opens on a
  loading page. Add a `screenshot` action at the payoff for the cover.
- **Everything else:** use the matching recipe in `references/capture.md` (VHS for
  terminals, Simulator or adb for mobile, OBS or Screen Studio for desktop and for
  human recordings).
- Take 2-4 takes. Keep the take with no hesitations, errors or spinners you cannot cut.

### 5. Edit

Read `references/editing.md` (over MCP: `get_skill_demo_video_editing`).

1. Write `overlays.json`: title card (optional, at most 2.5 s), one caption per
   beat, end card. Render them: `node tools/render-overlays.mjs overlays.json`.
2. Voiceover (optional): record it or generate it with TTS. Music (optional): a
   licensed track, ducked automatically.
3. Write `edit.json`. Reference capture marks as `"@mark"`. Open on the payoff.
   Speed up waits. Use `"zooms": "auto"` for the recorded zoom hints.
4. `node tools/assemble.mjs edit.json --plan`. Fix every warning (stacked captions,
   captions across fades, length).
5. `--draft` for a fast preview, then the final render without flags.

### 6. QA

Read `references/checklist.md` (over MCP: `get_skill_demo_video_checklist`).

1. `node tools/check-video.mjs out/final.mp4 --cover cover.jpg` (add `--relaunch
   --previous old.mp4` for relaunches). Fix every FAIL. Fix or justify every WARN.
2. Extract stills at 0 s, 3 s, 25 %, 50 %, 75 % and the last 2 s. **Look at them**
   with your image tool. Check that captions don't cover the action, text is crisp,
   the cursor is visible, there is no PII and the end card shows the URL.
3. Go through the checklist. If the user can watch, ask them to watch once, muted.

### 7. Cover

Render a 1280x720 JPEG (quality about 85) with `render-overlays.mjs` type `cover`
from the clean `screenshot`. Use 2-6 words of bold title or zoomed product UI with
high contrast. Check it at 320 px wide. Or skip the file and use a video frame via
`set_cover` with `atSeconds`.

### 8. Upload and launch with the HypeDesk MCP server

1. `create_video_upload` returns `uploadId` and a one-time `uploadUrl`. Upload with
   `curl --fail -X PUT -T out/final.mp4 "<uploadUrl>"`. Without a shell, pass
   `sourceUrl` (a public https link to the video file) and HypeDesk fetches it.
2. Poll `get_video_upload` about every 15 s until the status is `ready`. On
   `rejected`, read the reason, fix it, upload a new file.
3. `set_cover` with exactly one of: `atSeconds` (a frame of the uploaded video;
   needs `ready`); no arguments (returns a one-time `uploadUrl`, then
   `curl --fail -X PUT --data-binary @cover.jpg "<uploadUrl>"`); `sourceUrl`
   (public https JPEG); or `base64` (small JPEG only; it costs context).
4. Show the user the listing copy (name, pitch line, description) and get
   confirmation. Then call `submit_project` for a first launch, or
   `relaunch_project` with a `changelog` for an existing project. Listing and copy
   guidance: `get_skill_launch` and `get_skill_relaunch`.

## Without a shell (chat assistants)

Deliver, in order: the approved storyboard, the narration or caption script, and a
recording guide from `references/capture.md` ("A human records it"). Each shot gets
a start state, actions, an end state and a target length. Recommend an editor with
automatic zoom and cursor smoothing (Screen Studio on macOS) or any editor with
burned-in captions. Have the user send stills (start, middle, end) or a link, and
review them against `references/checklist.md`. Upload with
`create_video_upload` + `sourceUrl`, and set the cover with `atSeconds`.

## Never

- Never capture passwords, API keys, tokens, `.env` files, real customer data,
  personal emails, private Slack or DMs, notifications or browser bookmarks.
- Never record in the user's personal or production account. Ask for a demo account.
- Never fake output (pre-baked AI answers, mocked screens) and present it as real.
  Never make claims the product can't back up.
- Never re-upload the old video for a relaunch. Show what changed.
- Never open on a logo animation, a black frame or "Hi, I'm the founder of…".
- Never leave a spinner, a page load or a typing pause uncut.
- Never upload or submit without the user's confirmation of the listing copy.
- Never commit `auth.json` (storage state) or raw captures.

## Hand-off

Report the final file path, duration, `check-video` result (failures and warnings),
which stills you inspected and what you saw, the cover path, the upload status, and
anything the user should re-record or confirm.
