Skip to content

Commit d4bd291

Browse files
committed
docs(prompting): add per-rule A/B demos and the worker-boundary determinism caveat
1 parent 1f4d00e commit d4bd291

2 files changed

Lines changed: 49 additions & 0 deletions

File tree

‎docs/prompting/motion.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,51 @@ If a movement is doing none of those, it's decoration, and decoration is what ma
2323
7. **Match pacing to genre.** Showreel-style cuts run 1.5-4 seconds per idea; a stretched 8-second version of a 2-second idea feels slow no matter how it's animated.
2424
8. **Handmade imperfection stays reproducible.** A stop-motion or hand-animated feel wants irregular timing, not machine-smooth eases — but true unseeded randomness breaks the render: HyperFrames must produce the identical frame every time it seeks to the same point, and `Math.random()` can't promise that. Seed a PRNG once at composition start instead, and step discrete elements between held positions (a "two-frame hold": land, hold two frames, jump to the next offset) rather than tweening continuously between them. The irregularity is real — it just comes from a seed, not from chance.
2525

26+
27+
## Each rule, shown
28+
29+
One A/B per rule. Both halves of every clip run the same content, palette, layout and timing — the only thing that differs is the rule itself, so what you see is the rule and nothing else.
30+
31+
**Rule 1 — Nothing ever fully stops**
32+
33+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule1-nothing-stops.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
34+
*Left `WITHOUT`, right `WITH` — the left half is genuinely frozen after it lands; the right carries a breathing scale, a background drift, and a creeping sheen.*
35+
36+
**Rule 2 — The camera is an actor**
37+
38+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule2-camera-actor.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
39+
*Left `WITHOUT`, right `WITH` — identical cards; the left frame is locked, the right travels 31px of continuous, never-settling push and drift with the grid parallaxing behind it.*
40+
41+
**Rule 3 — Overlapping action**
42+
43+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule3-overlapping-action.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
44+
*Left `WITHOUT`, right `WITH` — two takes. First the simultaneous block, then the queue — offsets longer than the animations. The right runs the same wave both times: offset 0.12s against a 0.48s duration, so four chips are in motion at once instead of one.*
45+
46+
**Rule 4 — Compound properties only when they tell one story**
47+
48+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule4-compound-properties.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
49+
*Left `WITHOUT`, right `WITH` — the same sheet travels the same 470px in the same 1.12s on both sides. The left also rotates 12°; the right fades instead — one property that agrees with the rise.*
50+
51+
**Rule 5 — Overshoot and follow-through**
52+
53+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule5-overshoot.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
54+
*Left `WITHOUT`, right `WITH` — the left arrives at its exact target and stops. The right passes it and settles back, the chip further than the title. Neither numeral ever overshoots its value.*
55+
56+
**Rule 6 — Depth planes**
57+
58+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule6-depth-planes.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
59+
*Left `WITHOUT`, right `WITH` — the left moves every layer at one rate with no blur. The right runs three rates — background, content, and a heavily-blurred foreground drifting ten times faster than the grid.*
60+
61+
**Rule 7 — Match pacing to genre**
62+
63+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule7-pacing.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
64+
*Left `WITHOUT`, right `WITH` — the same three ideas. The left spends 2.0s each and consumes all six seconds; the right spends 1.3s each, finishes at 3.9s, and holds the rest on a live idle.*
65+
66+
**Rule 8 — Handmade imperfection stays reproducible**
67+
68+
<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-rule8-seeded-handmade.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
69+
*Left `WITHOUT`, right `WITH` — the same seeded sway sampled two ways. The left tweens smoothly; the right holds every position for exactly two frames — note the frame counter advancing in evens.*
70+
2671
## The grammar, measured
2772

2873
The same composition built twice — identical content, identical layout; the only variable is the motion treatment. The first build commits the anti-patterns above: simultaneous identical entrances, no camera, a frozen final 2.4 seconds. The second applies the eight rules.

‎docs/prompting/rules-and-anti-patterns.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ Elements that start hidden need their visible end state stated explicitly — a
3434

3535
- **A `fromTo` shows its from-state *before* it starts.** `immediateRender` back-renders the `from` vars at every time earlier than the tween's own start, so an element you authored to "appear at 3s" is already on screen at frame 0 wearing its start pose. Sequential preview hides this — you scrub past frame 0 before the tween exists. Ask for `to()` plus `keyframes`, or a zero-duration `tl.set()` at the beat boundary, whenever an element must be absent before its cue. (Surfaced while validating this guide's kinetic-quote and map-route examples.)
3636

37+
<Note>
38+
**One caveat on "identical every time": parallel workers are not bit-identical to each other.** Building this chapter's rule-1 demo — whose left half is deliberately frozen — a default multi-worker render produced four distinct frame hashes across those frozen frames instead of one, with the changes landing exactly on the 30-frame worker-chunk boundaries. The deltas were a handful of ±1-level pixels (109–113 dB), i.e. per-Chrome-process rasterization variance, not animation. Determinism in the sense that matters is intact: the same worker seeking the same time renders the same frame, and your composition is not the variable. But if you need a *bit-exact* result — hashing frames, proving a hold, diffing two renders — pass `--workers 1`. Encoding adds its own noise on top, so compare lossless frames rather than the encoded MP4 when you need certainty.
39+
</Note>
40+
3741
### Seek-order safety
3842

3943
These four all come from the same root cause: a cold render worker seeks non-linearly, so anything whose value depends on *when* or *in what order* it runs can render differently than the live preview did.

0 commit comments

Comments
 (0)