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.
Python 3dagent-skillsai-videoanimationblenderclaude-codeclaude-skillsclaymationcodexexplainer-videoffmpeggsaphyperframeskinetic-typographymanimmotion-graphicstext-to-videothreejsvideo-generationyoutube-shorts
docs: example 08 guide, the exact prompt to make the hero video and a script to check it
Varun Pratap Bhardwajb0aa26b46285
diff --git a/README.md b/README.mdindex abb78db..655b783 100644--- a/README.md+++ b/README.md@@ -32,7 +32,7 @@<a href="assets/example08-five-worlds.mp4"><img src="assets/example08-five-worlds.webp" alt="Example 08: the words of a brief lift off the page into a 3D city of light, the camera flies into a 2D chart world, rides a bar up into a spiral galaxy of particles, and the galaxy becomes the full stop in brief2mp4. One camera move, no cuts." width="100%"></a></p>-<p align="center"><b>One brief, five worlds, no cuts.</b> This is <a href="examples/08-brief-becomes-world/BRIEF.md">example 08</a>: the brief was pasted as written and the skill made the video, 2D type and charts in HyperFrames, the city and 27,000 particles in Three.js, finished with ffmpeg. Its <a href="examples/08-brief-becomes-world/SAMPLE-REPORT.md">report</a> shows 0 scene cuts and a first-to-last frame SSIM of 0.97, so it loops. <a href="assets/example08-five-worlds.mp4">Full-quality MP4 with sound</a>.</p>+<p align="center"><b>One brief, five worlds, no cuts.</b> This is <a href="examples/08-brief-becomes-world/BRIEF.md">example 08</a>: the brief was pasted as written and the skill made the video, 2D type and charts in HyperFrames, the city and 27,000 particles in Three.js, finished with ffmpeg. Its <a href="examples/08-brief-becomes-world/SAMPLE-REPORT.md">report</a> shows 0 scene cuts and a first-to-last frame SSIM of 0.97, so it loops. <a href="examples/08-brief-becomes-world/README.md"><b>Make it yourself and check it</b></a> · <a href="assets/example08-five-worlds.mp4">Full-quality MP4 with sound</a>.</p><p align="center"><b>▶ The 90-second story:</b> three AIs, one brief, and why brief2mp4 checks its own work. Press play, sound on.</p>@@ -219,7 +219,7 @@ Every download is checked before anything is unpacked: its SHA-256 must match bo| 05 | [2D explainer](examples/05-2d-explainer/BRIEF.md): "How a cache works" | HyperFrames | 20 s || 06 | [Vertical Short](examples/06-vertical-short/BRIEF.md): "3 easing rules", 1080x1920 with safe zones | HyperFrames | 15 s || 07 | [Edited tutorial](examples/07-edit-tutorial/BRIEF.md): two clips cut together with a title and a ducked voice-over mix | edit pack + HyperFrames | 14 s |-| 08 | [Five worlds](examples/08-brief-becomes-world/BRIEF.md): a brief's words become a 3D city, a 2D chart world and a galaxy in one camera move ([sample report](examples/08-brief-becomes-world/SAMPLE-REPORT.md), [video](assets/example08-five-worlds.mp4)) | HyperFrames + Three.js | 25 s |+| 08 | [Five worlds](examples/08-brief-becomes-world/BRIEF.md): a brief's words become a 3D city, a 2D chart world and a galaxy in one camera move ([how to make and check it](examples/08-brief-becomes-world/README.md), [sample report](examples/08-brief-becomes-world/SAMPLE-REPORT.md), [video](assets/example08-five-worlds.mp4)) | HyperFrames + Three.js | 25 s |## Write a briefdiff --git a/examples/08-brief-becomes-world/README.md b/examples/08-brief-becomes-world/README.mdnew file mode 100644index 0000000..c907dcc--- /dev/null+++ b/examples/08-brief-becomes-world/README.md@@ -0,0 +1,65 @@+# Example 08: one brief, five worlds++<p align="center">+ <img src="../../assets/example08-five-worlds.webp" alt="The words of a brief lift off the page into a 3D city, the camera flies into a 2D chart world, rides a bar up into a galaxy, and the galaxy becomes the full stop in brief2mp4." width="100%">+</p>++This is the video at the top of the brief2mp4 README, and this page shows how to make it yourself and how to check it. It is 25 seconds and one camera move with no cuts. The words of a brief peel off the page, become a 3D city of light, the camera flies through a window into a flat 2D chart world, rides a growing bar up into a galaxy of 27,000 particles, and the galaxy shrinks into the full stop of the title. The last frame matches the first, so it loops.++It uses most of what the skill can do in one piece: 2D type and charts in HyperFrames with GSAP, 3D and particles in Three.js, a soundtrack, and finishing with ffmpeg. [Watch the MP4 with sound](../../assets/example08-five-worlds.mp4).++## What is in this folder++| File | What it is |+|---|---|+| [BRIEF.md](BRIEF.md) | The brief, exactly as it was pasted. Copy this. |+| [SAMPLE-REPORT.md](SAMPLE-REPORT.md) | The report the skill wrote for the video above: every line of the brief marked met or not met, with the measurement or still behind it, render settings and open points. |+| [check.sh](check.sh) | Runs every check from the brief's "Done when" list on your own `final.mp4`. |+| [hue_scan.py](hue_scan.py) | Used by `check.sh` to show that no part of the frame turns teal or mint. |++## Make it++1. Install brief2mp4 (see [Quick start](../../README.md#quick-start)) and run the doctor once. You need Node.js 22+ and ffmpeg. The 3D pack and Blender are not needed: all of the 3D here is Three.js.+2. Make an empty folder for the video and open Claude Code or Codex in it.+3. Send this, then paste the whole of [BRIEF.md](BRIEF.md) under it:++ > Use the brief2mp4 skill to make the video in this brief:++4. Let it work. It writes `SPEC.md` first, builds the page, the city, the chart world and the galaxy in one HyperFrames composition, snapshots stills, renders, finishes with ffmpeg and writes `REPORT.md`. Expect a longer run than the 12-second examples, because there are five worlds to build and check.+5. When it says it is done, send:++ > Check it against the brief.++ It goes back to the brief line by line, shows the evidence for each line, fixes what falls short and renders again.++Your video will not be pixel-identical to ours. The brief fixes the words, the timing, the palette and the checks, and leaves the details of each world to the agent. The checks below are what every version has to pass.++## Check it++Run the checks in your video's folder:++```bash+bash /path/to/brief2mp4/examples/08-brief-becomes-world/check.sh final.mp4+```++It finds the skill's scripts on its own (pass the scripts folder as a second argument if it cannot), writes stills to `./checks` and prints one block per check. These are the numbers from the video above:++| Check | Command inside `check.sh` | Pass when | Our video |+|---|---|---|---|+| Size, frame rate, length, codecs, loudness | `check_delivery.sh final.mp4 --seconds 25 --size 1920x1080 --fps 30 --lufs -16` | `RESULT: PASS` | PASS, -15.3 LUFS |+| No cuts in the camera move | ffmpeg `scdet=threshold=10` | 0 scene cuts | 0 |+| It loops | SSIM of the first frame vs the last | 0.90 or more | 0.973 |+| The title is big and holds still | `bounds.py` on the stills at 20.5, 22.0 and 23.5 s | box 150 px or taller, same box each time | 290 px, identical |+| Type stays off the edges | `bounds.py --margin 64,64` at 22.0 s | `"inside": true` | true |+| No teal or mint | `hue_scan.py` over every still | a fraction of a percent, no region | 0.0009 % at most |++Then open the stills in `./checks`, because some lines of a brief can only be checked by looking. At 1.8 s at least one word of the second line should be off the page. At 6.0 s you should see the city, at 11.5 s the chart world, at 17.0 s the galaxy and at 22.0 s the title, each in the colours of the brief's palette table. The five chips in the bottom-left corner, one per world, should read exactly as the brief writes them.++## Make your own version++The brief is built to be edited. Keep its shape and change what you like:++- **Change the worlds.** Swap the city for a forest, or the galaxy for an ocean. Keep one "what happens when" step per world, with a time range and the colours it uses.+- **Keep the handoffs physical.** The no-cuts check passes because every world is entered by moving the camera (into a window, up a bar, into a point of light), never by cross-fading. Write each transition as a camera move.+- **Keep the palette table.** One row per world, with exact hex codes, is what makes the colour bold and still under control. A "never use" line (here: teal and mint) gives the check something to measure.+- **Keep the Done-when list measurable.** Every line should name a frame or a number: a still at a time, a cut count, an SSIM, a size in pixels, a loudness. Those numbers are what make "Check it against the brief." useful.diff --git a/examples/08-brief-becomes-world/check.sh b/examples/08-brief-becomes-world/check.shnew file mode 100755index 0000000..4a9f21d--- /dev/null+++ b/examples/08-brief-becomes-world/check.sh@@ -0,0 +1,44 @@+#!/usr/bin/env bash+# check.sh: run every "Done when" check of brief 08 on your own render.+# Usage: bash check.sh <path/to/final.mp4> [brief2mp4 scripts folder]+# Writes stills to ./checks next to where you run it. Needs ffmpeg, ffprobe, python3.+set -u+F="${1:?usage: bash check.sh final.mp4 [brief2mp4 scripts folder]}"+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+S="${2:-}"+if [ -z "$S" ]; then+ for d in "$HOME/.claude/skills/brief2mp4/scripts" "$HOME/.codex/skills/brief2mp4/scripts" "$HERE/../../plugin/skills/brief2mp4/scripts"; do+ [ -f "$d/check_delivery.sh" ] && S="$d" && break+ done+fi+[ -f "${S:-}/check_delivery.sh" ] || { echo "brief2mp4 scripts folder not found; pass it as the second argument"; exit 1; }+mkdir -p checks+LAST=$(( $(ffprobe -v error -count_frames -select_streams v:0 -show_entries stream=nb_read_frames -of csv=p=0 "$F") - 1 ))++echo "## 1. Delivery: 1920x1080, 30 fps, 25.0 s, H.264 + AAC, loudness -16 LUFS +/- 1"+bash "$S/check_delivery.sh" "$F" --seconds 25 --size 1920x1080 --fps 30 --lufs -16++echo; echo "## 2. Stills to open and look at (word peel 1.8 s, city 6 s, charts 11.5 s, galaxy 17 s, title 22 s)"+bash "$S/contact_sheet.sh" "$F" --at 0,1.8,3,6,9,11.5,14,17,20,20.5,22,23.5,24.9 --out checks++echo; echo "## 3. No cuts: scene changes found by scdet at threshold 10 (want 0)"+ffmpeg -hide_banner -nostats -i "$F" -vf "scdet=threshold=10" -an -f null - 2>&1 | grep -c "lavfi.scd.time"++echo; echo "## 4. Loop: SSIM of the first frame vs the last frame (want 0.90 or more)"+ffmpeg -v error -y -i "$F" -vf "select=eq(n\,0)" -frames:v 1 checks/first.png+ffmpeg -v error -y -i "$F" -vf "select=eq(n\,$LAST)" -frames:v 1 checks/last.png+ffmpeg -hide_banner -nostats -i checks/first.png -i checks/last.png -lavfi ssim -f null - 2>&1 | grep -o "All:[0-9.]*"++echo; echo "## 5. Title: ink box at 20.5, 22.0 and 23.5 s (want 150 px or taller, same box each time)"+for t in 020.50 022.00 023.50; do+ ffmpeg -v error -y -i "checks/t_${t}s.png" -vf "format=gray,lut=y='if(gt(val,150),255,0)'" "checks/bin_$t.png"+ python3 "$S/bounds.py" "checks/bin_$t.png" --bg "#000000" --region 100,300,1820,625 | head -1+done++echo; echo "## 6. Margins: all type at 22.0 s inside 64 px of the frame edge"+python3 "$S/bounds.py" checks/bin_022.00.png --bg "#000000" --margin 64,64 | head -1++echo; echo "## 7. No teal or mint: share of teal/mint-hue pixels per still (want a fraction of a percent, no region)"+python3 "$HERE/hue_scan.py" "$S/bounds.py" checks/t_0*.png | tail -1++echo; echo "Now open the stills in ./checks and read the five chip texts and the title against BRIEF.md."diff --git a/examples/08-brief-becomes-world/hue_scan.py b/examples/08-brief-becomes-world/hue_scan.pynew file mode 100755index 0000000..320778d--- /dev/null+++ b/examples/08-brief-becomes-world/hue_scan.py@@ -0,0 +1,18 @@+#!/usr/bin/env python3+"""hue_scan.py: count pixels whose hue reads as teal, mint or cyan-green (hue 140-190 deg) with real+saturation and brightness. Uses the PNG reader from the skill's bounds.py. Usage: hue_scan.py BOUNDS_PY still.png ..."""+import sys, colorsys, importlib.util+spec = importlib.util.spec_from_file_location("bounds", sys.argv[1]); b = importlib.util.module_from_spec(spec); spec.loader.exec_module(b)+worst = 0+for path in sys.argv[2:]:+ w, h, ch, rows = b.read_png(path)+ n = 0; tot = 0+ for row in rows:+ for x in range(0, w * ch, ch * 2): # every second pixel+ r, g, bl = row[x], row[x + 1], row[x + 2]+ tot += 1+ hh, s, v = colorsys.rgb_to_hsv(r / 255, g / 255, bl / 255)+ if 140 <= hh * 360 <= 190 and s > 0.35 and v > 0.3: n += 1+ worst = max(worst, n / tot)+ print(f"{path}: teal/mint-hue pixels {n} of {tot} sampled ({100 * n / tot:.4f}%)")+print(f"worst still: {100 * worst:.4f}%")