Workplace films

The people watching were sent this film; they did not choose it. They give it five seconds, then decide. A slide with a sentence on it loses them, however clean it is. What keeps them is a picture that changes while the voice talks: coins that stack, a lock that opens, a window closing on a calendar, a yearly limit filling up, the clause of the plan marked as it is read, the value changed in the app they will use. This page is the whole recipe. Read the others only when it sends you there.

1. Find the three facts and the one action

From the source document, write in DIRECTION.md:

• The action: what the viewer does afterwards, where and by when ("raise your rate to 5% in the benefits portal"). Show it briefly; it is not the ending.
• The hook: what they lose or gain if they don't, in one line. Open on it in the first five seconds. Never open on a welcome or the company's name.
• Three facts that make the action obvious. More than four and the film becomes a policy document; leave the rest to the guide it links to.

2. Scaffold

pnpm cf start DIR --document SOURCE.md --playbook PLAYBOOK --treatment workplace --length SECONDS --audience "…" --takeaway "…"

start copies the source document into the project (source/) and lists every figure in it in EVIDENCE.md; critique then names any figure you typed (a word, a chart value, a sketch number) that the document never states, and draft says when the film falls well short of the length asked for (a short film usually dropped the brief's facts). With no document, new DIR --treatment workplace --playbook PLAYBOOK --length SECONDS.

Playbooks: benefit-explainer (a benefit and how to use it: a match, a share plan, an HSA), day-in-the-life (one person and one object of theirs through the moments a benefit touches; onboarding and a new hire's first week), policy-change (what changed and what to do: a new rule, a deadline, a new tool), client-update (a calm market or portfolio update for clients), training-moment (a threat or mistake, the signs, the habit). Use one of these five: the other playbooks (product walkthroughs, explainers) are cards and statements that read as slides in a workplace film. They are starting arcs: if yours is a decision, a story or a comparison, reorder or swap beats rather than forcing it into one. Each beat already has a picture with placeholder words: replace the words, keep the pictures. Each playbook also has three endings (the step in the app then the film's object; a bookend where the opening picture comes back changed; the step on a phone then a close of its own), one picked per project and named in DIRECTION.md; --ending NAME chooses another. The treatment gives each project one of five looks (clean, notebook, brief, meadow, daylight: a palette, a type voice and clean or hand-drawn lines), picked from the folder name and written into DIRECTION.md, so films from the same playbook don't share a face. Keep it, or choose by subject with --theme (meridian financial, meadow benefits and health, briefing training, security and policy); a brand kit overrides all of them. Screens (portal, inspect, compose) stay crisp in a drawn film.

3. One picture per fact

Each fact gets the mechanism that shows it. These are sketches: fill sketchText (words from the source), sketchSay (the narration word each moment lands on) and sketchParams (the figures). pnpm cf sketch NAME prints the beat to paste with every slot named.

A picture must keep up with its narration: every figure or idea the voice names gets its own moment (a cue, a value's say, a sketch moment). Three figures said over one still number is a slide. A pointer gliding across the frame is not motion, to the verdict or to a viewer: when it reaches something, move the thing it touches (the card tugs toward the link, the email flinches toward the bin, the button presses).

Give the film one object of its own, and keep it across cuts: a cast of the film's objects (paycheck, jar, calendar, badge, house, umbrella, receipt, person, coin) that opens the film and comes back at the end (a paycheck that splits, a jar that fills, a badge for a new hire). It is what makes this film this film and not the last one. Two beats on the same idea share a cast, a world or an element id, so the cut is invisible; a new idea cuts hard (the default), goes into an element of the last scene (into: "share-31": from the figure into one of the claims it counts; from the phone into its screen), or pushes to the next step; never panel, which covers the picture with a flat slab of colour and reads as a rendering fault here. Point at the words that matter with marks on canvas text ({words: "Share securely", style: "circle", say: "securely"}; strike for the old way, highlight for the clause of a policy): they land on their word and stay attached to the text. Show the step done (portal) in one sentence, not a held screen: every film that ends on the same app mock-up looks like the last one. When the step is in a screen you draw yourself, give each control an id and let a canvas pointer press them on their words (steps: [{to: "claims", say: "Claims"}, …]); it follows the controls if the layout changes. examples/fsa-deadline quotes the plan document, marks the clause and presses Submit this way. Then close on the film's own picture (its object changed: the jar full, the calendar checked, the person with the paycheck), with the deadline or the line to repeat in the voice. One kinetic line (kinetic stack) for the sentence people should repeat is plenty.

People and places: greyed B-roll

Workplace films are about people, and the sketches have none. A few seconds of footage behind the hook, a close or a turn, greyed out so the type reads, puts the film in a real office or a real morning:

"plate": { "file": "assets/clips/office-morning.mp4", "side": "full", "treatment": "mono", "scrim": 0.75, "drift": "none", "offset": 0.5 }

Put it under big type (a kinetic hook or close) or a simple picture. Under a detailed sketch with small labels it competes: raise scrim to 0.85 or keep that beat on plain ground. Footage never carries a figure or a word; generic clips (an office, a street, a kitchen table) are reusable across films, so keep a local folder of them. Generating one costs money (veo-video, about $0.20–0.40 a clip at 720p); with no budget, leave it out.

4. Narration

One idea per beat, written for the ear: short sentences, figures as digits, the word that names each moment said where the picture should move (that word goes in sketchSay). voice DIR --draft is free and local (if it says a name wrong, respell it for the voice only: "voice": {"pronounce": {"Alder": "All-der"}}); it measures its words with Whisper, which takes about a minute per minute of speech, longer while other work runs. Wait for it.

5. Draft and read the verdict

pnpm cf draft DIR

It ends with a motion verdict that starts READY or NOT READY (a NOT READY draft exits with code 2). The film is done only when it says READY: a NOT READY film is not handed over, whatever the time box, and the verdict lists each edit (each is one change to one beat): the stillest beats and what to land on which words, the beats that are only words (a single figure on a card counts: a number chart with one value is a stat card; step it through several spoken values or give the figure a picture) and the picture for each, objects standing on each other, the source's facts a short film never states, a voice over an empty frame, pictures too small for the frame, and a film well short of the length asked for. Under 20% still is a film; over 40% is narrated slides, whatever the film score says. A real reading hold (a figure people must read, the action) is fine: mark that beat pace: "hold". Then open build/sheet.png and build/qa/phone.png and look at every frame. A longer film needs more pictures, not longer narration over the same ones: each added fact gets its own beat and picture.

6. Truth and tone

• A client letter's figures must reconcile before they share a picture (sleeve returns × weights against the total): if they do not, chart them separately and say so in DIRECTION.md. Land financial figures rather than count up to them; a count shows values the letter never states.
• Every figure comes from the source document and its beat names that document in source ("Alder Street Retirement Plan, 2027"). Counts and scales come from sketchParams, never from the drawing, and a sketch number is a figure too: never invent an amount to make a sketch draw money (if the page says "resets to $0", show the reset, not a balance).
• Keep the brief's must-haves: what it says people must not miss, the dates, the place to act, anything new this year. A film half the length asked for has usually dropped one of them.
• Attribution is short and in the film's words. No disclaimers on screen ("illustrative only", "not advice"); an example is labelled once ("Example: a $60,000 salary").
• Warm and plain, a little wit, never fear. Explain jargon with the picture, not a definition.

Commands, timing and delivery: clearframe-engine. Numbers and charts: clearframe-dataviz. Drawing beyond the sketches: clearframe-canvas.