Brief and story
1. The brief: what you must know
Find these out before anything else. Read what you were given first (the site, the app, a deck, a reference film); ask only for what is still missing, in one message.
| Question | Why it changes the film |
|---|---|
| Who watches, and where? | Investors in a room, visitors on a landing page and a muted social feed need different openings, lengths and text sizes |
| What should they do afterwards? | It becomes the last frame: an address, a QR code, a button |
| How long? | Sets the word count: about 2.5 spoken words a second, less for a film with pauses |
| What is the product, really? | You need to use it, or see it used, to show it truthfully |
| Is there a film they like? | A reference settles pace and look faster than any description |
| What must be in, what must not? | Features not yet live, competitors, claims legal has not cleared |
Defaults when they do not say: 16:9 at 1920 × 1080 authoring, 30 fps, 60 to 100 seconds, one narrator, the brand's own fonts and colours, light ground if the product is light.
2. Study the reference
If they give a reference film, take it apart before you write.
- Cuts:
npx hyperframes measure cuts ref.mp4or ffmpeg scene detection. Make a contact sheet with one tile per shot (scripts/sheet.sh). - Words:
npx hyperframes transcribe ref.wav --json. - Write a shot sheet: time, length, what is on screen, what is said. Then the proportions: how many seconds of problem, product, ending. Note shot length, where text appears, when music changes.
What you take from a reference is its structure and pace, never its footage, music, wording or characters.
3. Story shapes
Pick one and say which. They work for any product; what changes is who the people are and what the product
screens look like (section 4 and video-footage-and-screens).
Story film (pitch, launch, brand). Hook → meet the people → the problem lands on all of them → each one's worry → what they tried → one line that sums it up → the product answers → the people again, better off → end card. The problem is 45 to 55 percent of the length. This is the shape to use when the audience must first care.
Website promo (30 to 60 s). Hook stating the outcome → the product doing its one main thing, large → three proof beats (a feature each, on screen two to four seconds) → one human moment → end card. Value is stated by the second beat; everything after it is evidence.
Product walkthrough (60 to 120 s). One person with one task, start to finish in the real product. Each step is a screen plus the one piece of it that matters, pulled out large. Say what the person gets at each step, not what the button is called.
Social cut (10 to 30 s). One idea. Text carries it without sound. The first frame already says something.
Adapting to the product.
| Product | Who the people are | What "the product, large" means |
|---|---|---|
| Consumer app | people in their own lives, at home, on the move | the phone, with one piece of a screen pulled out beside it |
| SaaS or B2B tool | people in roles: an ops lead, a founder, a support agent, each with a deadline | a browser window, with the one panel or number that matters enlarged |
| Website or marketplace | a visitor with a need | the site itself: the hero, a search, a result, a checkout, as scrolling captures |
| Online shop or physical product | the buyer and the moment of use | the company's own product photos and footage, plus the page where you buy it |
| Service | the customer before and after | the booking or sign-up flow, and the result the service delivers |
4. People
When the film has people, make them particular. For each: a name, an age, a job, a city, and the one thing they want from the kind of problem this product solves. Give different people different wants: an audience of strangers finds itself in at least one. In a film for a personal-finance app that was a bike, a home, a wedding and a trip; for a hiring tool it might be four managers with four different roles to fill. Show the want as a picture, and show every want the same way.
Names must suit the footage you can actually get, so cast and name together (see video-footage-and-screens).
Keep one person's numbers the same as the account shown in the product, so story and screens agree.
These people are invented examples played by stock-footage models. Say so in SCRIPT.md and never present them
as customers.
5. Writing the script
Write lines to be said aloud, in short hits. The examples below are from one film, for a personal-finance app; write the equivalent for the product in front of you. What works:
- A hook that is a contrast or a small joke with truth in it: "Payday. The best day of the month. For about four hours."
- A callback: set up "four hours", pay it off with "Nine a.m. ... By lunch, it's spoken for."
- Fragments for introductions: "Kabir. Designer. He's wanted one bike for three years."
- The person's own question in their own words, one each: "Can I buy the bike, and still sleep at night?"
- One line that names the problem so well it could be the film's title: "They're not bad with money. They're alone with it."
- A line that hands over to the product: "Everyone has advice. Nobody has their numbers." then "Give it your real numbers."
Rules:
- One idea a line. Lines of two to five seconds. An id for every line (
n-01,p-01,e-01): the id names the audio file and the clip. - Write numbers and dates as they are said: "twenty twenty-eight", "nineteen ninety-nine a month".
- Use the audience's own currency, units and place names, and the words they use for the problem.
- Take product claims from the product's own words. Keep a table in
SCRIPT.md: line, where it comes from. - Leave words out where the picture says it. A name tag on screen does not need "meet Kabir".
- After the first full pass, cut a tenth. It is always too long.
Words the company itself avoids, avoid too. If its own copy never says "loan", neither does the narrator.
6. The shot plan
For every line, decide what is on screen and what changes on which word. Write it as the table in SCRIPT.md
(time, picture, voice) and, once timings exist, as the frame-numbered shot list in SPEC.md.
Check the plan against these before building:
- Does frame 0 already show a person or a title? It is the thumbnail.
- Is every important line also on screen as text? Rooms are noisy and feeds are muted.
- Does anything hold longer than three seconds with nothing changing?
- Is each kind of thing (name tags, wants, plans, advice) done one way throughout?
- Does the ending bring back what the opening set up?
- Does the last frame say where to go, and hold at least six seconds if it carries a QR code?
templates/SCRIPT.md has this form ready to fill in.