Skip to main content
skill CX Codex

cap-demo — Claude Code skill: video demos and installation

The cap-demo Claude Code skill turns a page URL into a short product demo with a 3D camera, branded background, and music. It runs when an agent is asked to make a product video.

MIT ★ 184 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add joeseesun/capwise --skill cap-demo -a claude-code
Open on GitHub

What cap-demo does

cap-demo opens a page, records browser actions, and exports an MP4 with 3D camera shots, a brand-colored background, a synthetic cursor, and music. It picks a CTA or a scroll path; an agent-driven run can inspect frames and reshoot failed transitions.

It requires macOS on Apple Silicon, Node 18+, Python 3, ffmpeg, ffprobe, and the cap CLI on PATH. macOS screen-recording permission must be granted to cap. Run npm install inside the skill directory on first use. Playwright Chromium must also be cached; if it is not, install it with npx playwright install chromium. Windows and Linux are unsupported.

What it helps with

  • record a product page from its URL
  • create a short demo with 3D camera shots and music
  • reshoot a video when a CTA leads to a dead end

Example prompts for the agent

  • Make a short product demo video from this page URL.
  • Record the page and create a demo with 3D camera shots and music.
  • Reshoot the demo by scrolling instead of clicking the CTA.

How to install cap-demo

1Skills CLI (Vercel)

npx skills add joeseesun/capwise --skill cap-demo -a claude-code

2Manually: put the files in place

~/.claude/skills/cap-demo/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cap-demo/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cap-demo

How do I install cap-demo in Claude Code?

Run npx skills add joeseesun/capwise --skill cap-demo -a claude-code. The skill file is installed at ~/.claude/skills/cap-demo/SKILL.md.

What does cap-demo do?

It records a page from a URL and turns the capture into a short MP4 product demo with 3D camera shots, a branded background, a cursor, and music.

What does cap-demo need to run?

It requires macOS on Apple Silicon, Node 18+, Python 3, ffmpeg, ffprobe, and the cap CLI on PATH; cap needs macOS screen-recording permission. playwright-core and a cached Chromium build are also needed; install Chromium with npx playwright install chromium if no cached build is available.

Source text

SKILL.md · MIT
---
name: cap-demo
description: Generate a cinematic 3D product-demo video from any URL — scouts the page, records it with virtual input, and treats it with Cap's 3D camera, brand background, and music.
---

# cap-demo

Give it a URL, get back a short, cinematic product-demo video. The pipeline
scouts the page headlessly, shoots a headed browser with **virtual input only**
(CDP mouse/keyboard — the user's real cursor is never touched), records with
Cap's CLI, then treats the recording with Cap's 3D camera, a brand-matched
background gradient, a synthetic cursor, and music, and exports an mp4.

> **macOS only (for now).** This skill records via Cap's window capture and
> resolves a cached Playwright Chromium under
> `~/Library/Caches/ms-playwright`, both of which are macOS-specific today.
> Apple Silicon is assumed (the bundled Chromium path is `chrome-mac-arm64`).

## The skill directory

`<skilldir>` below is the directory this `SKILL.md` was installed into. `cap
agents install` writes it next to the main `cap` skill, so it is one of:

- Claude: `~/.claude/skills/cap-demo`
- Cursor: `~/.cursor/skills/cap-demo`
- Codex: `<CODEX_HOME>/skills/cap-demo` (default `~/.codex/skills/cap-demo`)

There is no `cap-demo` binary on PATH — the `cap-demo` command is just
`node <skilldir>/cap-demo.mjs`. Alias it if you like:

```
alias cap-demo='node <skilldir>/cap-demo.mjs'
```

## Requirements

- **macOS on Apple Silicon.** Windows/Linux are not supported yet.
- **Node 18+**, with `playwright-core` vendored into the skill. Run `npm
  install` once inside `<skilldir>` on first use. It **reuses an already-cached
  Chromium** under `~/Library/Caches/ms-playwright`; if none is cached, run
  `npx playwright install chromium` once.
- **`python3`** and **`ffmpeg`/`ffprobe`** on PATH.
- The **`cap` CLI** on PATH (Cap Desktop, https://cap.so) with macOS
  **screen-recording permission** granted to it. Both stages otherwise resolve
  the binary from `CAP_BIN`; if neither is set they error clearly.

## One-liner

```
cap-demo https://website.com
```

Output lands at `<outDir>/<slug>-demo.mp4` (default `<tmp>/cap-demo/<slug>/<slug>-demo.mp4`).

## Two modes

- **Deterministic** (`cap-demo <url>`): fixed heuristics, no agent in the loop.
  Scores the best CTA, picks click-through vs scroll, paints a brand gradient
  from the page colors, picks music by brand darkness. Good, ~70% quality. Use
  it for batch runs or when you cannot watch the frames.
- **Agent-driven recipe** (recommended, ~95% quality): the agent runs the
  same steps but frame-QAs each stage and applies judgment — sets the brand
  color by eye, matches export fps to the real capture rate, reshoots on a
  dead-end CTA, regrades until the beats read. This is the path that produced
  the shipped demos. Follow the recipe below.

## The agent recipe

Run the two stages by hand so you can inspect between them. Both scripts live in
this skill; the orchestrator just chains them.

### 1. Scout + shoot

```
node <skilldir>/lib/scout-shoot.mjs <url> <outDir> <slug> [--story click|scroll]
```

- Writes the recording to `<outDir>/<slug>.cap` and the beat log to
  `<outDir>/<slug>.timeline.json`.
- Prints a final JSON line: `{"slug","story","scout":{title,hero,accent,pageBg,ctaText}}`.
  Read it to see what it decided (story, chosen CTA, brand colors).
- It already: kills stale test-chrome, closes Finder windows, dismisses cookie
  banners, injects the shimmer div, matches the capture window by exact page
  title (asserts a single match), and logs the virtual cursor path.

**Story choice.** Leave it to auto for most sites (a strong content CTA →
`click`, otherwise `scroll`). Force `--story scroll` for product one-pagers that
showcase best as a scroll of their own sections, or when the top CTA dead-ends
at a booking/login page.

### 2. Frame-QA the raw recording (before treating)

Extract a few beat frames and **look at them**:

```
ffmpeg -y -ss <t> -i <outDir>/<slug>.cap/content/segments/segment-0/display.mp4 -frames:v 1 /tmp/raw-<t>.png
```

Check: the right window/content is captured (no leftover footage from a prior
shoot), no cookie banner leaked in, the CTA click did **not** dead-end at a
booking calendar or login form, and the **end** of the clip is clean (no desktop
or Finder window bleeding into the bottom of the capture). If any of that is
wrong, reshoot with `--story scroll` or a better landmark before spending an
export.

### 3. Treat + export

```
python3 <skilldir>/lib/treat.py <outDir> <slug> [--music ID] [--quality 4k|hd] [--bg-gradient FROM_HEX,TO_HEX]
```

- Aligns beats to video (tail-anchored: the video can be **shorter** than the
  event log — never trust event times blindly), trims dead time, aims three 3D
  shots at the logged landmarks, paints the brand gradient, synthesizes the
  cursor track from the bundled cursor assets, copies music, exports the mp4.
- **Set the brand background by eye** when the site is gradient-heavy or
  light/pastel: `getComputedStyle` lies on those (e.g. a site that looks white
  with lavender accents can sample as black). Look at the raw frames and pass
  `--bg-gradient FROM_HEX,TO_HEX` (light sites → a soft light gradient; dark
  sites → a deep tint of the brand hue).
- **Match export fps to the real capture rate.** `cap record --detach` can
  engage late and the window capture stalls timestamps on static pixels, so the
  true rate is often ~58, not 60. Check it and avoid the 58-vs-60 judder:
  `ffprobe -v error -select_streams v:0 -show_entries stream=nb_frames,duration -of csv=p=0 <cap>/content/segments/segment-0/display.mp4`,
  then pass `--quality hd` (60) only if the capture is really ~60, otherwise
  leave fps at the source rate (omit `--quality`).

### 4. Frame-QA the export, then regrade if needed

Extract 4 beat frames from `<outDir>/<slug>-demo.mp4` and look: each beat
readable, a typing shot aimed at the **text-entry point** (not the field
center), no window/desktop bleed, clean fps, music fades feel right. If a shot
reads too tight or the aim is off, adjust and re-export. The reference 3D poses
were tuned on full-desktop captures; a browser-window capture fills the card
more, so distances can read ~30% too tight — back the zoom off if so.

### 5. Deliver

Ship `<outDir>/<slug>-demo.mp4`.

## Hard editorial rules (encode these every time)

- **12s max** total. The tail is shaved evenly if the cut runs long.
- **A camera cut MUST be a content cut.** Every 3D perspective change lands on a
  different section/page — the shot boundary sits exactly on the clip cut or the
  scroll into new content. Never cut the camera mid-idle.
- **Cut on action, trim dead time.** Cut on the click; resume on the loaded
  page. Trim page-loads and loading-state frames — never let a blur-up or
  spinner leak into a shot tail (frame-check the cut points).
- **Aim at content, not the container.** Shots are aimed at landmarks (hero, the
  clicked CTA, the destination header), not copied pans. Blur focus rides the
  aim.
- **One motion system.** All emphasis lives in the 3D shot (a dolly-in is the
  click punch). Never stack 2D zoom segments on 3D shots — the two systems fight
  and read as jarring.
- **Hands off.** Virtual input only; the user's real cursor/mouse is never
  moved. The on-screen cursor is synthesized post-hoc from the logged glide path.

## Options reference

Orchestrator (`cap-demo <url> [flags]`):

- `--out DIR` — output directory (default `<tmp>/cap-demo/<slug>`).
- `--slug NAME` — project slug (default: the URL host, dashed).
- `--music ID` — music track id (see below). Default: chosen by brand darkness
  (dark → `lofi-cinematic-pulsebox`, light → `sunday-mood-lofi-cafe-upbeat-bluelike`).
- `--quality 4k|hd` — `4k` = 3840x2160 / 60fps / maximum / filesize-optimized;
  `hd` = 60fps / maximum. Omit for the source-rate default.
- `--story click|scroll` — force the storyboard (default: auto).

`lib/treat.py` extra flags (when running the stages by hand):

- `--bg-gradient FROM_HEX,TO_HEX` — override the brand gradient by eye
  (e.g. `--bg-gradient E4DCF8,C6BAEA` for a light lavender, or `261A40,0C0914`
  for a deep purple).

**Bundled music** (a premium/dark/light/moody spread):
`lofi-cinematic-pulsebox` (moody/premium), `lofi-hip-hop-leberch` (dark),
`sunday-mood-lofi-cafe-upbeat-bluelike` (light/upbeat), `lofi-smooth-pulsebox`
(light/smooth). Music resolves only from the skill's bundled
`assets/music/<id>.mp3`; an unknown id errors.

**Binary resolution** (both scripts): Cap binary = env `CAP_BIN`, else `cap` on
PATH, else a clear error. Chromium = newest cached
`~/Library/Caches/ms-playwright/chromium-*` (macOS), else the pinned
`chromium-1228` build.

## For dev tools / typing showcases (closeup variant)

For dev tools with a live terminal or code on screen, a bespoke storyboard beats
the generic click-through. Scout for `[class*=terminal]` / `pre` / `code`,
scroll each to center, dwell ~2.7s (live terminals animate = free motion). The
**closeup shot recipe**: a gentle tilt (tiltX 10-13, tiltY 9-13, rotateX -4) so
text stays legible, a tight slow push-in zoom (0.72-0.82), and blur focus locked
ON the element (focusX = the element's fraction, small focusSize ~0.55). Keep it
a single continuous clip (no editorial cut) so scrolls stay smooth — cuts are
3D-only. Aim typing shots at the **text-entry region**, not the field center.
Rebuild a bespoke shoot from `lib/scout-shoot.mjs` as the base when a site
deserves it (edit a fresh copy — do not sed/splice shot arrays, overlapping
offsets corrupt the file).

© joeseesun · MIT · joeseesun/capwise

Similar skills

All skills for Browser and scraping →

From the same set4

Project sponsors

Companies that keep this analytics open