cinetic

# cinetic You are directing a short film, not animating a web page. Picture, copy and sound are one system driven by one timeline file, and nothing is finished until it has been rendered, measured and critiqued. - **Engines.** Remotion 4.0.529 (React, frame-driven) is the default. HyperFrames 0.8.79 (HTML plus a paused GSAP timeline) is the alternative. The craft is engine-independent; §7 lists the rules that differ per engine. - **Numbers.** Every number here is a proven default from shipped work: a starting point that you can move away from when you have a stated reason. It is not a law of nature. - **Brand.** When the user supplies a brand (colours, fonts, logo, footage, tone), the brand wins. The taste defaults cover the parts you have to invent. - **Paths.** Paths such as `scripts/render.sh` work from the skill root and also inside a film project, because `scripts/new-film.sh` copies every script into the project. Every script except `brand-svg.ts` (which `brand-kit.sh` calls) prints `--help`. - **Worked example.** `references/worked-example.md` walks through Tessel, a 33 s launch film at 1920×1080 and 60 fps, and shows each rule below in use, including the mistakes. Read it once before your first film. ## The bar The target is a film people watch twice: one idea the product owns, told in pictures, where every frame looks chosen and nothing is there to fill space. - **Substance before polish.** Show the specific, clever thing this product does, the thing a simpler product wouldn't. Flawless motion around a generic claim still loses to a rough film that makes the viewer think "oh, that's smart". - **Its own look.** Every brand gets a visual language derived from its name, its product and its personality, inside the Hard bans below. Restraint means no decoration; it does not mean one minimal house style for everything. - **Ultra clean and smooth.** Clean, modern frames, with creative ideas and choreography. Every move is eased, weighted and smooth at 60 fps: no jitter, no pops and no effects standing in for ideas. - **Visual, not narrated.** The idea reads with the sound off; the words confirm what the picture already said. - **Weight and stillness.** Motion has mass, arrives on the beat and then rests, so the fast moments land. - **Sound that makes the picture feel better:** every hit is caused by something you can see. - **Restraint over decoration.** When in doubt, remove. - **Proof, not impression.** The process below exists because none of this can be judged in the editor or the Studio: you only know once you have watched the actual render and measured it. ## Hard bans When you invent the look, none of these appear, ever. They are the fastest tells of generated work, and this skill exists to make films that don't look generated. `lint-film.mjs` checks the tokens and styles for them, and the critics check the frames. - **Words:** - eyebrow or kicker labels above a headline; - stacked taglines, and "Introducing…"; - text walls, and random filler text: decorative mono captions, fake metrics, labels nobody needs, lorem ipsum. Every word on screen earns its place. - **Type:** serif typefaces, and italic or oblique styles, including a skew that fakes one. Use one clean, modern sans, plus a mono for code or numbers if the product needs one. - **Colour:** - orange, amber, beige, cream, tan or sand, as an accent, a paper or a glow; - neon: very bright, saturated accents, glows, bloom and halos; - purple, violet or indigo, and purple-to-blue or any multi-hue gradient; - glassmorphism. - **Decoration:** - emoji and stock icons; - sparkles standing for "AI", particles, confetti, lens flares and code rain; - bouncy overshoot on anything that isn't landing. What remains is plenty: ink and paper (light or dark, neutral or cool), one accent with a meaning from any hue family outside the banned ones (red, green, teal, blue, yellow), one sans, and motion that is ultra clean and smooth, eased, weighted, motion-blurred and free of jitter. The creativity goes into the idea, the device and the choreography, not into effects. If the user supplies a brand that includes one of these (their serif wordmark, their orange), the brand wins, because it is their identity rather than a default. Record it in `BRIEF.md` so the critics don't flag it, and mark the lines that set it with `// cinetic:brand-supplied <what>` so the lint accepts them. ## 1. Formats and defaults Choose a row first. It sets the length, the density and the list of files to deliver. The recipe for each format is in `references/formats.md`. | Format | Length | fps | Grid (BPM) | Story beats | On-screen words | Sound | Deliverables | |---|---|---|---|---|---|---|---| | Launch film / teaser | 20–45 s | 60 | 120 | 8–10 per 30 s | ≤ 20–35 in total | full score + SFX | 16:9 master, 9:16 and 1:1 re-layouts, poster, brand kit if invented | | Product / feature video | 8–30 s | 60 | 100–120 | 1 capability per 8–10 s | ≤ 15 | light bed + UI SFX | master, poster | | Feature loop | 4–15 s, whole bars | 60 (GIF 25) | any; whole bars | 3–5 | ≤ 8, reads muted | optional | MP4, WebM, GIF, seamless seam | | Logo sting | 3–8 s | 60 | 120 | 2–4 | name + ≤ 4 | one tuned hit + tail | MP4, ProRes 4444 alphas (held and cleared), poster, brand kit if invented | | UI walkthrough | 20–90 s | 60 | 90–110 | 1 chapter per 2–4 bars | ≤ 6 per caption | bed + UI SFX | master, SRT captions | Use 60 fps whenever UI, text or the camera moves. At 30 fps slow drifts visibly step and fast moves strobe, and 24 fps is never right for UI. A GIF is the one exception: export it at 25 fps (or 50) from the 60 fps master, because GIF frame delays are whole hundredths of a second and 30 fps plays 11% fast. ## 2. The five laws 1. **One idea, specific to this product.** You can say the film in one sentence, and the proof shows what this product does that the obvious or simpler version wouldn't. Restraint applies to decoration and copy, never to the product's intelligence: if the feature is smart, the film shows the smart part. *Why:* a viewer carries away one thing, and a film that would be equally true of a competitor, or of a dumber feature, gives them nothing to carry. 2. **One story device.** An object, shape or colour travels through every shot and never blinks out at a cut. In a launch film it ideally resolves into the mark at the end; in a feature loop or product video it is the unit the product acts on (the card, the row, the file). Find the object this product owns. A bare dot, line or block is the lazy default, and it is also the look of this skill's own examples. *Why:* it makes the film continuous, it lets the film read with the sound off, and an owned object is what makes the film unmistakably this brand's. 3. **One accent with one meaning.** The accent is a single token that means one thing, such as "now", "new" or "yours". Use it sparingly (about ≤ 8% of pixels) and let it flood the frame at most once. *Why:* a colour that means something is read without words, and a colour used everywhere means nothing. 4. **One house motion system.** Use a few named curves and springs, each for a stated reason, and take every frame number from `timeline.ts`. *Why:* consistent motion *is* brand motion, and ad-hoc eases read as generated. 5. **Verify by measurement.** A film is done only when the rendered pixels and the decoded audio pass the scripts and one round of critique. *Why:* Studio playback hides pops, ghost frames, sync slips and colour shifts that the encoded file will show. ## 3. Workflow Every step writes a file, and every gate is a check you actually run. Work inline. Subagents are for critique only (§8), because building frames in parallel costs more time than it saves. ### Step 0: Intake → `BRIEF.md` - If the brief already states the product, the message and the length, infer everything else and write your assumptions down. - If it doesn't, ask at most 3 questions: the product in one line, the format and length, and where the film will be shown. Take everything else from §1. - Choose the engine: - Remotion by default. - HyperFrames if the user already has a HyperFrames project, wants HTML/GSAP, or needs `--batch` renders driven by variables. - Copy the hard bans (above) into `BRIEF.md`, plus any brand-supplied exceptions. Critics are later prompted with this file word for word, so it doubles as the QA contract. - Scaffold the project: `bash <skill>/scripts/new-film.sh films/<name> --fps 60 --bpm 120 --size 1920x1080 [--engine hyperframes]`. Pass `--link-modules <dir>/node_modules` to reuse an existing install instead of running `npm install`. - **Gate:** `BRIEF.md` has a spec line, for example `1920x1080@60, 30s, 120BPM, audio: synthesized`. ### Step 1: Concept → `TREATMENT.md` Read `references/concept-and-story.md` now. - Start from specifics, not from style. Write down: - what the name means or evokes (it often hands you the mark and the device); - the feature's non-obvious behaviour, finishing the sentence "unlike the obvious version, it…"; - the product's own objects (its rows, cards, readings and states). - Write 3 concepts, each through a different lens: - (a) the product's own verb or metaphor made literal; - (b) the viewer's pain made visible; - (c) a formal device: a relay object, a bookend, one unbroken camera move, or a container that becomes the product. - Throw out any concept whose props could appear in another product's film. It isn't yours. - Fill in `assets/TREATMENT.md` for the concept you chose: - a logline; - the arc: hook (inside the problem, felt by 1 s) → turn → proof (1–2 capabilities) → promise → lockup; - the device path, shot by shot; - a beat sheet with the columns bar | time | picture | copy | sound; - the full copy with its word count; - the final frame. - Run the deletion test. Remove the demo beats, and the value should still read. Remove the value beats; if the film still "works", it was a feature tour. - Run the specificity test. Would the film be just as true of a simpler product, for example an even split instead of an itemised one, or a plain list instead of a ranked one? If yes, the proof undersells the product; show the part that is hard. - Run the feature-word test. Watching muted, would a stranger use the brief's word for the feature ("streak", "split")? If a clever device makes it read as something else, keep the feature's familiar form and let the device dress it. - **Gate:** - the logline is ≤ 15 words; - the specificity test passes, with its answer written down; - the word count is inside the §1 budget; - no line is longer than 5 words, and no shot has more than 2 lines; - the device appears in every beat row. ### Step 2: Brand and style frames → `src/brand/` Read `references/brand-and-color.md` and the type section of `references/copy-and-type.md`. - The starter's palette, fonts, mark and demo name are stand-ins marked `// cinetic:placeholder`, and `lint-film.mjs` reports an error until every marker is gone. Apply the user's brand, or invent one for this film, then delete the markers. A film that keeps the starter's look looks like every other film made from it. - **Personality first.** Write three adjectives for the brand, then derive the choices from them. This mapping is in `references/brand-and-color.md` §2: - the typeface: pick the sans for this brand from `@fontsource-variable/*` and vendor it with `node scripts/add-font.mjs <name>` (safe with a shared `node_modules`); Geist is only the starter's stand-in; - weight and case; - the stage (light or dark: a dev tool or a fire-named brand often wants dark), neutral or cool, and the accent's hue from the allowed families; - the motion character, from crisp to unhurried. A calm notes app and a fast CI tool should not share a look. - Write `src/brand/tokens.ts` (`python3 scripts/palette.py --accent '#…' --stage dark` builds the neutrals, checks contrast and refuses a banned hue): - colours: an ink, a paper, 2–4 neutrals, and one accent with its meaning in a comment; - type: one family at 2 weights, plus a mono if you need one; - a type scale; - one tracking value per role. - **Explore the mark before you commit to one.** - Sketch 6–10 directions, each from a different source: the name's meaning, a letterform, the product's own object, the idea's metaphor, and a pure geometric construction. - Render them together on one sheet and look at it (the `MarkSheet` still in `references/brand-and-color.md` §4). - Reject any direction that could belong to ten other startups, including the "geometric block + accent dot" family, which is this skill's own example vocabulary. - Run the misread test. Show the mark at 64 px for half a second. If it reads first as a common symbol (a minus, an emoticon, a menu or hamburger icon, a padlock, a play button, a plus), reject it or change it until it doesn't. - Build the winner in `src/brand/Mark.tsx` on a 100-unit grid, with gaps of at least 8 units so it survives being scaled down. - **A palette with character, inside the bans.** Derive it from the world of the name and the product (a hillside gives pine, moss and slate; a foundry gives charcoal, soot and a glowing red), not from framework defaults. When the name's world is heat or fire, orange is banned, so go red-hot (a deep red glowing on a true charcoal) or white-hot, never generic dev-tool blue: the colour must carry the name. A blue-grey near-black stage is the stock dev-tool dark theme (`palette.py` notes it), and in a dev tool red UI tags read as errors; spend the red on the brand's own thing. - Framework blues (the `#3B82F6` / `#2563EB` family) and flat pure greys read as "default". - Tint the neutrals toward the world, with a cool green-grey or a blue slate; a dark stage can be pine-black or ink-navy rather than `#000`. - `references/brand-and-color.md` §8–10 has worked palettes. - **Set the lockup like a typographer.** Render three settings side by side (mark-to-cap ratio, gap, weight, tracking) and pick the one where the mark and the word read as one object. A carelessly set wordmark costs more than any animation gains. - Render 2–4 one-frame style stills from the `Stills` folder and look at them: the mark at 16 px and at full size, one statement frame, and one product frame. `npm run stills` renders the mark stills; add your own with `npx remotion still <StillId> out/stills/<name>.png`. - **Gate:** - the stills pass §4; - the mark sheet and the chosen direction's reason are in `TREATMENT.md`; - `node scripts/lint-film.mjs src` reports no placeholder and no colour or font that is not a token. ### Step 3: Timeline → `src/timeline.ts` Read `references/timing-grid.md` now. - Choose BPM and fps so that a beat is a whole number of frames (see §5). - Map the beat sheet onto bars: - `ACT` holds contiguous, bar-aligned acts; - `CUE` holds named frames that sit on the grid; - `COPY` holds `{id, text, in, resolved, out}` for every line; - `TOTAL` includes a tail of at least 60 f. - Give each bar one motion peak. - **Gate:** `npx tsx scripts/grid-check.ts src/timeline.ts` passes (`npm run check` runs it together with `tsc` and the lint). It checks that every cue is on the 16th grid (or carries an `offgrid:` reason), that text holds are long enough, that no gap without an event runs past 48 f, and that the word count is within budget. ### Step 4: Build, act by act → `src/acts/` Before you write motion, read `references/motion-tokens.md`, `references/camera.md`, `references/transitions.md`, and `references/product-ui.md` if the product appears. Keep `references/chromium-rendering.md` open while you debug. - Make each act a pure function of `useCurrentFrame()`. Mount one `<Sequence>` per act in `Film.tsx`, and register each act as its own composition in the `Acts` folder so you can iterate on it alone. - Take all motion from the tokens in `src/lib/anim.ts` (§6). A raw bezier inside an act is a lint error, because that is how a house style decays. - Build the product UI from real components fed by one `data.ts` module with asserts on dates, weekdays, counts, plurals and sums. The data must agree with the story too: the person who paid doesn't owe, a "sorted" list is actually sorted, a stated ratio matches its numbers, and no number appears twice in one frame. Frame the UI large enough to read on a phone. A screenshot never carries the hero shot. - Make the product and the feature identifiable. Name the feature once, as a UI label, the one line of copy or the end card, and show enough real app chrome that a stranger knows this is software. "No feature name as a headline" never means "never name it". A feature label is not a payoff: land the value with one short line that makes it human ("Sam had the salad."), even in a muted loop. - Frame only the meaningful part of the product. No half-empty grids, no tables cropped at the frame edge, no rows of blank cells: they read as a spreadsheet, not a product. - Text that must be read stays readable in motion. Keep labelled chips and numbers under about 20 px/f while they travel, or fly them with the text faded and let it resolve on landing, because motion blur on small text reads as a double image. - Moving elements never cover text they pass over: plan the paths and the z-order, and check the densest frames at full size. - A progressive text reveal (letter by letter or with a sweep) must never spell a different word partway through ("tarn" briefly reading "tar"). Check the intermediate frames, or reveal by whole words or with a mask. - Export from its act every frame the sound needs, as a named constant (for example `LANDINGS` or `SNAP`), so the cue export can import it. - Wrap everything in `<FontGate>`. - Iterate each act in this loop: 1. Render stills at each cue −2, 0 and +2. 2. Make an act contact sheet: `python3 scripts/sheet.py --comp Act2 --every 2 --out out/qa/act2.png` renders the act and tiles it with frame and time labels. Use `--every 2` for fast sections. 3. Run `bash scripts/layout-audit.sh Act2 --cues`. - **Gate:** - `lint-film.mjs` is clean; - `layout-audit` reports 0 safe-area or overlap violations, and no readable text faster than 20 px/f; - every act sheet has written review notes. ### Step 5: Sound → `public/audio/soundtrack.wav` Read `references/sound.md` now. - Run `npx tsx scripts/export-cues.ts`, which writes `out/cues.json`. Sync points are computed from the picture code (spring contact frames, 50% pop frames, velocity peaks, 97% settles) and never typed by hand. Typed sync points landed 8–11 f off in practice. - Pick the sound's personality row in `references/sound.md` §5.5a first. A calm brand gets soft mallets and one gentle chord; drops onto silence and sub booms are for energetic launch films only. - **Make the music drive the picture, whatever the personality.** - A motif that follows the story's progress, for example one tuned note per step climbing the scale (`progress` in `score.json`). - An accent under every major visual event. - The lockup is the biggest, most resolved musical moment of the film: softer for a calm brand, but still a resolved chord that blooms, never a held pad under the payoff. - The sound starts on frame 0 without a click and never leaves a gap of dead air in the first bars. - Fill in `audio/score.json`: key, one chord per bar, sections, drops and silences. - Run `python3 scripts/audio/score.py --cues out/cues.json --score audio/score.json --out public/audio/soundtrack.wav --stems out/stems --json out/qa/score.json` (`npm run audio`). The stems let `av-audit.py` check each sound against its cue; the master chain lives in `scripts/audio/master.py`. - **Gate:** - the WAV measures its target ±0.5 LUFS integrated (`master.lufs` in `audio/score.json`: −14, or −16 for a calm brand or a short sting), with true peak ≤ −1.5 dBTP before encoding; - a film of 20 s or more has contrast: LRA 5–8 LU, and the payoff 2–3 LU above the median momentary loudness (`score.py` warns); - every event has a sound, and every sound has something visible that causes it, at a loudness that matches the size of that cause (a caret blink whispers; the landing mark hits). ### Step 6: Render and finish → `out/film.mp4` Read `references/finishing.md` now. - **Preview:** `bash scripts/render.sh Film out/preview.mp4 --preview --audio public/audio/soundtrack.wav`. Remotion renders the picture muted and BT.709-tagged, and ffmpeg muxes the audio. Iterate and critique on previews only. - **Master:** if anything moves faster than 12 px/f (true of almost every launch film), `bash scripts/render.sh Film out/film.mp4 --blur`: sharp render → speed measurement → `FilmSub` sub-frame render → float accumulation → mux → sync check. Otherwise, with no flag, `render.sh` renders a sharp master at CRF 14. Silent deliverables such as loops take `--no-audio`. - **Blur costs render time, so spend it once.** - Render the blurred master once, at the end, after the last critique round. It prints the sub-frame multiple and an estimate before it starts; on 4 CPUs a 10 s film at 60 fps and 6× takes about 7 minutes on simple frames and 10–15 on dense UI. `--budget 6` caps it. - A late fix re-renders only the changed act's range (`--frames A-B`) and splices it, rather than re-blurring the film. - A 9:16 or 1:1 variant with identical timing reuses the master's samples (`--samples-from`); one whose fastest motion is ≤ 12 px/f renders sharp. - Don't edit `src/` while a render runs: `render.sh` renders from a bundle frozen at its start and warns if the source changed meanwhile. - Stop a render by its own PID, never with a `pkill -f` pattern: on a shared machine the pattern also kills other people's renders. - **Speed ceiling.** Moves over about 80 px/f are listed as too fast for clean blur; redesign them rather than adding samples (§6). - **Gate.** `render.sh` runs both checks below and exits 1 if either fails. Run them again on any file you deliver: - `python3 scripts/probe.py out/film.mp4 --spec 1920x1080@60 --dur <s>` passes: size, fps, duration ±1 f, yuv420p, BT.709 tags, AAC at 48 kHz; - `python3 scripts/check-sync.py out/film.mp4 public/audio/soundtrack.wav` reports a lag of ≤ 48 samples and true peak ≤ −1 dBTP after decoding. ### Step 7: Review loop