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 hero, one brief through five worlds in one camera move
Varun Pratap Bhardwaj8c3f5114ce15
diff --git a/.gitignore b/.gitignoreindex e507f97..0e9d609 100644--- a/.gitignore+++ b/.gitignore@@ -16,3 +16,4 @@ renders/venv/.venv/.pytest_cache/+!assets/example08-five-worlds.mp4diff --git a/README.md b/README.mdindex 72431c7..abb78db 100644--- a/README.md+++ b/README.md@@ -28,6 +28,16 @@<a href="#faq">FAQ</a></p>+<p align="center">+ <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>▶ The 90-second story:</b> three AIs, one brief, and why brief2mp4 checks its own work. Press play, sound on.</p>++https://github.com/user-attachments/assets/8e975937-03d7-4648-b527-19b712c7e6c8+| You give it | You get back ||---|---|| A written brief: length, size, the exact words on screen, what happens when, and a "done when" list. | `final.mp4`, plus a `REPORT.md` that goes through your brief line by line with the measurement or still that backs each one. Example 01's report shows a 126 px headline against a 120 px minimum. |@@ -209,6 +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 |## Write a briefdiff --git a/assets/example08-five-worlds.mp4 b/assets/example08-five-worlds.mp4new file mode 100644index 0000000..ae5a339Binary files /dev/null and b/assets/example08-five-worlds.mp4 differdiff --git a/assets/example08-five-worlds.webp b/assets/example08-five-worlds.webpnew file mode 100644index 0000000..62b55e7Binary files /dev/null and b/assets/example08-five-worlds.webp differdiff --git a/examples/08-brief-becomes-world/BRIEF.md b/examples/08-brief-becomes-world/BRIEF.mdnew file mode 100644index 0000000..8ad7c5b--- /dev/null+++ b/examples/08-brief-becomes-world/BRIEF.md@@ -0,0 +1,64 @@+# Brief 08: one brief, five worlds++Make a 25-second shot in which the words of a brief turn into the worlds they describe. The camera never cuts. It travels from a flat page of text, through a 3D city, into a 2D chart world, out into a galaxy and back to the page. Each world shows a different thing the skill can do, and the last frame loops back to the first.++- Delivery: final.mp4, 1920x1080, 30 fps, exactly 25.0 s, H.264 + AAC.+- Typefaces: JetBrains Mono for the brief text, Space Grotesk Bold for every other word (both Google Fonts).+- Route: HyperFrames for the 2D type and charts, Three.js for the 3D worlds, all in one composition, so the camera can pass from one world into the next without a cut. ffmpeg finishes the file.+- Never use teal or mint anywhere, not even as a shade.++## Palette++Each world has its own colour key. Use only these hex codes, their shades and their mixes.++| World | Dominant | Accents |+|---|---|---|+| 1. The page | midnight indigo #14112B | paper #F2EDE4 text, saffron #FFB000 cursor |+| 2. The city of light | dusk violet #2A1B5C sky | saffron #FFB000 towers, coral #FF5A1F street lights, magenta #E0338A haze |+| 3. The chart world | paper #F2EDE4 | ink #16130F, coral #FF5A1F, violet #7B5CFF, saffron #FFB000 |+| 4. The galaxy | deep space #07060F | magenta #E0338A arms, violet #7B5CFF dust, saffron #FFB000 core, sky blue #3FA9F5 stars |+| 5. The title | midnight indigo #14112B | paper #F2EDE4 title, saffron-to-coral gradient on the underline |++## What happens when++1. **The page, 0.0-3.0 s (2D type).** A dark page fills the frame. From the first frame it shows three lines in paper colour, 56 px, with a blinking saffron cursor after the last one:+ - `# brief.md`+ - `A city of light rises out of these words.`+ - `Camera: one move, no cuts.`++ From 1.0 s the words of the second line peel off the page one at a time and extrude into glowing saffron 3D blocks. The first word has left the page plane by 1.8 s.+2. **The city of light, 3.0-9.0 s (3D).** The blocks drop and stack into a city of at least 60 glowing towers under a violet dusk sky with magenta haze and soft fog. Place the towers with a seeded random generator so every render is identical. The camera tilts down from the page and flies low down the main street between the towers. Bloom only on the lit windows and street lights.+3. **The chart world, 9.0-14.0 s (2D motion graphics).** The camera flies into one lit window, and the window opens into a flat paper-coloured world: an animated bar chart of five bars growing in sequence (coral, violet, saffron, coral, violet), a line that draws itself across them, and three flat icons that pop in (a play button, a frame, a speaker). Everything is crisp flat 2D, on a plane inside the scene.+4. **The galaxy, 14.0-20.0 s (3D particles).** The tallest bar keeps growing upwards, and the camera rides it up through the top of the frame into deep space. The camera pulls back through a spiral galaxy of at least 20,000 particles (magenta arms, violet dust, saffron core, sky-blue stars), turning slowly.+5. **The title, 20.0-23.5 s.** The galaxy shrinks to a single saffron point, which becomes the dot of the full stop in "brief2mp4." in Space Grotesk Bold, at least 150 px tall, paper colour. Under it, at 48 px: "paste a brief, get this". A saffron-to-coral underline draws in under the title. The title holds still and fully readable from 20.5 to 23.5 s.+6. **Back to the page, 23.5-25.0 s.** The title fades, the camera settles to the exact framing of the first frame, and the three brief lines are back, so the video loops with no visible jump.++## Capability chips++A small chip in the bottom-left corner names what each world is made with, so a viewer learns the routes while watching. Chips are 32 px Space Grotesk on a dark rounded pill, at least 64 px from the frame edges, each cross-fading into the next:++| Time | Chip text, exactly |+|---|---|+| 0.3-3.0 s | `2D type · HyperFrames` |+| 3.0-9.0 s | `3D city · Three.js` |+| 9.0-14.0 s | `2D charts · HyperFrames + GSAP` |+| 14.0-20.0 s | `20,000 particles · Three.js` |+| 20.0-23.5 s | `finished · ffmpeg` |++## Rules++- One continuous camera move from the first frame to the last. No cuts and no fades to black.+- Text never touches the frame edge (at least 64 px margin). Nothing important is cut off at any time.+- Sound: a soundtrack with a soft rise in each world, a light accent when the first word lifts (about 1.2 s), a whoosh into each new world (3.0, 9.0 and 14.0 s) and a low accent when the title lands (20.0 s). Loudness -16 LUFS integrated.++## Done when++- ffprobe reports 1920x1080, 30 fps, 25.0 s, H.264 + AAC.+- A still at 1.8 s shows at least one word of the second line off the page plane.+- Stills at 6.0, 11.5, 17.0 and 22.0 s show the city, the chart world, the galaxy and the title, in the colours of the palette table.+- ffmpeg scene-cut detection (`scdet`) finds no cut anywhere in the video.+- The first and last frames match: SSIM at least 0.90.+- The title is at least 150 px tall, and still and readable from 20.5 to 23.5 s.+- All five chip texts appear exactly as written, each readable in at least one still.+- No pixel region reads as teal or mint in any still.+- Integrated loudness is -16 LUFS, within 1 LU.diff --git a/examples/08-brief-becomes-world/SAMPLE-REPORT.md b/examples/08-brief-becomes-world/SAMPLE-REPORT.mdnew file mode 100644index 0000000..0e9efd8--- /dev/null+++ b/examples/08-brief-becomes-world/SAMPLE-REPORT.md@@ -0,0 +1,59 @@+# REPORT: Brief 08, one brief, five worlds++`final.mp4`: 25.0 s, 1920x1080, 30 fps, H.264 + AAC. One camera move through the page, the city, the chart world, the galaxy and the title, looping back to the first frame. Brief used exactly as written (`BRIEF.md`, the upgraded 25 s version). Every number below is in `checks.txt`, produced by `bash run_checks.sh <skill>/scripts`.++## Delivery check+`check_delivery.sh final.mp4 --seconds 25 --size 1920x1080 --fps 30` ends with `RESULT: PASS (final.mp4)` (12 PASS lines, no WARN, no FAIL).++## Done when (from the brief)+| Line | Result | Evidence |+|---|---|---|+| ffprobe reports 1920x1080, 30 fps, 25.0 s, H.264 + AAC | met | `codec_name=h264 width=1920 height=1080 r_frame_rate=30/1 nb_frames=750`, `codec_name=aac sample_rate=48000 channels=2`, `duration=25.000000` |+| Still at 1.8 s shows a word of line 2 off the page | met | `checks/t_001.80s.png`: "A", "city", "of", "light", "rises" are lifted tiles with saffron side walls and a glow under them; "out of these words." still flat on the page |+| Stills at 6.0, 11.5, 17.0, 22.0 s show city, chart, galaxy, title in palette colours | met | `checks/t_006.00s.png` (saffron towers, violet sky, magenta haze, coral street lights), `t_011.50s.png` (paper, coral/violet/saffron bars, ink line), `t_017.00s.png` (magenta arms, violet dust, saffron core, sky-blue stars on deep space), `t_022.00s.png` (paper title on indigo, saffron-to-coral underline) |+| scdet finds no cut | met | `scdet=threshold=10` (ffmpeg default): 0 cuts. Highest per-frame score in the whole file 4.249 at 8.87 s (the flight through the window); next 2.926 at 16.17 s |+| First and last frames match, SSIM >= 0.90 | met | frame 0 vs frame 749: `SSIM All:0.972693`. Command: `ffmpeg -i checks/first.png -i checks/last.png -lavfi ssim -f null -` |+| Title at least 150 px tall, still and readable 20.5-23.5 s | met | `bounds.py` on the binarised still (underline excluded): ink box 1604 x 290 px (clipped at the underline; font-size 320 px), identical box `x 164-1767, y 335-624` at 20.5, 22.0 and 23.5 s. SSIM of the binarised title area 20.5 vs 23.5 s: 0.998592 |+| All five chip texts exact, each readable in a still | met | `2D type · HyperFrames` in `t_001.80s.png`; `3D city · Three.js` in `t_006.00s.png`; `2D charts · HyperFrames + GSAP` in `t_011.50s.png`; `20,000 particles · Three.js` in `t_017.00s.png`; `finished · ffmpeg` in `t_022.00s.png`. Text comes from the `CHIPS` array in `city-layout.js`, copied from the brief |+| No pixel region reads as teal or mint | met | `hue_scan.py` over all 21 stills (hue 140-190 degrees, saturation > 0.35, value > 0.3): worst still 0.0009 % of sampled pixels (a handful of single compressed pixels at star edges, no region). I also looked at every still |+| Integrated loudness -16 LUFS within 1 LU | met | `I: -15.3 LUFS`, true peak -1.5 dBTP. See the loudness note below |++## Other lines of the brief+| Line | Result | Evidence |+|---|---|---|+| Frame 0: three lines, 56 px, paper, blinking saffron cursor | met | `t_000.00s.png`; CSS 112 px at 0.5 scale; cursor on for half of every second |+| Words peel from 1.0 s, first off the page by 1.8 s | met | first word starts 1.0 s, fully lifted 1.7 s |+| At least 60 towers, seeded | met | `node check_layout.mjs`: 67 city towers + 1 end tower, seed 20261116, second run identical |+| Bloom only on lit windows and street lights | mostly met | bloom threshold 0.9 in the city; walls, edges, sky and sun are under it. The coral beacon masts on some roofs also bloom |+| Five bars in sequence (coral, violet, saffron, coral, violet), a drawn line, three icons | met | `t_011.50s.png`, `t_013.50s.png`, `t_014.00s.png` |+| Chart is flat 2D on a plane inside the scene | met | HTML/SVG sheet placed with the camera matrix on the wall behind the window; camera stops square-on at 1 unit = 1 px |+| Tallest bar grows, camera rides it into space | met | `t_015.20s.png`, `t_016.20s.png`, `t_017.00s.png` |+| At least 20,000 particles | met | 27,000 (14,000 arm, 7,000 dust, 2,500 core, 3,500 stars), seeded |+| Galaxy shrinks to a saffron point that becomes the full stop | met | `t_019.60s.png`, `t_020.00s.png` (point sits where the full stop is in `t_020.50s.png`) |+| Subtitle 48 px, underline saffron to coral | met | CSS 48 px Space Grotesk Bold; ink box 491 x 44 px |+| One continuous move, no cuts, no fades to black | met | scdet above; `check_delivery`: no black stretch |+| Text at least 64 px from the frame edge | met | title still: all bright type inside the 64 px zone (`inside: true`, box x 91-1767, y 335-998); chips are CSS `left: 64px; bottom: 64px` |+| Chips 32 px Space Grotesk on a dark pill, cross-fading | met | CSS; cross-fades are 0.4 s wide and centred on 3.0, 9.0, 14.0, 20.0 s |+| Sound: rise per world, accent 1.2 s, whooshes 3.0 / 9.0 / 14.0 s, low accent 20.0 s | met by construction | `make_audio.sh`. Levels measured, not listened to (see open points) |++## Loudness note+`finish.sh` defaults to -14 LUFS. I ran it with `--lufs -15.3`. That lands at -15.3 LUFS, which is inside the brief's -16 +/- 1 window (-17 to -15) and also inside the default window of `check_delivery.sh` (-14 +/- 1.5), so the check command passes as written without `--lufs`. With `--lufs -16` the same check also passes.++## Stills I opened and looked at+`checks/sheet.png` (all 21) and, at half size or larger, 0, 1.8, 3, 6, 8.7, 9, 11.5, 14, 17, 20, 22, 24.9 s. Also 13.5, 15.2, 16.2, 18.5, 19.6, 20.5, 23.5, 24.2 s on the sheet. Spelling of every line, chip and title checked against the brief.++## Render settings+- HyperFrames 0.8.216: `npx hyperframes render . -o render.mp4 --quality delivery --workers 8 --fps 30`. Render time 10.6 s (12 s wall) on the M5 Pro.+- three 0.170.0 and GSAP 3.15.0 vendored by `vendor_libs.sh`; UnrealBloomPass, EffectComposer and ShaderPass copied from the same three 0.170.0 package into `vendor/three-addons/`. Fonts vendored (JetBrains Mono, Space Grotesk). No network at render time.+- Determinism: `draw(t)` is the only source of a frame; mulberry32 seeds 20261116 (city), 77 (embers), 4242 (galaxy); no `Math.random`, no wall clock (the composer is called with a fixed delta).+- Finish: `finish.sh --in render.mp4 --out final.mp4 --seconds 25 --audio bed.wav --lufs -15.3` (H.264 CRF 18 slow, AAC 192k).+- Fix rounds used: 1 after the first full render (chart starts 0.3 s sooner). Before that, stills-only rounds fixed bloom strength, the wall top and the galaxy entry speed.+- The 3D pack was not used; all 3D is hand-built Three.js.++## Open points+1. The still at exactly 9.0 s is plain paper with the two chips mid cross-fade: the camera has just come through the window and the chart starts drawing at 9.1 s.+2. During each 0.4 s chip cross-fade the two texts overlap and are not readable. The brief asks for a cross-fade in one place, so I kept it.+3. Lines 1 and 3 of the brief leave the first page between 2.05 and 3.4 s, before the page beat ends at 3.0 s, because an HTML word cannot be hidden behind a 3D block.+4. During the title hold the type is still, but the faint ruled lines behind it drift slowly with the camera.+5. I judged stills and measurements only. Nobody has watched it in motion or listened to the soundtrack yet.+6. `hyperframes lint`: 0 errors, warnings only (one large composition file, nested timeline element).