---
description: product-film is an open-source agent skill that makes short product films from your product's real UI: an HTML timeline, rendered frame by frame with Playwright and cut with ffmpeg.
title: product-film documentation
---

 

## Install

Add the skill to your agent with the command above, then describe the film you want: “make a 30-second launch film for the new share dialog”, “recut the hero film with a shorter ending”, or “a paper-collage explainer of how comments reach a client”. In Claude Code, `/product-film <what the film is about>` also works.

The skill renders on the machine your agent runs on, so that machine needs:

* **Node 18 or later** with npm. Playwright is installed once into each film folder, and Chromium downloads once per machine (about 100 MB).
* **ffmpeg** with libx264\. The paper route also writes ProRes masters, and its quality gate measures VMAF when ffmpeg is built with libvmaf.
* **Python 3** for the paper route, which makes a per-film virtual environment with numpy and Pillow.

Hosted chat apps without a local shell can read the skill and plan a film, but cannot render one.

## How it works

A product film here is a function of time. One HTML page holds the whole film; `window.seek(t)` draws frame `t` from scratch, with no dependence on the frame before.

1. 01**Timeline page**Your components, copied from shipped code or captured as DOM snapshots, inside one page with a camera, a pointer and captions.
2. 02**Every frame**Playwright opens the page headless at device scale 2 and screenshots each frame in turn.
3. 03**Encode and cut**ffmpeg encodes the frames, joins beats and footage, and writes a master, a web file, a review file, a poster and a contact sheet.
4. 04**Review**One review page per film on display.dev, each cut a new version, comments answered in place.

Because the film is code, three things hold that a screen recording cannot give you. Text stays sharp when the camera pushes in, because it is real text rendered at 2× or 3×. A recut re-renders only the beat that changed, and the rest of the film is bit-for-bit the same. And feedback lands on numbers: a hold, a zoom factor or a typing speed, not a new take.

The UI must be the product's own. The agent takes markup and CSS from your shipped components, or captures live screens from your running app with every API call answered by fictional data, and mounts them in the film. Mock-ups and generated video are out.

## Pick a route

Four routes. Walkthroughs come in the kinetic style by default, and a launch that needs breadth can be a reel cut to music. The agent picks from your request and says why; if you name a reference film, it probes it and uses its structure as the grammar.

![A dashboard on a soft plate with a comment popover in front of it, a reply from the agent, and a Republished as v2 status.]()

Routes A and BCinematicA 3D plate and a camera that never stops. Route A cuts licensed live-action footage against product beats; Route B is product beats only.

![A dimmed wall of document thumbnails on a dark teal plate with the claim Every doc. One link., the second sentence in light teal.]()

Route B, reel styleReelClaim-and-proof sections cut to the music's bar lines on flat brand plates, one capability per section.

![The words Every draft gets a second look, in very large type on white, with the last two words in teal.]()

Route C, the defaultKinetic walkthroughA pointer drives one story through isolated UI at extreme close-up on white, morphs instead of cuts, words that arrive in the accent and settle to ink.

![A cut-paper character in a mustard sweater beside a browser window showing a launch plan, on an engraved chart background, with the caption The plan sits in drafts.]()

Route DPaper collageA cut-paper cast tells a story with a problem, a turn and a payoff over real product screenshots, in stop-motion.

__Defaults per route. A length you name always wins.__
| Route             | Good for                                             | Typical length                          | Formats                                                              | Template                 |
| ----------------- | ---------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- | ------------------------ |
| A · with footage  | Website hero loops with people in them               | 30 s loop                               | 16:9; 9:16 as a separate pass                                        | cinematic/               |
| B · pure product  | Landing sections, launch teasers                     | 20–25 s                                 | 16:9; 9:16 as a separate pass                                        | cinematic/               |
| B · reel          | Launch reels that show several capabilities          | 25–35 s on a tempo grid                 | 16:9                                                                 | walkthrough/reel.html    |
| C · walkthrough   | Store-listing promos, feature launches               | 35–40 s for one flow plus feature beats | 16:9 and square from one page; a caption-band or card cut on request | walkthrough/kinetic.html |
| D · paper collage | Social cuts, explainers, people and product together | 45–60 s                                 | 16:9, 9:16 and 4:5 at once, plus an .srt                             | paper/                   |

## What the agent does

The agent settles the inputs it cannot infer, states its assumptions for the rest, and then works in this order:

1. **Settles the brief.** The reference film, the story in one line, the route, the surface and length, and a truth sheet: every claim on screen with its source.
2. **Starts a film folder** with `templates/new-film.sh <route> <folder>`, which copies a working template and installs Playwright there.
3. **Builds beats** one at a time from your components, and checks each with a contact sheet before rendering the next.
4. **Renders and assembles,** then runs the route's checks and looks at frames at full size before anyone else sees the cut.
5. **Publishes a review page on display.dev,** with the cut embedded, “what changed since vN” on top and a scene-by-scene table. Every later cut is a new version of the same page.
6. **Loops on your comments** on that page: one new version per round, a reply in each thread with what changed, and the durable notes recorded in your project's `FILM.md` so the next film starts from them.
7. **Hands off** the web file and poster to your site's video pipeline.

### What stays with you

The taste calls. The agent presents candidates and frames; you choose the shoot, buy any footage license, and decide between looks. It never publishes anything except the review page, and only where and when you ask.

## Checks before anyone watches

Stuck pointers and one-frame flickers are hard to see in stills and easy to see in a film. The templates catch the mechanical failures so review time goes to taste.

__Checks that ship with the templates.__
| Check          | Route     | Catches                                                                                                                                    |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| audit.js       | C, B reel | Pointer rests, holds that freeze a moving pointer, elements that jump for one frame, and frames that depend on the frame before            |
| Strict mode    | D         | A missing shot, box or cue stops the render instead of drawing at the wrong time                                                           |
| check-copy.py  | D         | Words per caption, hold time, one accent word per caption, scene spacing, banned terms read from your style guide, spelling and dash rules |
| gates.py       | D         | Exact frame counts, timing jumps, color tags, encode quality (VMAF ≥ 95), true peak and loudness                                           |
| review.py      | D         | Phone-size contact sheets, transition strips around every cut and a frame-difference trace, so a character drawn twice shows up            |
| Contact sheets | All       | Continuity and framing across the whole film at one frame per second                                                                       |

An agent cannot hear. When a cut has sound, the skill measures it and says plainly that it needs your ears.

## Teach it your product

The agent reads what your project already has before it asks. None of these files is required.

__Project files the skill reads, and what for.__
| File                                   | Used for                                                                                                                                 |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| FILM.md                                | Your team's film notes: reference builds, looks you rejected, capture setup, house rules. Read first; it overrides the skill's defaults. |
| DESIGN.md, tokens.css, Tailwind config | Colors, type, radii, borders and focus rings. Every template keeps its brand values in one block to replace.                             |
| Shipped UI and a dev server            | The components on screen, copied or captured live on fictional data.                                                                     |
| PRODUCT.md, VOICE.md, a style guide    | Audience, naming, tone and banned terms for captions and on-screen copy.                                                                 |
| Docs, changelog, pricing page, specs   | The truth sheet. A claim without a source does not go on screen.                                                                         |

```
# FILM.md

## Brand
Accent #0E8A7E, ink #121212, plate #F3F3F3.
Fonts: Geist, Geist Mono.

## Looks we rejected
- Color glows behind the UI: they tinted it.
- A zoom on every beat: zoom only onto
  the item the step is about.

## Capture
Dev server: npm run dev -- --port 3999
Hide the changelog notice: set
localStorage "notice:changelog" = "v12".
```

A short `FILM.md` for the fictional Tidewell team. After each review round, the agent records the notes that should outlive the film there, so the second film starts where the first one ended.

## Templates

Every route starts from a working template with the fictional example product, so the first render works before you change anything. You replace its brand block, components and copy with your own.

```
templates/
  new-film.sh      starts a film folder for a route
  common/          copied into every film: Playwright loader, DOM capture and
                   snapshot library, engraved-chart background in your colors
  cinematic/       Routes A and B: 3D beat engine, renderer, assembly
  walkthrough/     Route C and the reel: 2D engine, kinetic and reel examples,
                   beat map for your track, parallel render, motion audit
  paper/           Route D: canvas engine, paper kit and cast, capture harnesses
                   for your app, CLI and an agent window, sound, review, gates
```

Each route has a reference with the numbers that held across many review rounds: [camera rig](https://github.com/display-dev/product-film/blob/main/product-film/references/camera-rig.md), [walkthrough](https://github.com/display-dev/product-film/blob/main/product-film/references/walkthrough.md), [kinetic style](https://github.com/display-dev/product-film/blob/main/product-film/references/kinetic-style.md), [reel style](https://github.com/display-dev/product-film/blob/main/product-film/references/reel-style.md), [live DOM](https://github.com/display-dev/product-film/blob/main/product-film/references/live-dom.md), [paper collage](https://github.com/display-dev/product-film/blob/main/product-film/references/paper-collage.md), [paper capture](https://github.com/display-dev/product-film/blob/main/product-film/references/paper-capture.md) and [paper lessons](https://github.com/display-dev/product-film/blob/main/product-film/references/paper-lessons.md).

## Questions

Does it record my screen?

No. Every frame is drawn from code. The paper route captures stills of your real app on fictional data and composes them into the collage.

Can it show my real app without touching real data?

Yes. The capture harness runs your app on its dev server and answers every API call from a fixtures file, reports any call it did not expect, and blocks everything else. Names, emails and companies come from a fictional story file. The agent compares your repository's `git status` before and after; it must not change.

Does it publish or upload anything?

Only the review page, to display.dev, when you ask. With the display.dev CLI or connector it publishes to your workspace with company access; without an account it creates a 30-day preview you can claim. Captures publish nothing.

Does it cost anything to run?

Nothing by default: no stock footage, and no image, video or audio models. Route A uses footage you license yourself.

What about sound and music?

Films are silent unless you supply a track. The paper route synthesizes pen-and-paper sound effects. Laying your own music under a finished cut is in scope; composing music or recording voice is not.

Can I make it look like my brand?

Yes. Each template keeps its colors and fonts in one block, the background generator renders in your accent, and `FILM.md` overrides the skill's defaults wherever your team decides differently.

What license is it under?

MIT. The fonts the templates use (Geist, Geist Mono, Caveat Brush and others) are under the SIL Open Font License.