Skip to content

AbubakrChan/product-launch-motion / legacy

product-launch-motion-v1

Verified

Legacy v1 (voiceover-led, GSAP + HyperFrames). Use when making, directing or rescuing a product launch video, promo, teaser, demo reel, sizzle, feature-announcement film or animated product explainer built from code — and when an existing one looks basic, reads as a slideshow, has reveals that miss the voiceover, an invisible cursor, an inaudible sound effect, a clipped or too-quiet mix, or every video coming out looking the same. Covers SaaS, apps, hardware, e-commerce, dev tools, services. Keywords include motion design, storyboard, voiceover sync, kinetic typography, GSAP, HyperFrames, Remotion, film grain, LUFS, ffmpeg.

FileKindSize
CASE-STUDY.mdmarkdown12.8 KB
SKILL.mdskill md17.4 KB
assets/BRIEF.mdmarkdown3.0 KB
assets/STORYBOARD.mdmarkdown2.7 KB
assets/cues.example.jsonconfig3.2 KB
assets/film.example.jsonconfig3.4 KB
assets/frame-skeleton.htmlother17.3 KB
evals/BASELINE.mdmarkdown7.5 KB
evals/evals.jsonconfig5.3 KB
film-preview.webpbinary975.7 KB
references/01-renderer-contract.mdmarkdown14.8 KB
references/02-story-and-truth.mdmarkdown20.7 KB
references/03-word-locked-sync.mdmarkdown9.2 KB
references/04-motion-grammar.mdmarkdown19.6 KB
references/05-camera-3d-cursor.mdmarkdown12.4 KB
references/06-look-and-grade.mdmarkdown18.3 KB
references/07-sound-and-master.mdmarkdown10.3 KB
references/08-qa-and-direction.mdmarkdown11.7 KB
references/09-shot-catalog.mdmarkdown38.9 KB
references/10-traps.mdmarkdown14.6 KB
references/11-creative-direction.mdmarkdown17.4 KB
references/12-deliverables.mdmarkdown7.1 KB
scripts/assemble.mjsexecutablescript9.3 KB
scripts/level-sfx.mjsexecutablescript8.5 KB
scripts/master.shexecutablescript3.8 KB
scripts/transitions.mjsexecutablescript7.2 KB
scripts/verify-cue.shexecutablescript3.4 KB
scripts/wire-audio.mjsexecutablescript5.3 KB
scripts/wire-grade.mjsexecutablescript9.7 KB
scripts/word-timings.mjsexecutablescript4.6 KB
still-1.jpgbinary16.9 KB

references/03-word-locked-sync.md

View on GitHub
# Word-locked sync

Owns Law 2. This is the difference between animation that illustrates narration and
animation that merely accompanies it.

The rule: **every reveal is cued to the measured start time of the word it illustrates.**
Not to a beat grid, not to a stopwatch estimate, not to "roughly when he says it" — to a
word-level transcript of the actual voiceover file you are shipping.

Viewers cannot articulate this, but they feel it instantly. A chip that appears 200ms
after the word that names it reads as lag. The same chip on the word reads as the voice
causing it.

## Contents

- [Voiceover first](#voiceover-first)
- [Getting word timings](#getting-word-timings)
- [The cue table](#the-cue-table)
- [Cueing in practice](#cueing-in-practice)
- [Deriving frame durations](#deriving-frame-durations)
- [Pacing and holds](#pacing-and-holds)
- [Re-cutting the narration](#re-cutting-the-narration)
- [Choosing a voice](#choosing-a-voice)

## Voiceover first

Render or record the voiceover **before building a single frame.** Frame durations are
derived from real narration length; if you build to estimates you will rebuild every
timeline when the real audio comes in half a second longer.

This inverts the instinct to storyboard visually first. Storyboard the *shots* first, yes —
but the moment you need a number, that number comes from the wav.

Order of operations:

1. Write the script (`references/02-story-and-truth.md`)
2. Render one audio file per narration line
3. Transcribe with word-level timestamps
4. Derive each frame's duration from its line's length, plus a tail hold
5. Only now, build frames

## Getting word timings

Any transcriber that returns word-level timestamps works. Whisper locally is the usual
choice because it is free, offline and accurate enough:

```bash
whisper assets/voice/01.wav --model small --word_timestamps True --output_format json
```

Normalise whatever you get into one table the frames can read:

```bash
node scripts/word-timings.mjs --transcript transcript.json --out audio_meta.json
```

```json
{
  "01-hook": {
    "duration": 4.02,
    "words": [
      { "w": "Find",   "start": 0.11, "end": 0.42 },
      { "w": "the",    "start": 0.42, "end": 0.55 },
      { "w": "creators","start": 0.55, "end": 1.08 }
    ]
  }
}
```

Two practical notes:

- **Timings are per frame, frame-relative.** A cue inside a frame is expressed relative to
  that frame's start, so re-ordering frames does not invalidate the cues.
- **Spot-check the first and last word of every line.** Transcribers clip leading
  consonants and occasionally merge two short words; a wrong start on the first word
  offsets an entire shot.

## The cue table

Write the timings you actually use into a comment table at the top of the frame, then cue
against it. This is the artefact that makes a frame reviewable — a reader can check the
sync without opening an audio editor.

```js
/* VO: "It searches three hundred and fifty million creators and finds the contact."
   "searches"@0.16  "350"@0.77  "million"@1.47  "creators"@2.02
   "and"@2.68  "finds"@2.84  "the"@3.15  "contact."@3.33                        */

tl.to(glow, { opacity: 1, duration: 0.22, ease: "power2.out" }, 0.16);   // "searches"
tl.to(count, { opacity: 1, duration: 0.22, ease: "power2.out" }, 2.02);  // "creators"
click(1, 2.84);                                                          // "finds"
```

Every cue carries the word in a trailing comment. When someone later asks "why 2.84?", the
answer is in the file.

## Cueing in practice

**Cue the meaning, not the noun.** The word to lock to is the one that makes the visual
make sense — usually a verb or the emphasis word, not the subject.

**Lead by a hair when the eye needs travel time.** An element that must be *read* can start
0.02–0.06s early so that it is legible on the word. An element that is a *hit* (a click, a
state flip, a stat landing) fires exactly on the word.

**Lead the travel, land the beat.** A cursor crossing a card needs 0.2–0.3s of eased
travel. Start the move early; put the *click* on the word. The word-locked event is the
one the viewer connects to the sentence.

**Count-ups start on the word that names them and finish before the next clause.** A
counter still spinning while the voice has moved on reads as a stall.

**Weight reveals to the back half of a shot.** At t=0 a frame carries only what the voice is
saying at t=0. Everything else arrives as it is spoken. This single habit is what stops a
shot from being a slide that fades in complete.

**One beat can carry two cues, never three.** If three things must land on one word, you
have a storyboard problem, not a timing problem.

## Deriving frame durations

```
frame duration = narration length + tail hold + transition pad
```

The tail hold is the breath after the line — 0.2–0.5s, longer before a hero beat because
silence is what makes the next hit land (`references/07-sound-and-master.md`). The
transition pad is whatever the outgoing transition needs to overlap the next frame.

Set the root's `data-duration` and every timed child to the same padded value. Mismatched
durations between a frame root and its clips is a common source of a frame that goes blank
just before the cut.

## Pacing and holds

Pace is a direction note, not a constant. The reference film was re-cut 10% faster after a
first pass that dragged, and then given tail holds after a second pass that was too
clipped — the final film is *faster in the clauses and slower at the ends* than either.

Practical guidance:

- If the voice finishes a clause and the visuals are still resolving, the shot is too slow.
- If a shot cuts within ~0.2s of its last motion, it is too fast — the viewer has no time
  to read the state you just built.
- Put a genuine breather on either side of the busiest stretch. Two consecutive dense
  product shots exhaust an audience faster than one long one.

## Re-cutting the narration

If you speed up or re-render the VO, **every cue in the film is now wrong.** Two options:

1. Re-transcribe and re-derive all timings (correct, and what you should do).
2. If you applied a uniform tempo change (`atempo=1.1`), rescale the existing word table by
   the same factor (`start / 1.1`) — valid only for a uniform change, and worth
   spot-checking against the new wav at three points before trusting it.

Changing voice, speaker or model is never a uniform change. Re-transcribe.

## When there is no voiceover

A silent film is a legitimate and often correct choice — feed placements autoplay muted, and
a narrated skincare film is the category default you may want to break. But Law 2 as written
assumes words to lock to, and "cue to a beat grid instead" is exactly what it forbids. So
the law generalises rather than lapses:

> **Every reveal is cued to the thing that motivates it.** With narration, that is the word.
> Without narration, it is a physical event or the moment a viewer has finished reading.

Three sources of truth replace the transcript:

1. **Sound-design events.** If the film is sound-led, the cue grid is the SFX transients, and
   you build it the other way round: place the sound events first, measure their onsets
   exactly as you would words (`volumedetect` in 100ms slices, or read them off the asset),
   and cue the visuals to those. The discipline is identical — measured onsets, never
   estimates.
2. **Reading time.** A title card cannot be cued; it must be *held*. Budget a minimum of
   ~0.35s per word plus 0.3s of settle, never less than 1.2s for any card, and longer for a
   card carrying a number. Read it aloud at a natural pace and time yourself — if you can
   finish comfortably, a viewer can.
3. **The action itself.** In a demonstration, the motivating event is on screen: the lid
   lifts, the row resolves, the value lands. Cue everything else to that.

Two things do not change. Durations still come from measured content rather than estimates —
you are measuring reading time and sound onsets instead of speech. And nothing is arbitrary:
if you cannot say what a reveal is cued *to*, it is cued to nothing, which is the definition
of a slideshow.

## Choosing a voice

| Option | Cost | Trade-off |
|---|---|---|
| **Local neural TTS** (e.g. Kokoro-82M) | Free, offline, CPU | Fully deterministic and re-runnable, but audibly synthetic — acceptable for internal and iterative work, noticeable on a public launch |
| **Commercial TTS** | Per-character | Best quality-per-effort for a public film; pin the voice and model version, because a model update will change your timings |
| **Human recording** | Time or money | Still the best, and the only option that can carry irony. Record before the storyboard is fixed, not after |

Whichever you choose, the pipeline is identical: a wav plus word timings. That is the whole
interface, which is what makes the voice swappable at all.

One caveat learned the hard way: some TTS drivers silently ignore a `--speed` flag. If
tempo matters, verify the output length rather than trusting the parameter, and apply tempo
changes with ffmpeg (`atempo`) where you can measure them.

## Related

- `references/02-story-and-truth.md` — writing the script the voice will read
- `references/04-motion-grammar.md` — how long a cued entrance should take
- `references/07-sound-and-master.md` — SFX cues on the same word grid
- `scripts/word-timings.mjs` — transcript → cue table
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall