Skip to content

Text to motion graphics for Claude Code and Codex: write a brief, get a checked MP4. 30 art forms from claymation and paper cut-out to anime and pixel art, 2D explainers, Shorts, 3D products. Installs brief2motion for websites. MIT.

feat: brief2mp4 0.1.0, a brief-to-MP4 motion skill for Claude Code and Codex

Varun Pratap Bhardwaj4b17df4eca6e
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c9da8d3
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,10 @@
+.DS_Store
+*.mp4
+*.mov
+*.wav
+frames/
+checks/
+renders/
+node_modules/
+__pycache__/
+*.pyc
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f962d47
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Varun Pratap Bhardwaj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..07ff846
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# brief2mp4
+
+A free skill that teaches Claude Code and Codex to turn a written brief into a finished, checked MP4: kinetic type, 3D scenes, product shots. MIT licensed. No account, no paywall.
+
+```bash
+git clone https://github.com/qualixar/brief2mp4.git && bash brief2mp4/install.sh
+```
+
+That installs the skill into `~/.claude/skills/brief2mp4` and `~/.codex/skills/brief2mp4`. Start a new session in either app and ask:
+
+> Use the brief2mp4 skill to make the video in this brief: *(paste one of the briefs below)*
+
+When it says it is done, send one follow-up:
+
+> Check it against the brief.
+
+The skill treats that as an instruction to re-read your original brief line by line, show the evidence for each line, fix what fails, and render again.
+
+## What it does
+
+The skill gives the agent one working loop and the tools to run it:
+
+1. **Spec.** Before writing code it writes `SPEC.md`: the delivery spec (size, frame rate, exact duration, codecs, loudness), every on-screen word copied exactly, the palette, a beat sheet with times, and a "done when" checklist with one checkable line per requirement.
+2. **Build.** It picks the right tool for the brief and starts from a template that already renders.
+3. **Self-check.** It measures the file (`check_delivery.sh`), pulls stills at the important moments (`contact_sheet.sh`), looks at them, and marks every checklist line met or not met with evidence.
+4. **Fix.** It fixes the worst miss first and re-renders, up to three rounds.
+5. **Deliver.** `final.mp4` plus a `REPORT.md` that says what was checked, how, and what is still open.
+
+| The brief asks for | The skill uses |
+|---|---|
+| Type, layouts, UI, charts, 2D motion | [HyperFrames](https://github.com/heygen-com/hyperframes) (HTML + CSS + GSAP to MP4) |
+| Stylised 3D, particles, camera moves | [Three.js](https://threejs.org) inside HyperFrames, driven by the timeline so every frame is repeatable |
+| Realistic products, materials, soft light | [Blender](https://www.blender.org), scripted in Python and rendered without opening a window |
+| Sound, joins, exact length, loudness, encoding | [ffmpeg](https://ffmpeg.org) |
+
+## Try it: three example briefs
+
+| Brief | Tool | Length |
+|---|---|---|
+| [01 kinetic type](examples/01-kinetic-type/BRIEF.md): "Finish something today" | HyperFrames | 12 s |
+| [02 Three.js](examples/02-threejs-orbit/BRIEF.md): a low-poly planet, three moons, "ORBIT" | Three.js | 10 s |
+| [03 Blender](examples/03-blender-product/BRIEF.md): a smart-speaker turntable, "LISTEN." | Blender | 8 s |
+
+Copy a brief, paste it after the request above, and let it run. Then write your own: say how long, what size, which colours, the exact words, and what should happen when. The more of that you write down, the less the agent has to guess.
+
+## Requirements
+
+- Claude Code or Codex (desktop app or CLI)
+- Node.js 22 or newer and ffmpeg, for every brief
+- Blender, only for Blender briefs (tested with 5.2; 4.2 or newer should work)
+
+The installer checks these and tells you what is missing. HyperFrames runs through `npx`, so there is nothing else to install.
+
+## What is inside
+
+```
+skill/brief2mp4/
+ SKILL.md the loop the agent follows
+ references/ HyperFrames, Three.js, Blender, ffmpeg notes
+ scripts/
+ finish.sh any render -> delivery MP4 (exact length, H.264/AAC, -14 LUFS)
+ check_delivery.sh PASS/WARN/FAIL against the delivery spec
+ contact_sheet.sh stills at chosen moments, plus a grid
+ sound_bed.sh a quiet original placeholder soundtrack
+ templates/
+ SPEC.md the spec the agent fills in
+ threejs/index.html a Three.js scene that renders frame by frame
+ blender/scene.py a scripted Blender turntable
+examples/ three briefs
+install.sh install, update or remove
+```
+
+The scripts also work on their own, for any video:
+
+```bash
+bash ~/.claude/skills/brief2mp4/scripts/check_delivery.sh my-video.mp4 --seconds 30
+```
+
+## Update or remove
+
+```bash
+cd brief2mp4 && git pull && bash install.sh # update
+bash brief2mp4/install.sh --uninstall # remove from both apps
+bash brief2mp4/install.sh --claude # only Claude Code (or --codex)
+```
+
+The installer only replaces or removes a folder it created itself. If you already had a folder called `brief2mp4` in your skills, it is moved aside with a timestamp, never deleted.
+
+## Licence
+
+MIT. Use it, change it, ship videos with it. HyperFrames (Apache-2.0), Three.js (MIT), GSAP, Blender (GPL) and ffmpeg (LGPL/GPL) keep their own licences; this repo does not bundle them.
diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..6e8bf73
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+0.1.0
diff --git a/examples/01-kinetic-type/BRIEF.md b/examples/01-kinetic-type/BRIEF.md
new file mode 100644
index 0000000..ab6bfc5
--- /dev/null
+++ b/examples/01-kinetic-type/BRIEF.md
@@ -0,0 +1,15 @@
+# Brief 01: kinetic type, "Finish something today"
+
+Make a 12-second kinetic typography video.
+
+- Delivery: final.mp4, 1920x1080, 30 fps, exactly 12.0 s, H.264 + AAC.
+- Background: warm paper #F2EDE4. Text: ink #16130F. Accent: signal orange #FF5A1F. Typeface: Space Grotesk (Google Fonts), bold.
+- Three lines, in this order, each one replacing the last:
+ 1. 0.3-3.5 s: "Ideas are cheap."
+ 2. 3.5-7.0 s: "Finished is rare."
+ 3. 7.0-12.0 s: "Finish something today."
+- Every word arrives with a masked rise, one word at a time.
+- An orange bar wipes across the frame between lines (at 3.5 s and 7.0 s). After the last wipe it shrinks into an underline under the word "today."
+- The last line is the hero: it lands by 8.0 s and holds still and fully readable until 12.0 s.
+- Sound: a quiet soundtrack with a low accent on each wipe (3.5 s and 7.0 s).
+- Text never touches the frame edge. Headlines at least 120 px tall.
diff --git a/examples/02-threejs-orbit/BRIEF.md b/examples/02-threejs-orbit/BRIEF.md
new file mode 100644
index 0000000..fb5a18f
--- /dev/null
+++ b/examples/02-threejs-orbit/BRIEF.md
@@ -0,0 +1,13 @@
+# Brief 02: Three.js, "ORBIT"
+
+Make a 10-second 3D shot in Three.js.
+
+- Delivery: final.mp4, 1920x1080, 30 fps, exactly 10.0 s, H.264 + AAC.
+- Palette: night sky #14112B, planet coral #FF7A59, moons gold #FFC857, text cream #FFF4E8.
+- A low-poly planet (flat-shaded) with a thin tilted ring, in the centre of the frame.
+- Three small moons orbit the planet at three different speeds and distances. Each one passes in front of the planet at least once.
+- About 1,500 stars, placed with a seeded random generator, so every render is identical.
+- Camera: starts wide and slow-pushes in over the whole shot, with a gentle orbit. One continuous move, no cuts.
+- At 6.5 s the word "ORBIT" rises in from below in HTML text, 140 px, wide letter spacing, below the planet. It holds until the end.
+- Nothing in the frame is cut off at any time, and the planet stays lit on the side facing the camera.
+- Sound: a quiet soundtrack with a low accent at 6.5 s.
diff --git a/examples/03-blender-product/BRIEF.md b/examples/03-blender-product/BRIEF.md
new file mode 100644
index 0000000..c284419
--- /dev/null
+++ b/examples/03-blender-product/BRIEF.md
@@ -0,0 +1,13 @@
+# Brief 03: Blender, "LISTEN."
+
+Make an 8-second product turntable in Blender, built entirely from a Python script and rendered headless.
+
+- Delivery: final.mp4, 1920x1080, 30 fps, exactly 8.0 s, H.264 + AAC.
+- The product: a smart speaker. A tall rounded cylinder with a charcoal fabric look (#2E2B33) and a slightly darker top cap. A thin light ring on the top edge glows amber (#FFB347).
+- Set: the speaker stands on a floor in deep plum (#2A2140) that fades into a background of the same colour. No visible horizon line.
+- Light: a soft key from the front-left, a warm rim light behind on the right, a weak fill. A soft contact shadow under the speaker.
+- Camera: a smooth turntable, 270 degrees over the 8 seconds, slightly above the speaker, looking down a little.
+- The light ring pulses once, brighter, at 5.5 s.
+- At 6.0 s the word "LISTEN." appears above the speaker in cream (#FFF4E8) and holds until the end.
+- Use EEVEE. Render 3 preview stills before the full render and check them.
+- Sound: a quiet soundtrack with a low accent at 5.5 s.
diff --git a/install.sh b/install.sh
new file mode 100755
index 0000000..fe3e58e
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Install the brief2mp4 skill for Claude Code and Codex.
+#
+# bash install.sh # both
+# bash install.sh --claude # Claude Code only
+# bash install.sh --codex # Codex only
+# bash install.sh --uninstall # remove from both
+#
+# Claude Code reads skills from ~/.claude/skills (or $CLAUDE_CONFIG_DIR/skills).
+# Codex reads skills from ~/.codex/skills (or $CODEX_HOME/skills).
+set -euo pipefail
+
+NAME="brief2mp4"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SRC="$HERE/skill/$NAME"
+VERSION="$(cat "$HERE/VERSION" 2>/dev/null || echo dev)"
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"
+CODEX_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
+
+DO_CLAUDE=1 DO_CODEX=1 UNINSTALL=0
+for arg in "$@"; do
+ case "$arg" in
+ --claude) DO_CODEX=0 ;;
+ --codex) DO_CLAUDE=0 ;;
+ --uninstall) UNINSTALL=1 ;;
+ -h|--help) sed -n '2,10p' "$0"; exit 0 ;;
+ *) echo "install.sh: unknown option $arg" >&2; exit 2 ;;
+ esac
+done
+
+[[ -f "$SRC/SKILL.md" ]] || { echo "install.sh: cannot find $SRC/SKILL.md (run it from the repo folder)" >&2; exit 1; }
+
+remove_ours() {
+ # Only ever removes a folder this installer created (it carries our marker file).
+ local dest="$1"
+ [[ -n "$dest" && "$(basename "$dest")" == "$NAME" ]] || return 1
+ if [[ -f "$dest/.installed-by-$NAME" ]]; then
+ rm -r "$dest"
+ return 0
+ fi
+ return 1
+}
+
+install_to() {
+ local base="$1" label="$2" dest="$1/$NAME"
+ mkdir -p "$base"
+ if [[ -e "$dest" ]]; then
+ if ! remove_ours "$dest"; then
+ local backup
+ backup="$dest.backup-$(date +%Y%m%d-%H%M%S)"
+ mv "$dest" "$backup"
+ echo " kept your existing $NAME folder at $backup"
+ fi
+ fi
+ cp -R "$SRC" "$dest"
+ chmod +x "$dest"/scripts/*.sh
+ echo "$VERSION" > "$dest/.installed-by-$NAME"
+ echo " $label: installed to $dest"
+}
+
+uninstall_from() {
+ local dest="$1/$NAME" label="$2"
+ if [[ -e "$dest" ]]; then
+ if remove_ours "$dest"; then echo " $label: removed $dest"
+ else echo " $label: $dest was not installed by this script; left it alone"; fi
+ else
+ echo " $label: nothing to remove"
+ fi
+}
+
+if [[ "$UNINSTALL" == 1 ]]; then
+ echo "Removing $NAME"
+ [[ "$DO_CLAUDE" == 1 ]] && uninstall_from "$CLAUDE_DIR" "Claude Code"
+ [[ "$DO_CODEX" == 1 ]] && uninstall_from "$CODEX_DIR" "Codex"
+ exit 0
+fi
+
+echo "Installing $NAME $VERSION"
+[[ "$DO_CLAUDE" == 1 ]] && install_to "$CLAUDE_DIR" "Claude Code"
+[[ "$DO_CODEX" == 1 ]] && install_to "$CODEX_DIR" "Codex"
+
+echo
+echo "Tools the skill uses:"
+check() {
+ local cmd="$1" why="$2" fix="$3"
+ if command -v "$cmd" >/dev/null 2>&1; then echo " ok $cmd ($why)"
+ else echo " missing $cmd ($why). Install: $fix"; fi
+}
+check node "HyperFrames and Three.js, version 22 or newer" "https://nodejs.org or: brew install node"
+check ffmpeg "finishing and checks, needed for every video" "brew install ffmpeg (Linux: apt install ffmpeg)"
+if command -v blender >/dev/null 2>&1 || [[ -x /Applications/Blender.app/Contents/MacOS/Blender ]]; then
+ echo " ok blender (only for Blender briefs)"
+else
+ echo " missing blender (only for Blender briefs). Install: https://www.blender.org/download or: brew install --cask blender"
+fi
+if command -v node >/dev/null 2>&1; then
+ major="$(node -v | sed 's/^v//; s/\..*//')"
+ [[ "$major" -ge 22 ]] 2>/dev/null || echo " note node $(node -v) is older than 22; HyperFrames needs 22 or newer"
+fi
+
+echo
+echo "Done. Start a new Claude Code or Codex session, then try:"
+echo " Use the $NAME skill to make the video in this brief: <paste a brief from examples/>"
diff --git a/skill/brief2mp4/SKILL.md b/skill/brief2mp4/SKILL.md
new file mode 100644
index 0000000..8056f0b
--- /dev/null
+++ b/skill/brief2mp4/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: brief2mp4
+description: Turn a written brief into a finished, checked MP4 motion graphic. Use when asked to make an animation, motion graphic, kinetic typography, title sequence, logo sting, 3D scene, product turntable or short explainer clip as a video file. Builds with HyperFrames (HTML + GSAP), Three.js or Blender, finishes with ffmpeg, then checks the video against the brief and fixes what fails before handing it over.
+---
+
+# brief2mp4
+
+A brief goes in. `final.mp4` comes out, and for every line of the brief you can point to the frame or the command output that shows the video meets it.
+
+Work in this order every time: **spec, build, self-check, fix, deliver.** Do not skip the self-check. A render that finished is not a video that is right.
+
+## 0. Before you start
+
+Check the tools the job needs and say what is missing:
+
+```bash
+node -v # 22 or newer (HyperFrames and Three.js paths)
+ffmpeg -version # every path
+blender --version # only for the Blender path
+```
+
+On macOS Blender is often not on the PATH: use `/Applications/Blender.app/Contents/MacOS/Blender`. If a tool is missing, tell the user the install command (`brew install node ffmpeg`, `brew install --cask blender`, or the Linux equivalent) and stop, unless the brief allows another tool.
+
+Work inside one project folder. Never write outside it.
+
+The scripts and templates named below sit next to this SKILL.md. Call them by their full path, for example `<this skill's folder>/scripts/finish.sh`; after installing they are in `~/.claude/skills/brief2mp4/` or `~/.codex/skills/brief2mp4/`.
+
+## 1. Spec: write SPEC.md before any code
+
+SPEC.md is the contract you will check against. It has six parts:
+
+1. **Delivery**, as a table. If the brief is silent, use these defaults and say so:
+
+ | Item | Default |
+ |---|---|
+ | File | `final.mp4` in the project root |
+ | Frame | 1920x1080 (16:9). Vertical briefs: 1080x1920 |
+ | Frame rate | 30 fps |
+ | Duration | exactly what the brief says, to the frame |
+ | Video | H.264, yuv420p |
+ | Audio | AAC, 48 kHz, stereo, -14 LUFS integrated, true peak at or below -1 dBTP. Silent only if the brief says silent (still include a silent track) |
+
+2. **Exact text.** Every word that appears on screen, copied character for character from the brief. Spelling, capitals and punctuation are part of the spec.
+3. **Look.** Palette as hex codes, one or two typefaces, background, the mood in five words or fewer.
+4. **Beat sheet.** Time ranges (`0.0-2.0 s`), what is on screen, what moves, and where the one hero moment lands. Something must be visible by 0.3 s. The final message holds for the last 1.5-2.5 s.
+5. **Tool choice** (section 2) and one sentence on why.
+6. **Done when.** One checklist line per requirement in the brief, each one checkable by a command or by looking at a named frame: "`final.mp4` is 12.0 s", "at 9.5 s the words FINISH SOMETHING TODAY are fully on screen, nothing cut off".
+
+If the brief leaves a choice open, make it, write it under **Decisions** in SPEC.md, and continue. Ask the user only when the gap makes the video impossible.
+
+A blank spec to copy is in `templates/SPEC.md`.
+
+## 2. Pick the tool
+
+| The brief asks for | Use | Reference |
+|---|---|---|
+| Type, layouts, UI, charts, icons, 2D shapes, captions | HyperFrames (HTML + CSS + GSAP) | `references/hyperframes.md` |
+| Stylised 3D, particles, many objects, flying cameras | Three.js inside HyperFrames | `references/threejs.md` |
+| Realistic products, materials, soft light and shadows | Blender, scripted with Python, run headless | `references/blender.md` |
+| Joining clips, adding sound, exact duration, loudness, encoding | ffmpeg (`scripts/finish.sh`) | `references/ffmpeg.md` |
+
+Mixing is normal: render a Blender shot to frames, then use it as a video layer under HyperFrames type, or join HyperFrames and Blender clips with ffmpeg. Every path ends with `scripts/finish.sh` and `scripts/check_delivery.sh`.
+
+Starters that already render: `templates/threejs/index.html` and `templates/blender/scene.py`. Copy one into the project and change it, rather than starting from an empty file.
+
+## 3. Build
+
+Rules for every tool:
+
+- **The picture is a pure function of time.** No wall clock, no `Math.random()` (use a seeded generator), no network calls while rendering. Render the same frame twice and you must get the same pixels.
+- **Every element has a job in the beat sheet.** If you cannot say which beat it serves, cut it.
+- **Text is readable.** Body text at least 40 px tall at 1080p, headlines 90 px or more. Keep 5% safe margins (96 px left and right, 54 px top and bottom at 1920x1080). No text touches or crosses the frame edge. Hold any line on screen for at least (words / 3) + 0.5 seconds.
+- **Motion is eased.** Use ease-out for things arriving and ease-in for things leaving; linear only for constant spins and turntables. Most UI moves take 0.3-0.8 s. One clear hero moment beats ten small effects.
+- **Draft small first.** Render 2-3 seconds at draft quality, look at it, then build the rest.
+- **Edit files with your file-editing tool, not `sed -i`.** `sed -i` behaves differently on macOS and Linux and can fail silently; if an edit did not apply, the next render shows the old file.
+
+## 4. Self-check: look before you say done
+
+After every full render, do all three:
+
+1. **Measure.** `scripts/check_delivery.sh final.mp4 --seconds <N> [--size WxH] [--fps N] [--silent-ok]` must end with `RESULT: PASS`. A FAIL is a fix, not a footnote.
+2. **Look.** `scripts/contact_sheet.sh final.mp4 --at <beat starts, hero moment, last second>` writes one PNG per moment. Open and view each image. For every frame ask: is the text spelled exactly as the spec says? Is anything cut off or overlapping? Are the colours from the palette? Is the beat that should be on screen at this time actually there?
+3. **Walk the list.** Go through **Done when** line by line and mark each **met** or **not met**, with the evidence: the command output line, or the frame file name.
+
+If you cannot view images in this environment, say so plainly in the report. Never claim a visual check you did not do.
+
+## 5. Fix
+
+Fix the worst miss first, re-render, and run section 4 again. To save time, re-render only what changed where the tool allows it (`hyperframes render --start/--end`, a Blender frame range). Stop after three fix rounds; if something still fails, deliver and list it honestly.
+
+## 6. Deliver
+
+- `final.mp4` in the project root.
+- `REPORT.md`: the Done-when list with met / not met and evidence, the render settings you used, render time, and anything still open.
+- In chat: the path, the duration, one line on what is in it, and any open issue. Keep it short.
+
+## Render settings
+
+| Path | While iterating | Final |
+|---|---|---|
+| HyperFrames | `npx hyperframes render . -o draft.mp4 --quality draft --workers 4` | `npx hyperframes render . -o render.mp4 --quality delivery --fps 30` |
+| Three.js (in HyperFrames) | same as above; renderer pixel ratio 1, `preserveDrawingBuffer: true` | same as above |
+| Blender | `--preview` (3 stills) with EEVEE, 16-32 samples | EEVEE 32-64 samples; Cycles 64-128 with denoising only when the brief asks for realism. Render PNG frames |
+| ffmpeg finish | n/a | `scripts/finish.sh`: H.264 CRF 18 preset slow, yuv420p, AAC 192k 48 kHz, -14 LUFS, true peak -1.5 dBTP, exact duration |
+
+Run one heavy render at a time. Two renders side by side are slower than two in a row.
+
+## When the user says "check it against the brief"
+
+That message means: re-read the **original brief** (not your spec), go through it line by line, and for each line show the evidence that `final.mp4` meets it. Fix every miss, re-render, run section 4 again, and update REPORT.md. Do this without asking first.
+
+## Files in this skill
+
+- `references/hyperframes.md`: composition rules, commands, audio, sub-compositions, common failures
+- `references/threejs.md`: time-driven 3D, seeded randomness, text over 3D, performance
+- `references/blender.md`: headless Blender, engines, light, camera, text, frames
+- `references/ffmpeg.md`: finishing, joining, overlays, sound, loudness, inspection
+- `scripts/finish.sh`, `scripts/check_delivery.sh`, `scripts/contact_sheet.sh`, `scripts/sound_bed.sh`
+- `templates/SPEC.md`, `templates/threejs/index.html`, `templates/blender/scene.py`
diff --git a/skill/brief2mp4/references/blender.md b/skill/brief2mp4/references/blender.md
new file mode 100644
index 0000000..e53fec8
--- /dev/null
+++ b/skill/brief2mp4/references/blender.md
@@ -0,0 +1,54 @@
+# Blender, scripted and headless
+
+Blender builds and renders 3D from a Python script with no window open. Use it when the brief wants something that should look physically real: a product on a table, glass, metal, ceramic, soft shadows.
+
+Start from `templates/blender/scene.py`. It builds a whole scene from code (floor, product, three lights, a turntable camera, a 3D title that scales in) and renders PNG frames.
+
+## Run it
+
+```bash
+# 3 stills (first, middle, last frame): seconds, not minutes. Do this first.
+blender --background --factory-startup --python scene.py -- --frames-dir frames --preview
+
+# The full shot as numbered PNGs
+blender --background --factory-startup --python scene.py -- --frames-dir frames --seconds 8 --fps 30
+
+# Encode to a delivery MP4
+scripts/finish.sh --in frames --out final.mp4 --seconds 8
+```
+
+Everything after `--` goes to the script. `--factory-startup` ignores the user's own Blender settings so the result is the same on every machine. macOS path if `blender` is not found: `/Applications/Blender.app/Contents/MacOS/Blender`.
+
+Render frames, not a video file, from Blender: a crash at frame 200 keeps frames 1-199, and ffmpeg does the encoding properly.
+
+## Engines
+
+| Engine | Use it for | Settings |
+|---|---|---|
+| EEVEE | Almost everything. Fast, good soft shadows | 32-64 samples |
+| Cycles | When the brief wants realism: glass, caustics, true reflections | 64-128 samples plus denoising; on Apple Silicon try the Metal GPU |
+
+Engine names changed across Blender versions. Set them inside a `try` and fall back (the template does this): EEVEE is `BLENDER_EEVEE` in current releases and was `BLENDER_EEVEE_NEXT` in some 4.x releases.
+
+Measure before you commit to a full render: time the `--preview` run, divide by 3, multiply by the frame count.
+
+## Writing robust scripts
+
+- Find shader nodes by **type**, not name: `next(n for n in mat.node_tree.nodes if n.type == "BSDF_PRINCIPLED")`. Node names are translated in other languages.
+- Colours on the Principled BSDF are linear. Convert hex from sRGB (the template's `hex_rgba` does it), or the palette comes out washed.
+- When you parent one object to another after creating both, set `child.matrix_parent_inverse = parent.matrix_world.inverted()`, or the child jumps.
+- Set `bpy.context.preferences.edit.keyframe_new_interpolation_type` to `"LINEAR"` before keyframing a constant turntable and back to `"BEZIER"` for eased moves.
+- Always build from `read_factory_settings(use_empty=True)` so no default cube or light sneaks in.
+
+## Light, camera, material: a recipe that rarely fails
+
+- **Three area lights:** a large key in front and to one side (about 600 W, size 3 m), a smaller rim behind on the other side in a warm palette colour (about 400 W), a weak broad fill (about 120 W). Point each at the subject.
+- **Background:** a dark world colour from the palette at low strength, and a big floor in a slightly lighter shade so the shadow has something to land on and the horizon disappears.
+- **Camera:** 50 mm lens, a few metres away, a `TRACK_TO` constraint on an empty at the subject's centre. Animate the empty's rotation for a turntable; animate the camera's distance for a push-in. One move per shot.
+- **Materials:** roughness 0.2-0.3 for glazed ceramic and plastic, 0.05 plus metallic 1.0 for polished metal, transmission 1.0 for glass (Cycles for best results).
+- **Title in 3D:** a text object with a little extrude and an emissive material, parented to the camera rig so it always faces the lens. Or skip 3D text and put the title on top in HyperFrames.
+
+## Checks
+
+- Look at the three preview stills before the full render: subject in frame, nothing cut off, the floor horizon invisible, the title readable.
+- After the full render, run `scripts/check_delivery.sh` and `scripts/contact_sheet.sh` on the finished MP4 like any other path.
diff --git a/skill/brief2mp4/references/ffmpeg.md b/skill/brief2mp4/references/ffmpeg.md
new file mode 100644
index 0000000..3747a02
--- /dev/null
+++ b/skill/brief2mp4/references/ffmpeg.md
@@ -0,0 +1,75 @@
+# ffmpeg: finishing, joining, sound, checks
+
+Every path ends here. The renderers make pictures; ffmpeg makes a file that plays everywhere and meets the delivery spec.
+
+## The finish step
+
+```bash
+scripts/finish.sh --in render.mp4 --out final.mp4 --seconds 12 # silent track added
+scripts/finish.sh --in render.mp4 --out final.mp4 --seconds 12 --audio bed.wav
+scripts/finish.sh --in frames/ --out final.mp4 --seconds 8 # a PNG sequence
+scripts/finish.sh --in render.mp4 --out final.mp4 --seconds 12 --keep-audio # keep the render's own sound
+```
+
+It fits the picture to the frame without stretching, forces the frame rate, holds the last frame if the render is short, cuts to the exact duration, encodes H.264 (CRF 18, yuv420p, `+faststart` for web playback) and AAC 48 kHz stereo, and normalises the sound to -14 LUFS with true peak at -1.5 dBTP. Options: `--size 1080x1920`, `--fps 60`, `--lufs -16`, `--crf 16`.
+
+## Check it
+
+```bash
+scripts/check_delivery.sh final.mp4 --seconds 12 # PASS/WARN/FAIL per item
+scripts/contact_sheet.sh final.mp4 --at 0.5,3,6,9.5,11.5 # stills at exact moments
+ffprobe -v error -show_streams -show_format final.mp4 # everything, raw
+```
+
+## Recipes
+
+**Join clips that share size, rate and codec (no re-encode):**
+```bash
+printf "file '%s'\n" a.mp4 b.mp4 c.mp4 > list.txt
+ffmpeg -f concat -safe 0 -i list.txt -c copy joined.mp4
+```
+
+**Join with a crossfade (re-encodes):**
+```bash
+ffmpeg -i a.mp4 -i b.mp4 -filter_complex \
+ "[0:v][1:v]xfade=transition=fade:duration=0.5:offset=4.5,format=yuv420p[v]" \
+ -map "[v]" -an ab.mp4 # offset = length of a.mp4 minus the fade
+```
+
+**Put a transparent overlay (MOV with alpha, or PNG) on top of a shot:**
+```bash
+ffmpeg -i shot.mp4 -i title.mov -filter_complex "[0:v][1:v]overlay=0:0:shortest=1" -c:a copy out.mp4
+```
+
+**Lay a soundtrack under a silent render** (or use `finish.sh --audio`):
+```bash
+ffmpeg -i render.mp4 -i music.wav -map 0:v -map 1:a -c:v copy -c:a aac -shortest out.mp4
+```
+
+**A placeholder soundtrack when you have no music:** `scripts/sound_bed.sh bed.wav --seconds 12 --hits 9.0` makes a quiet original pad with a pulse and a low accent at each `--hits` time (put one on the hero moment). Replace it with real music when you have some.
+
+**Measure loudness:**
+```bash
+ffmpeg -nostats -i final.mp4 -af ebur128=peak=true -f null - 2>&1 | tail -12
+```
+
+**Find black or frozen stretches:**
+```bash
+ffmpeg -i final.mp4 -vf blackdetect=d=0.5:pic_th=0.98 -an -f null - 2>&1 | grep black_start
+ffmpeg -i final.mp4 -vf freezedetect=n=0.001:d=1.5 -an -f null - 2>&1 | grep freeze_start
+```
+
+**A GIF preview for a README or a pull request:**
+```bash
+ffmpeg -i final.mp4 -vf "fps=15,scale=800:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" preview.gif
+```
+
+**Speed up heavy encodes on Apple Silicon** (for intermediates only; keep x264 for the final): `-c:v h264_videotoolbox -b:v 12M`.
+
+## Platform targets
+
+| Where | Frame | Rate | Loudness |
+|---|---|---|---|
+| YouTube, landscape | 1920x1080 or 3840x2160 | 24, 30 or 60 | about -14 LUFS |
+| Shorts, Reels, TikTok | 1080x1920 | 30 or 60 | about -14 LUFS |
+| Slides, websites | 1920x1080 | 30 | quieter is fine, or silent |
diff --git a/skill/brief2mp4/references/hyperframes.md b/skill/brief2mp4/references/hyperframes.md
new file mode 100644
index 0000000..a47d184
--- /dev/null
+++ b/skill/brief2mp4/references/hyperframes.md
@@ -0,0 +1,77 @@
+# HyperFrames: HTML, CSS and GSAP to MP4
+
+HyperFrames renders a web page frame by frame in headless Chrome and encodes the frames to video. You write HTML and CSS for the look and a paused GSAP timeline for the motion; the renderer seeks that timeline to every frame and takes a screenshot. Because it seeks rather than plays, anything that depends on real time (timers, `requestAnimationFrame` loops, the clock) will not show up the way you expect. Drive everything from the timeline.
+
+Docs: https://hyperframes.heygen.com (machine-readable index at `/llms.txt`). Offline: `npx hyperframes docs <topic>` with topics `data-attributes`, `gsap`, `compositions`, `rendering`, `examples`, `troubleshooting`.
+
+## Start a project
+
+```bash
+npx hyperframes init my-video --example blank --non-interactive --skip-skills
+cd my-video
+```
+
+This writes `index.html` (the root composition), `hyperframes.json`, `meta.json` and `package.json`. Add `--resolution portrait` for 1080x1920. `--skip-skills` stops `init` from installing HyperFrames' own agent skills into the user's skill folders; leave it off only if the user wants them.
+
+## The composition contract
+
+```html
+<div id="root" data-composition-id="main" data-start="0" data-duration="12"
+ data-width="1920" data-height="1080">
+ <h1 id="line1" class="clip" data-start="0" data-duration="12">Ideas are cheap.</h1>
+</div>
+<script>
+ const tl = gsap.timeline({ paused: true });
+ tl.fromTo("#line1", { opacity: 0, y: 60 }, { opacity: 1, y: 0, duration: 0.6, ease: "power3.out" }, 0.2);
+ window.__timelines = window.__timelines || {};
+ window.__timelines["main"] = tl;
+</script>
+```
+
+- The root element carries `data-composition-id`, `data-start`, `data-duration`, `data-width`, `data-height`.
+- Every timed element has `data-start` and `data-duration` (seconds) and the class `clip`.
+- Register exactly one **paused** root timeline per composition in `window.__timelines["<composition-id>"]`. Child timelines you nest into it must not be paused, or they will not move when the root is seeked.
+- Timeline positions are seconds from the start of the composition. Keep a comment block at the top of the script that lists the beat sheet times; it makes fixes fast.
+- Load GSAP from a pinned CDN version (`https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js`).
+
+## Sound
+
+- Music or voiceover: an `<audio>` element with `data-start`, `data-duration` and a local file path, for example `<audio src="assets/bed.wav" data-start="0" data-duration="12"></audio>`.
+- Video with its own sound: keep it on the `<video>` element with `data-has-audio="true"` and no `muted`. Silent footage: `muted`.
+- Or render silent and add sound in the finish step: `scripts/finish.sh --audio bed.wav`. This is the simplest path and also sets loudness.
+
+## Splitting a long piece
+
+Put each scene in its own file under `compositions/` and pull it into the root with `data-composition-src="compositions/scene2.html"`. Each scene registers its own timeline under its own id. Long pieces stay editable and you can render one scene alone with `--composition`.
+
+## Commands you will use
+
+```bash
+npx hyperframes lint . # structure errors, fast
+npx hyperframes check . # lint + runtime + layout + contrast in one gate
+npx hyperframes snapshot . --at 0.5,3,7.5 # PNG stills at exact seconds: look at them
+npx hyperframes render . -o draft.mp4 --quality draft --workers 4
+npx hyperframes render . -o render.mp4 --quality delivery --fps 30
+npx hyperframes render . -o fix.mp4 --start 4 --end 7 # re-render a span only
+```
+
+Quality presets: `draft` for iterating, `looks` (default) for review, `delivery` for the final. `--workers` sets parallel Chrome processes (about 256 MB each); 4-8 suits most laptops. Renders queue by default, so starting two does not make either faster.
+
+## Patterns that work
+
+- **Word-by-word or line-by-line type:** wrap each word in a `<span>` and stagger: `tl.from(".l1 span", { yPercent: 110, opacity: 0, duration: 0.5, stagger: 0.06, ease: "power3.out" }, 0.3)`. Put the words inside a wrapper with `overflow: hidden` for a clean mask reveal.
+- **Count-ups:** tween a plain object and write the rounded value into the element in `onUpdate`. Format with `toLocaleString("en-US")` so the commas are right.
+- **A shape that carries across scenes:** one element (a bar, a circle) that grows to fill the frame becomes the next background. It reads as one continuous film instead of a slide show.
+- **Camera feel on 2D:** scale the whole stage from 1.0 to 1.04 over the shot. Tiny, but it keeps a held frame alive.
+- **Fonts:** use a web font loaded with `<link>` from Google Fonts, or a system stack. Check the snapshot to confirm the font actually loaded; a fallback font is the most common silent failure.
+
+## Common failures and the fix
+
+| You see | Cause | Fix |
+|---|---|---|
+| Nothing moves in the render | Timeline not registered, wrong id, or not paused | `window.__timelines["<id matching data-composition-id>"] = tl` with `paused: true` |
+| An element never appears | Missing `data-start` / `data-duration`, or its time range does not cover the tween | Give it the full range it is on screen |
+| Nested animation frozen | Child timeline created paused | Create children unpaused; only the root is paused |
+| Different result every render | `Math.random()`, `Date.now()`, or a fetch | Seeded random, fixed values, local files |
+| Text in the wrong font | Font not loaded before capture | Load from a pinned URL or local file; confirm in a snapshot |
+| Render is the wrong length | Root `data-duration` differs from the brief | Set it to the exact seconds; `finish.sh --seconds` trims and pads too |
diff --git a/skill/brief2mp4/references/threejs.md b/skill/brief2mp4/references/threejs.md
new file mode 100644
index 0000000..a4fa19b
--- /dev/null
+++ b/skill/brief2mp4/references/threejs.md
@@ -0,0 +1,59 @@
+# Three.js inside HyperFrames
+
+Three.js draws 3D with WebGL. On its own it animates with a render loop that runs in real time, which a frame-by-frame renderer cannot capture reliably. The fix is to make the 3D scene a pure function of time: GSAP owns the clock, and every time HyperFrames seeks the timeline, one `draw(t)` call positions everything for second `t` and renders once.
+
+Start from `templates/threejs/index.html`. It renders as is (10 s, a low-poly shape, a slow camera dolly, seeded stars, an HTML title on top).
+
+## The pattern
+
+```js
+import * as THREE from "three"; // via an import map pinned to one version
+
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, preserveDrawingBuffer: true });
+renderer.setPixelRatio(1); // the canvas is already 1920x1080
+renderer.setSize(1920, 1080, false);
+
+function draw(t) { // t in seconds: the ONLY place that decides the frame
+ camera.position.set(/* from t */);
+ camera.lookAt(0, 0, 0);
+ subject.rotation.y = t * 0.5;
+ renderer.render(scene, camera);
+}
+
+const clock = { t: 0 };
+const tl = gsap.timeline({ paused: true });
+tl.to(clock, { t: DURATION, duration: DURATION, ease: "none", onUpdate: () => draw(clock.t) }, 0);
+window.__timelines = window.__timelines || {};
+window.__timelines["main"] = tl;
+draw(0);
+```
+
+Rules:
+
+- No `renderer.setAnimationLoop`, no `requestAnimationFrame`, no `THREE.Clock`. Time comes only from `t`.
+- Compute positions from `t` directly (`x = 4 * Math.sin(t * 0.8)`), or keep GSAP tweens on plain objects and read their values in `draw`. Both are seek-safe.
+- Random layouts use a seeded generator (the template includes `mulberry32`). Same seed, same stars, every render.
+- `preserveDrawingBuffer: true` so the captured frame is the finished frame.
+- Pin the Three.js version in the import map (the template uses 0.170.0). Do not use `latest`.
+
+## Text and 3D together
+
+Put headlines in HTML on top of the canvas, animated by the same GSAP timeline. HTML text is sharper than text inside WebGL and easier to check. Use 3D text (`TextGeometry`) only when the brief wants letters with depth that the camera moves around.
+
+## Making it look designed
+
+- **Light:** one hemisphere light for the base and one strong directional key from above and to the side. Add a rim light behind the subject in a warm or saturated colour from the palette to separate it from the background.
+- **Material:** `MeshStandardMaterial` with `flatShading: true` reads as clean low-poly; `roughness` 0.3-0.6 for most surfaces.
+- **Camera:** one motivated move per shot (a dolly in, an orbit, a crane up). Ease it. A camera that drifts randomly reads as unfinished.
+- **Depth:** fog in the background colour (`scene.fog = new THREE.Fog(color, near, far)`) and a few thousand small points give scale cheaply.
+- **Instancing:** for hundreds of the same object use `InstancedMesh` and set each matrix in `draw(t)`.
+
+## Performance
+
+HyperFrames uses the machine's GPU for WebGL when it can (`--browser-gpu` forces it; `--no-browser-gpu` forces software rendering, which is slow but works on any machine). A 10-second 1080p scene with a few thousand objects renders in well under a minute on a recent laptop. If a render crawls, cut shadow-map size, polygon count or post effects before anything else.
+
+## Checks that catch 3D bugs
+
+- Snapshot the first frame, the middle and the last: the subject must be in frame and lit in all three.
+- Black frames usually mean the camera is inside an object or looking away. Print the camera position at those times.
+- A flat, grey look usually means the lights are too weak for `MeshStandardMaterial`: raise the key light intensity.
diff --git a/skill/brief2mp4/scripts/check_delivery.sh b/skill/brief2mp4/scripts/check_delivery.sh
new file mode 100755
index 0000000..8c62176
--- /dev/null
+++ b/skill/brief2mp4/scripts/check_delivery.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# check_delivery.sh: measure a finished MP4 against the delivery spec.
+# Prints one PASS / WARN / FAIL line per check and exits 1 if anything FAILs.
+#
+# check_delivery.sh final.mp4 --seconds 12
+# check_delivery.sh final.mp4 --seconds 8 --size 1080x1920 --fps 30 --silent-ok
+#
+# Options
+# --seconds N expected duration (required); tolerance is one frame
+# --size WxH expected frame size (default 1920x1080)
+# --fps N expected frame rate (default 30)
+# --lufs N loudness target (default -14), checked within +/-1.5 LU
+# --silent-ok a silent soundtrack is what the brief asked for
+set -uo pipefail
+
+FILE="${1:-}"; shift || true
+SECONDS_="" SIZE="1920x1080" FPS=30 LUFS=-14 SILENT_OK=0
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --seconds) SECONDS_="$2"; shift 2 ;;
+ --size) SIZE="$2"; shift 2 ;;
+ --fps) FPS="$2"; shift 2 ;;
+ --lufs) LUFS="$2"; shift 2 ;;
+ --silent-ok) SILENT_OK=1; shift ;;
+ *) echo "check_delivery.sh: unknown option $1" >&2; exit 2 ;;
+ esac
+done
+[[ -f "$FILE" && -n "$SECONDS_" ]] || { echo "usage: check_delivery.sh FILE --seconds N [--size WxH] [--fps N]" >&2; exit 2; }
+
+FAILS=0
+pass() { echo "PASS $1"; }
+warn() { echo "WARN $1"; }
+fail() { echo "FAIL $1"; FAILS=$((FAILS + 1)); }
+probe() { ffprobe -v error -select_streams "$1" -show_entries "$2" -of default=nw=1:nk=1 "$FILE" | head -1; }
+
+W="${SIZE%x*}" H="${SIZE#*x}"
+vcodec="$(probe v:0 stream=codec_name)"
+pix="$(probe v:0 stream=pix_fmt)"
+vw="$(probe v:0 stream=width)"; vh="$(probe v:0 stream=height)"
+rate="$(probe v:0 stream=avg_frame_rate)"
+dur="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$FILE")"
+acodec="$(probe a:0 stream=codec_name)"
+arate="$(probe a:0 stream=sample_rate)"
+ach="$(probe a:0 stream=channels)"
+
+[[ "$vcodec" == "h264" ]] && pass "video codec h264" || fail "video codec is '$vcodec', want h264"
+[[ "$pix" == "yuv420p" ]] && pass "pixel format yuv420p" || fail "pixel format is '$pix', want yuv420p"
+[[ "$vw" == "$W" && "$vh" == "$H" ]] && pass "frame size ${vw}x${vh}" || fail "frame size ${vw}x${vh}, want ${W}x${H}"
+fps_ok="$(awk -v r="$rate" -v f="$FPS" 'BEGIN{split(r,a,"/"); v=(a[2]>0)?a[1]/a[2]:a[1]; print (v>f-0.01 && v<f+0.01)?1:0}')"
+[[ "$fps_ok" == 1 ]] && pass "frame rate $rate" || fail "frame rate $rate, want $FPS"
+dur_ok="$(awk -v d="$dur" -v s="$SECONDS_" -v f="$FPS" 'BEGIN{diff=d-s; if(diff<0)diff=-diff; print (diff<=1.0/f+0.001)?1:0}')"
+[[ "$dur_ok" == 1 ]] && pass "duration ${dur}s" || fail "duration ${dur}s, want ${SECONDS_}s (+/- one frame)"
+
+if [[ -z "$acodec" ]]; then
+ fail "no audio stream (add one, even silent: finish.sh does this)"
+else
+ [[ "$acodec" == "aac" ]] && pass "audio codec aac" || fail "audio codec is '$acodec', want aac"
+ [[ "$arate" == "48000" ]] && pass "audio 48 kHz" || warn "audio sample rate $arate (48000 preferred)"
+ [[ "$ach" == "2" ]] && pass "audio stereo" || warn "audio has $ach channel(s) (stereo preferred)"
+ stats="$(ffmpeg -nostats -hide_banner -i "$FILE" -map 0:a:0 -af ebur128=peak=true -f null - 2>&1 | tail -14)"
+ il="$(echo "$stats" | awk '/I:/{v=$2} END{print v}')"
+ tp="$(echo "$stats" | awk '/Peak:/{v=$2} END{print v}')"
+ if [[ -z "$il" || "$il" == "-inf" ]] || awk -v i="$il" 'BEGIN{exit !(i < -60)}'; then
+ [[ "$SILENT_OK" == 1 ]] && pass "soundtrack silent (brief allows it)" || warn "soundtrack is silent; pass --silent-ok if the brief asked for silence"
+ else
+ awk -v i="$il" -v t="$LUFS" 'BEGIN{d=i-t; if(d<0)d=-d; exit !(d<=1.5)}' \
+ && pass "loudness ${il} LUFS (target ${LUFS})" || fail "loudness ${il} LUFS, target ${LUFS} +/- 1.5"
+ awk -v p="$tp" 'BEGIN{exit !(p<=-1.0)}' && pass "true peak ${tp} dBTP" || fail "true peak ${tp} dBTP, want <= -1.0"
+ fi
+fi
+
+# Picture health: long black stretches and long frozen stretches.
+black="$(ffmpeg -nostats -hide_banner -i "$FILE" -vf "blackdetect=d=0.5:pic_th=0.98" -an -f null - 2>&1 | grep -c black_start || true)"
+[[ "$black" == 0 ]] && pass "no black stretch over 0.5 s" || warn "$black black stretch(es) over 0.5 s: intended?"
+frozen="$(ffmpeg -nostats -hide_banner -i "$FILE" -vf "freezedetect=n=0.001:d=1.5" -an -f null - 2>&1 | grep -c freeze_start || true)"
+[[ "$frozen" == 0 ]] && pass "nothing frozen over 1.5 s" || warn "$frozen frozen stretch(es) over 1.5 s: a hold the brief asked for, or dead air?"
+
+echo "----"
+if [[ "$FAILS" == 0 ]]; then echo "RESULT: PASS ($FILE)"; exit 0; else echo "RESULT: FAIL, $FAILS check(s) ($FILE)"; exit 1; fi
diff --git a/skill/brief2mp4/scripts/contact_sheet.sh b/skill/brief2mp4/scripts/contact_sheet.sh
new file mode 100755
index 0000000..38d00e0
--- /dev/null
+++ b/skill/brief2mp4/scripts/contact_sheet.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# contact_sheet.sh: pull frames from a video so you can LOOK at it before you
+# say it is done. Writes one PNG per sample, named by its time, plus a grid.
+#
+# contact_sheet.sh final.mp4 # a frame every second
+# contact_sheet.sh final.mp4 --at 0.5,3,7.2 # exactly these moments (seconds)
+# contact_sheet.sh final.mp4 --every 0.5 --out checks/
+#
+# Output: <out>/t_003.00s.png ... and <out>/sheet.png (6 columns, read left to
+# right, top to bottom, in time order).
+set -euo pipefail
+
+FILE="${1:-}"; shift || true
+EVERY=1 AT="" OUT="checks"
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --every) EVERY="$2"; shift 2 ;;
+ --at) AT="$2"; shift 2 ;;
+ --out) OUT="$2"; shift 2 ;;
+ *) echo "contact_sheet.sh: unknown option $1" >&2; exit 2 ;;
+ esac
+done
+[[ -f "$FILE" ]] || { echo "usage: contact_sheet.sh FILE [--every S | --at t1,t2] [--out DIR]" >&2; exit 2; }
+mkdir -p "$OUT"
+rm -f "$OUT"/t_*.png "$OUT"/sheet.png
+
+dur="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$FILE")"
+if [[ -z "$AT" ]]; then
+ AT="$(awk -v d="$dur" -v e="$EVERY" 'BEGIN{s=""; for(t=0; t<d-0.01; t+=e){s=s (s==""?"":",") t}; print s}')"
+fi
+
+IFS=',' read -r -a TIMES <<< "$AT"
+for t in "${TIMES[@]}"; do
+ name="$(awk -v t="$t" 'BEGIN{printf "t_%06.2fs.png", t}')"
+ ffmpeg -v error -y -ss "$t" -i "$FILE" -frames:v 1 "$OUT/$name"
+done
+
+n="${#TIMES[@]}"; cols=6; rows=$(( (n + cols - 1) / cols ))
+ffmpeg -v error -y -pattern_type glob -i "$OUT/t_*.png" \
+ -vf "scale=480:-1,tile=${cols}x${rows}:padding=6:color=0x222222" -frames:v 1 "$OUT/sheet.png"
+echo "contact_sheet.sh: $n frames in $OUT/, grid at $OUT/sheet.png (6 per row, time order)"
diff --git a/skill/brief2mp4/scripts/finish.sh b/skill/brief2mp4/scripts/finish.sh
new file mode 100755
index 0000000..7711fcc
--- /dev/null
+++ b/skill/brief2mp4/scripts/finish.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# finish.sh: turn a rough render (MP4/MOV or a folder of PNG frames) into a
+# delivery-ready MP4: exact size, frame rate, duration, H.264 + AAC, loudness.
+#
+# finish.sh --in render.mp4 --out final.mp4 --seconds 12
+# finish.sh --in frames/ --out final.mp4 --seconds 8 --audio bed.wav
+#
+# Options
+# --in PATH video file, or a folder of numbered PNGs (0001.png ...)
+# --out PATH output MP4 (default final.mp4)
+# --seconds N exact duration of the result (required)
+# --fps N frame rate (default 30)
+# --size WxH frame size (default 1920x1080); the picture is fitted, never stretched
+# --audio PATH soundtrack to lay under the picture (replaces any audio in --in)
+# --keep-audio keep the audio already inside --in
+# --lufs N integrated loudness target (default -14)
+# --crf N x264 quality, lower is better (default 18)
+set -euo pipefail
+
+IN="" OUT="final.mp4" SECONDS_="" FPS=30 SIZE="1920x1080" AUDIO="" KEEP=0 LUFS=-14 CRF=18
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --in) IN="$2"; shift 2 ;;
+ --out) OUT="$2"; shift 2 ;;
+ --seconds) SECONDS_="$2"; shift 2 ;;
+ --fps) FPS="$2"; shift 2 ;;
+ --size) SIZE="$2"; shift 2 ;;
+ --audio) AUDIO="$2"; shift 2 ;;
+ --keep-audio) KEEP=1; shift ;;
+ --lufs) LUFS="$2"; shift 2 ;;
+ --crf) CRF="$2"; shift 2 ;;
+ -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+ *) echo "finish.sh: unknown option $1" >&2; exit 2 ;;
+ esac
+done
+
+[[ -n "$IN" && -n "$SECONDS_" ]] || { echo "finish.sh: --in and --seconds are required" >&2; exit 2; }
+command -v ffmpeg >/dev/null || { echo "finish.sh: ffmpeg not found" >&2; exit 2; }
+W="${SIZE%x*}" H="${SIZE#*x}"
+
+# Picture input: a frame folder or a video file.
+if [[ -d "$IN" ]]; then
+ FIRST=""
+ for f in "$IN"/*.png; do
+ name="$(basename "$f")"
+ if [[ "$name" =~ ^[0-9]+\.png$ ]] && { [[ -z "$FIRST" ]] || [[ "$name" < "$FIRST" ]]; }; then FIRST="$name"; fi
+ done
+ [[ -n "$FIRST" ]] || { echo "finish.sh: no numbered PNGs in $IN" >&2; exit 2; }
+ DIGITS="${#FIRST}"; DIGITS=$((DIGITS - 4))
+ START="$((10#${FIRST%.png}))"
+ VIN=(-framerate "$FPS" -start_number "$START" -i "$IN/%0${DIGITS}d.png")
+else
+ [[ -f "$IN" ]] || { echo "finish.sh: $IN not found" >&2; exit 2; }
+ VIN=(-i "$IN")
+fi
+
+# Fit inside the frame, pad the rest, hold the last frame if the render is short.
+VF="scale=${W}:${H}:force_original_aspect_ratio=decrease:flags=lanczos,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,fps=${FPS},tpad=stop_mode=clone:stop_duration=${SECONDS_},format=yuv420p"
+AF="loudnorm=I=${LUFS}:TP=-1.5:LRA=11,aresample=48000,apad,atrim=0:${SECONDS_},afade=t=out:st=$(awk "BEGIN{print ${SECONDS_}-0.4}"):d=0.4"
+
+if [[ -n "$AUDIO" ]]; then
+ ffmpeg -v error -y "${VIN[@]}" -i "$AUDIO" -map 0:v:0 -map 1:a:0 -vf "$VF" -af "$AF" \
+ -t "$SECONDS_" -c:v libx264 -preset slow -crf "$CRF" -profile:v high -r "$FPS" \
+ -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart "$OUT"
+elif [[ "$KEEP" == 1 ]]; then
+ ffmpeg -v error -y "${VIN[@]}" -map 0:v:0 -map 0:a:0 -vf "$VF" -af "$AF" \
+ -t "$SECONDS_" -c:v libx264 -preset slow -crf "$CRF" -profile:v high -r "$FPS" \
+ -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart "$OUT"
+else
+ # No soundtrack: add a silent stereo track so every player and platform accepts the file.
+ ffmpeg -v error -y "${VIN[@]}" -f lavfi -i anullsrc=channel_layout=stereo:sample_rate=48000 \
+ -map 0:v:0 -map 1:a:0 -vf "$VF" -t "$SECONDS_" \
+ -c:v libx264 -preset slow -crf "$CRF" -profile:v high -r "$FPS" \
+ -c:a aac -b:a 128k -ar 48000 -ac 2 -movflags +faststart "$OUT"
+fi
+echo "finish.sh: wrote $OUT (${W}x${H}, ${FPS} fps, ${SECONDS_} s)"
diff --git a/skill/brief2mp4/scripts/sound_bed.sh b/skill/brief2mp4/scripts/sound_bed.sh
new file mode 100755
index 0000000..9a97fbf
--- /dev/null
+++ b/skill/brief2mp4/scripts/sound_bed.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# sound_bed.sh: a quiet, original placeholder soundtrack made from sine waves,
+# so a render is never delivered silent by accident. Swap in real music or a
+# voiceover whenever you have one.
+#
+# sound_bed.sh bed.wav --seconds 12
+# sound_bed.sh bed.wav --seconds 10 --bpm 96 --hits 2.0,6.5
+#
+# Options
+# --seconds N length (required)
+# --bpm N pulse tempo (default 100)
+# --hits LIST extra low "boom" accents at these seconds (e.g. on a reveal)
+set -euo pipefail
+
+OUT="${1:-}"; shift || true
+SECONDS_="" BPM=100 HITS=""
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --seconds) SECONDS_="$2"; shift 2 ;;
+ --bpm) BPM="$2"; shift 2 ;;
+ --hits) HITS="$2"; shift 2 ;;
+ *) echo "sound_bed.sh: unknown option $1" >&2; exit 2 ;;
+ esac
+done
+[[ -n "$OUT" && -n "$SECONDS_" ]] || { echo "usage: sound_bed.sh OUT.wav --seconds N [--bpm N] [--hits t1,t2]" >&2; exit 2; }
+
+BEAT="$(awk -v b="$BPM" 'BEGIN{print 60/b}')"
+# Pad: an A-minor-ish chord with a slow swell. Pulse: a soft low thump on every beat.
+PAD="0.06*sin(2*PI*220*t)*(0.6+0.4*sin(2*PI*0.25*t))+0.045*sin(2*PI*261.63*t)+0.04*sin(2*PI*329.63*t)*(0.7+0.3*sin(2*PI*0.5*t))"
+PULSE="0.22*sin(2*PI*55*t)*exp(-9*mod(t\,${BEAT}))"
+EXPR="${PAD}+${PULSE}"
+if [[ -n "$HITS" ]]; then
+ IFS=',' read -r -a H <<< "$HITS"
+ for h in "${H[@]}"; do
+ EXPR="${EXPR}+0.5*sin(2*PI*45*(t-${h}))*exp(-4*(t-${h}))*gte(t\,${h})"
+ done
+fi
+
+ffmpeg -v error -y -f lavfi -i "aevalsrc=${EXPR}|${EXPR}:s=48000:d=${SECONDS_}" \
+ -af "afade=t=in:d=0.6,afade=t=out:st=$(awk -v s="$SECONDS_" 'BEGIN{print s-1}'):d=1,lowpass=f=6000" \
+ -c:a pcm_s16le "$OUT"
+echo "sound_bed.sh: wrote $OUT (${SECONDS_} s, ${BPM} bpm)"
diff --git a/skill/brief2mp4/templates/SPEC.md b/skill/brief2mp4/templates/SPEC.md
new file mode 100644
index 0000000..7566218
--- /dev/null
+++ b/skill/brief2mp4/templates/SPEC.md
@@ -0,0 +1,41 @@
+# SPEC: <title>
+
+## Delivery
+| Item | Value |
+|---|---|
+| File | final.mp4 |
+| Frame | 1920x1080 |
+| Frame rate | 30 fps |
+| Duration | <N.0> s |
+| Video | H.264, yuv420p |
+| Audio | AAC 48 kHz stereo, -14 LUFS, true peak <= -1 dBTP (or: silent track) |
+
+## Exact text (character for character)
+1. "<line one>"
+2. "<line two>"
+
+## Look
+- Palette: background #......, ink #......, accent #......
+- Type: <face>, <weights>
+- Mood: <five words or fewer>
+
+## Beat sheet
+| Time (s) | On screen | Motion |
+|---|---|---|
+| 0.0-2.0 | | |
+| 2.0-5.0 | | |
+| ... | | |
+| <N-2>-<N> | final message holds | |
+
+Hero moment: <time>: <what happens>
+
+## Tool
+<HyperFrames | Three.js in HyperFrames | Blender | mix> because <one sentence>.
+
+## Decisions (choices the brief left open)
+-
+
+## Done when
+- [ ] final.mp4 is <N.0> s, 1920x1080, 30 fps (check_delivery.sh PASS)
+- [ ] at <t> s "<line one>" is fully on screen, spelled exactly, nothing cut off
+- [ ] <one line per requirement in the brief>
diff --git a/skill/brief2mp4/templates/blender/scene.py b/skill/brief2mp4/templates/blender/scene.py
new file mode 100644
index 0000000..f56708b
--- /dev/null
+++ b/skill/brief2mp4/templates/blender/scene.py
@@ -0,0 +1,193 @@
+"""brief2mp4 starter: a scripted Blender product turntable.
+
+Run it headless (no Blender window needed):
+
+ blender --background --factory-startup --python scene.py -- \
+ --frames-dir frames --seconds 8 --fps 30 --samples 32
+
+It writes PNG frames (frames/0001.png ...). Encode them with
+scripts/finish.sh so the MP4 meets the delivery spec.
+
+Everything is built from code: geometry, materials, lights, camera move and
+title. Replace build_subject() with what the brief asks for; keep the rest.
+"""
+
+import argparse
+import math
+import os
+import sys
+
+import bpy
+
+
+def parse_args():
+ argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+ p = argparse.ArgumentParser()
+ p.add_argument("--frames-dir", default="frames")
+ p.add_argument("--seconds", type=float, default=8.0)
+ p.add_argument("--fps", type=int, default=30)
+ p.add_argument("--width", type=int, default=1920)
+ p.add_argument("--height", type=int, default=1080)
+ p.add_argument("--samples", type=int, default=32)
+ p.add_argument("--engine", default="EEVEE", choices=["EEVEE", "CYCLES"])
+ p.add_argument("--title", default="TITLE")
+ p.add_argument("--preview", action="store_true", help="render only 3 stills (start, middle, end)")
+ return p.parse_args(argv)
+
+
+def hex_rgba(h):
+ h = h.lstrip("#")
+ srgb = [int(h[i:i + 2], 16) / 255 for i in (0, 2, 4)]
+ lin = [c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in srgb]
+ return (*lin, 1.0)
+
+
+def material(name, color, roughness=0.4, metallic=0.0, emission=None, strength=0.0):
+ mat = bpy.data.materials.new(name)
+ mat.use_nodes = True
+ # Find the shader node by type, never by its (localised) name.
+ bsdf = next(n for n in mat.node_tree.nodes if n.type == "BSDF_PRINCIPLED")
+ bsdf.inputs["Base Color"].default_value = hex_rgba(color)
+ bsdf.inputs["Roughness"].default_value = roughness
+ bsdf.inputs["Metallic"].default_value = metallic
+ if emission:
+ bsdf.inputs["Emission Color"].default_value = hex_rgba(emission)
+ bsdf.inputs["Emission Strength"].default_value = strength
+ return mat
+
+
+def set_engine(scene, wanted, samples):
+ names = ["BLENDER_EEVEE", "BLENDER_EEVEE_NEXT"] if wanted == "EEVEE" else ["CYCLES"]
+ for name in names:
+ try:
+ scene.render.engine = name
+ break
+ except TypeError:
+ continue
+ if scene.render.engine == "CYCLES":
+ scene.cycles.samples = samples
+ scene.cycles.use_denoising = True
+ try:
+ prefs = bpy.context.preferences.addons["cycles"].preferences
+ prefs.compute_device_type = "METAL"
+ prefs.get_devices()
+ scene.cycles.device = "GPU"
+ except Exception:
+ scene.cycles.device = "CPU"
+ else:
+ scene.eevee.taa_render_samples = samples
+
+
+def build_subject():
+ """Placeholder product: a ceramic cup. Replace with the brief's object."""
+ bpy.ops.mesh.primitive_cylinder_add(vertices=96, radius=0.55, depth=1.1, location=(0, 0, 0.55))
+ cup = bpy.context.object
+ bev = cup.modifiers.new("bevel", "BEVEL")
+ bev.width = 0.04
+ bev.segments = 4
+ bpy.ops.object.shade_smooth()
+ bpy.ops.mesh.primitive_torus_add(major_radius=0.28, minor_radius=0.06, location=(0.68, 0, 0.55),
+ rotation=(math.radians(90), 0, 0))
+ handle = bpy.context.object
+ bpy.ops.object.shade_smooth()
+ mat = material("ceramic", "#f4ece1", roughness=0.25)
+ for ob in (cup, handle):
+ ob.data.materials.append(mat)
+ handle.parent = cup
+ handle.matrix_parent_inverse = cup.matrix_world.inverted() # keep its world position
+ return cup
+
+
+def main():
+ args = parse_args()
+ bpy.ops.wm.read_factory_settings(use_empty=True)
+ scene = bpy.context.scene
+ scene.render.resolution_x = args.width
+ scene.render.resolution_y = args.height
+ scene.render.resolution_percentage = 100
+ scene.render.fps = args.fps
+ frames = int(round(args.seconds * args.fps))
+ scene.frame_start, scene.frame_end = 1, frames
+ set_engine(scene, args.engine, args.samples)
+ scene.render.image_settings.file_format = "PNG"
+ frames_dir = os.path.abspath(args.frames_dir)
+ scene.render.filepath = os.path.join(frames_dir, "")
+
+ world = bpy.data.worlds.new("world")
+ scene.world = world
+ world.use_nodes = True
+ bg = next(n for n in world.node_tree.nodes if n.type == "BACKGROUND")
+ bg.inputs["Color"].default_value = hex_rgba("#2a2140")
+ bg.inputs["Strength"].default_value = 0.4
+
+ # Floor that fades into the background.
+ bpy.ops.mesh.primitive_plane_add(size=400)
+ bpy.context.object.data.materials.append(material("floor", "#2a2140", roughness=0.6))
+
+ subject = build_subject()
+
+ # Three-point light: key, rim, fill.
+ def area(name, loc, energy, size, color="#ffffff"):
+ bpy.ops.object.light_add(type="AREA", location=loc)
+ light = bpy.context.object
+ light.name = name
+ light.data.energy = energy
+ light.data.size = size
+ light.data.color = hex_rgba(color)[:3]
+ direction = -light.location.normalized()
+ light.rotation_euler = direction.to_track_quat("-Z", "Y").to_euler()
+ return light
+
+ area("key", (3, -3, 4), 600, 3)
+ area("rim", (-3, 3, 3), 400, 2, "#ffb48a")
+ area("fill", (-4, -2, 2), 120, 4)
+
+ # Camera on a turntable: rotate an empty, the camera follows.
+ bpy.ops.object.empty_add(location=(0, 0, 0.6))
+ pivot = bpy.context.object
+ bpy.ops.object.camera_add(location=(0, -6.5, 1.6))
+ cam = bpy.context.object
+ cam.parent = pivot
+ cam.data.lens = 50
+ track = cam.constraints.new("TRACK_TO")
+ track.target = pivot
+ track.track_axis = "TRACK_NEGATIVE_Z"
+ track.up_axis = "UP_Y"
+ scene.camera = cam
+ edit_prefs = bpy.context.preferences.edit
+ edit_prefs.keyframe_new_interpolation_type = "LINEAR" # constant turntable speed
+ pivot.rotation_euler = (0, 0, 0)
+ pivot.keyframe_insert("rotation_euler", frame=1)
+ pivot.rotation_euler = (0, 0, math.radians(300))
+ pivot.keyframe_insert("rotation_euler", frame=frames)
+
+ # Title in 3D, scales up in the last 25% of the shot.
+ bpy.ops.object.text_add(location=(0, 0, 1.55))
+ title = bpy.context.object
+ title.data.body = args.title
+ title.data.align_x = "CENTER"
+ title.data.size = 0.32
+ title.data.extrude = 0.02
+ title.data.materials.append(material("title", "#fff4e8", emission="#fff4e8", strength=1.5))
+ title.parent = pivot # always faces the camera
+ title.location = (0, -0.6, 0.85) # local to the pivot: above the subject, toward the camera
+ title.rotation_euler = (math.radians(90), 0, 0)
+ edit_prefs.keyframe_new_interpolation_type = "BEZIER" # eased title
+ start = int(frames * 0.75)
+ title.scale = (0.001, 0.001, 0.001)
+ title.keyframe_insert("scale", frame=start)
+ title.scale = (1, 1, 1)
+ title.keyframe_insert("scale", frame=min(frames, start + args.fps))
+
+ if args.preview:
+ for i, f in enumerate((1, frames // 2, frames)):
+ scene.frame_set(f)
+ scene.render.filepath = os.path.join(frames_dir, f"preview_{i}.png")
+ bpy.ops.render.render(write_still=True)
+ else:
+ bpy.ops.render.render(animation=True)
+ print(f"brief2mp4: rendered {frames} frames to {args.frames_dir}/")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skill/brief2mp4/templates/threejs/index.html b/skill/brief2mp4/templates/threejs/index.html
new file mode 100644
index 0000000..8e27c7d
--- /dev/null
+++ b/skill/brief2mp4/templates/threejs/index.html
@@ -0,0 +1,115 @@
+<!doctype html>
+<!--
+ brief2mp4 starter: a Three.js scene that HyperFrames can render frame by frame.
+ The whole picture is a pure function of time t (seconds). GSAP owns the clock;
+ Three.js only draws. Replace the scene, keep the pattern.
+-->
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=1920, height=1080" />
+ <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
+ <style>
+ :root {
+ --ground: #14112b;
+ --ink: #fff4e8;
+ --accent: #ff7a59;
+ }
+ * { margin: 0; padding: 0; box-sizing: border-box; }
+ html, body {
+ width: 1920px;
+ height: 1080px;
+ overflow: hidden;
+ background: var(--ground);
+ }
+ #stage { position: absolute; inset: 0; }
+ #gl { width: 1920px; height: 1080px; display: block; }
+ #title {
+ position: absolute;
+ left: 0;
+ right: 0;
+ bottom: 140px;
+ text-align: center;
+ color: var(--ink);
+ font: 700 120px/1 "Helvetica Neue", Arial, sans-serif;
+ letter-spacing: 0.12em;
+ opacity: 0;
+ }
+ </style>
+ </head>
+ <body>
+ <div id="stage" data-composition-id="main" data-start="0" data-duration="10" data-width="1920" data-height="1080">
+ <canvas id="gl" class="clip" width="1920" height="1080" data-start="0" data-duration="10"></canvas>
+ <div id="title" class="clip" data-start="0" data-duration="10">TITLE</div>
+ </div>
+
+ <script type="importmap">
+ { "imports": { "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js" } }
+ </script>
+ <script type="module">
+ import * as THREE from "three";
+
+ const DURATION = 10;
+
+ // Renderer: fixed size, pixel ratio 1, keep the buffer so each captured frame is complete.
+ const canvas = document.getElementById("gl");
+ const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, preserveDrawingBuffer: true });
+ renderer.setPixelRatio(1);
+ renderer.setSize(1920, 1080, false);
+ renderer.setClearColor(0x14112b, 1);
+
+ const scene = new THREE.Scene();
+ const camera = new THREE.PerspectiveCamera(40, 1920 / 1080, 0.1, 200);
+
+ scene.add(new THREE.HemisphereLight(0xfff4e8, 0x14112b, 0.6));
+ const key = new THREE.DirectionalLight(0xffffff, 2.2);
+ key.position.set(5, 6, 4);
+ scene.add(key);
+
+ // Placeholder subject: replace with the scene the brief asks for.
+ const subject = new THREE.Mesh(
+ new THREE.IcosahedronGeometry(1.4, 1),
+ new THREE.MeshStandardMaterial({ color: 0xff7a59, flatShading: true, roughness: 0.55 })
+ );
+ scene.add(subject);
+
+ // Seeded random (never Math.random): same seed, same picture, every render.
+ function mulberry32(seed) {
+ return function () {
+ seed |= 0; seed = (seed + 0x6d2b79f5) | 0;
+ let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+ r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+ return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+ };
+ }
+ const rand = mulberry32(42);
+ const stars = new THREE.BufferGeometry();
+ const pts = new Float32Array(900 * 3);
+ for (let i = 0; i < pts.length; i++) pts[i] = (rand() - 0.5) * 80;
+ stars.setAttribute("position", new THREE.BufferAttribute(pts, 3));
+ scene.add(new THREE.Points(stars, new THREE.PointsMaterial({ color: 0xfff4e8, size: 0.08 })));
+
+ const ease = (x) => 1 - Math.pow(1 - Math.min(Math.max(x, 0), 1), 3);
+
+ // The only place that decides what the frame looks like.
+ function draw(t) {
+ const dolly = ease(t / DURATION);
+ camera.position.set(Math.sin(t * 0.25) * 2, 1.2 - dolly * 0.6, 9 - dolly * 3.5);
+ camera.lookAt(0, -0.7, 0);
+ subject.rotation.set(t * 0.3, t * 0.5, 0);
+ renderer.render(scene, camera);
+ }
+
+ // GSAP owns time. HyperFrames seeks this timeline to every frame.
+ const clock = { t: 0 };
+ const tl = gsap.timeline({ paused: true });
+ tl.to(clock, { t: DURATION, duration: DURATION, ease: "none", onUpdate: () => draw(clock.t) }, 0);
+ tl.fromTo("#title", { opacity: 0, y: 40 }, { opacity: 1, y: 0, duration: 0.8, ease: "power3.out" }, 7);
+
+ window.__timelines = window.__timelines || {};
+ window.__timelines["main"] = tl;
+ draw(0);
+ tl.seek(0);
+ </script>
+ </body>
+</html>