{"slug": "show-hn-brief2mp4-claudecode-codex-skill-that-checks-videos-against-the-brief", "title": "Show HN: Brief2mp4 – ClaudeCode/Codex skill that checks videos against the brief", "summary": "Qualixar released brief2mp4, a free MIT-licensed agent skill for Claude Code and Codex that turns a written video brief into a finished MP4 and then checks the output against every line of that brief. The skill routes each beat to HyperFrames for type and 2D motion, Three.js for stylised 3D, an optional 3D pack for CAD models, materials and physics, and Blender for photoreal shots, then finishes with ffmpeg and returns final.mp4 plus a REPORT.md documenting evidence for each brief line; everything runs locally. In the project's run of example 01, the check pass caught headlines that cleared the 120 px minimum by only a few pixels, enlarged them and re-rendered.", "body_md": "**Text to motion graphics for Claude Code and Codex. Write a video brief, get a finished MP4 that has been checked against every line of it.**\n\n2D explainers · maths animations · tutorials · Shorts and Reels · data stories · product launches · logo stings · kinetic type · 3D products\n\n[Quick start](#quick-start) ·\n  [What it makes](#what-it-makes) ·\n  [How it works](#how-it-works) ·\n  [3D pack](#the-3d-pack) ·\n  [Edit pack](#the-edit-pack) ·\n  [Examples](#examples) ·\n  [Write a brief](#write-a-brief) ·\n  [Docs](https://github.com/qualixar/brief2mp4/blob/main/docs/README.md) ·\n  [FAQ](#faq)\n\nbrief2mp4 is a free, MIT-licensed agent skill. You paste a written brief (length, size, exact words, what happens when). The agent writes a spec with a checkable \"done when\" list, routes each beat to the right tool (HyperFrames for type and 2D motion, Three.js for stylised 3D, an optional 3D pack for CAD models, materials and physics, Blender for photoreal shots), renders, finishes the file with ffmpeg, measures it, looks at real frames, fixes what misses and hands you `final.mp4` with a `REPORT.md` that shows the evidence for every line. Everything runs on your own machine.\n\n**[▶ Watch the video](https://youtu.be/l9mEZQon6JM)**  ·  **[All 11 contest films, untouched](https://drive.google.com/drive/folders/1yBmCb2h63Fp5yr_37LY46f8BSRa_3GiO?usp=sharing)**  ·  **[Free 69-page guide](https://qualixar.com/learn/guides/brief2mp4-guide)**  ·  [How it was built](https://qualixar.com/research/blog/brief2mp4-deep-dive)\n\n**Fastest: let your agent set everything up.** Open Claude Code or Codex in any folder and send:\n\nSet up brief2mp4 from [https://github.com/qualixar/brief2mp4](https://github.com/qualixar/brief2mp4) by following its SETUP.md.\n\nThe agent detects your OS, asks before installing Node, ffmpeg (and Git Bash on Windows), installs the skill, runs the doctor and makes a 12-second test video so you know it works. [SETUP.md](https://github.com/qualixar/brief2mp4/blob/main/SETUP.md) is the exact script it follows.\n\n**Or install it yourself:**\n\n| You use | Run | \n|---|---|\n| Claude Code (plugin) | `/plugin marketplace add qualixar/brief2mp4` then`/plugin install brief2mp4@brief2mp4` | \n| Codex (plugin) | `codex plugin marketplace add qualixar/brief2mp4` then`codex plugin add brief2mp4@brief2mp4` | \n| macOS / Linux / WSL (both apps) | `git clone https://github.com/qualixar/brief2mp4.git && bash brief2mp4/install.sh` | \n| Windows PowerShell (both apps) | `git clone https://github.com/qualixar/brief2mp4.git; powershell -ExecutionPolicy Bypass -File .\\brief2mp4\\install.ps1 -InstallTools` | \n\nAdd the 3D pack with `--with-3d` (macOS/Linux) or `-With3D core` (Windows), and the edit pack with `--with-edit` or `-WithEdit film,sound`. Plugins install the skill only, so on a fresh machine also install the tools below. Start a new session after installing so the app loads the skill.\n\n**Then make a video.** In a folder for the video:\n\nUse the brief2mp4 skill to make the video in this brief: *(paste your brief)*\n\nWhen it says it is done, send one follow-up:\n\nCheck it against the brief.\n\nThat makes the agent go back to your original brief line by line, show the evidence for each line, fix what falls short and render again. In our run of example 01 it caught headlines that cleared the 120 px minimum by only a few pixels, enlarged them and rendered again.\n\n| Tool | Needed for | macOS | Windows | Ubuntu / Debian | \n|---|---|---|---|---|\n| Node.js 22+ | every video | `brew install node` | `winget install -e --id OpenJS.NodeJS.LTS` | [nodesource setup_22.x](https://github.com/nodesource/distributions) | \n| ffmpeg | every video | `brew install ffmpeg` | `winget install -e --id Gyan.FFmpeg` | `sudo apt install ffmpeg` | \n| Git Bash | Windows only (the scripts are bash) |  | `winget install -e --id Git.Git` |  | \n| Blender 4.2+ | photoreal shots (optional) | `brew install --cask blender` | `winget install -e --id BlenderFoundation.Blender` | [blender.org/download](https://www.blender.org/download) | \n| Python 3.12 or 3.13 | the 3D pack (optional) | `brew install python@3.12` | `winget install -e --id Python.Python.3.12` | Ubuntu 24.04: `sudo apt install python3 python3-venv` (Debian 12 ships 3.11:`uv python install 3.12` , then install with`B2M3D_PYTHON=\"$(uv python find 3.12)\"` , see[uv](https://docs.astral.sh/uv/) ) | \n\nCheck a machine at any time with `bash plugin/skills/brief2mp4/scripts/doctor.sh`. It prints `ok` or the exact install command for each tool.\n\nRound 4 of the video: Fable 5.2 in Claude Code got a written brief for a 60-second film, one continuous camera move through four worlds with its own music, and delivered this. That was a sealed contest run made without this skill; brief2mp4 packages the same loop (spec, build, measure, check every line, fix) so you can run it on your own briefs. The [full films](https://drive.google.com/drive/folders/1yBmCb2h63Fp5yr_37LY46f8BSRa_3GiO?usp=sharing) are untouched, with checksums.\n\n| Format | What the skill does for it | Route | \n|---|---|---|\n| **2D explainers** (YouTube, courses) | hook, setup, three-step idea, example, takeaway; diagrams that draw on, labels word by word | HyperFrames | \n| **Maths and algorithms** | equations term by term, colour-coded to the picture; one transformation per beat | HyperFrames + KaTeX, or [Manim](https://github.com/ManimCommunity/manim) inserts | \n| **Tutorial intros and callouts** | title and chapter cards, callouts and zooms over your screen recording | HyperFrames + your recording | \n| **Stories and skits** | situation, want, obstacle, turn; timing pauses before the punchline; captions to the voice | HyperFrames, SVG, Lottie or Rive characters | \n| **YouTube Shorts, Reels, TikTok** | 9:16 safe zones, a hook in the first frame, a change every 2-4 s, loopable endings | HyperFrames | \n| **Data stories** | charts that draw from the baseline, numbers that count to the exact value | HyperFrames + SVG/D3 | \n| **Product launches** | problem, reveal, features, call to action; real UI recreated sharp | HyperFrames, 3D pack, Blender | \n| **Logo stings and titles** | build-up, resolve on the sound accent, hold | HyperFrames, 3D pack | \n| **Kinetic type and lyric videos** | words timed to measured audio, stress shown with scale and weight | HyperFrames | \n| **Stylised 3D** | planets, particles, abstract shapes, flying cameras | Three.js | \n| **3D products with physics** | parts that drop and settle, exploded views, turntables | 3D pack | \n| **Photoreal shots** | glass, metal, soft shadows | Blender | \n\nExamples 05 (a 20 s explainer) and 06 (a 15 s vertical Short), each made by running the skill on the brief as written: both passed `check_delivery.sh`, and their [sample](https://github.com/qualixar/brief2mp4/blob/main/examples/05-2d-explainer/SAMPLE-REPORT.md) [reports](https://github.com/qualixar/brief2mp4/blob/main/examples/06-vertical-short/SAMPLE-REPORT.md) list the evidence for every line, including the fixes the self-check forced.\n\nEvery format has a beat sheet, a route and its own checks in [references/formats.md](https://github.com/qualixar/brief2mp4/blob/main/plugin/skills/brief2mp4/references/formats.md), which the agent reads when your brief names the kind of video.\n\n**Proof the skill works:** example brief 01, pasted as written, came back as a 12.000 s, 1920x1080, 30 fps file that passed the delivery check. Its [report](https://github.com/qualixar/brief2mp4/blob/main/examples/01-kinetic-type/SAMPLE-REPORT.md) lists every requirement with its evidence: which still shows which line, the measured headline height (126 px against a 120 px minimum), the text bounds and the loudness at each sound accent.\n\n1. **Spec.** Before any code the agent writes`SPEC.md` : size, frame rate, exact duration, codecs and loudness; every on-screen word copied exactly; the palette; a beat sheet with times; and a \"done when\" list with one checkable line per requirement.\n2. **Route and build.** Each beat goes to the tool that fits it, starting from templates that already render. HyperFrames is the spine where every layer meets on one timeline.\n3. **Self-check.**`check_delivery.sh` measures the file (PASS, WARN or FAIL).`contact_sheet.sh` pulls stills at the important moments, and the agent views them and marks every \"done when\" line met or not met, with evidence.\n4. **Fix.** Worst miss first, render again, up to three rounds.\n5. **Deliver.**`final.mp4` and a`REPORT.md` that says what was checked, how, and what is still open.\n\n| The beat needs | Tool | Licence | \n|---|---|---|\n| Type, layouts, UI, charts, 2D motion | [HyperFrames](https://github.com/heygen-com/hyperframes) (HTML, CSS and[GSAP](https://github.com/greensock/GSAP) to MP4) | Apache-2.0 | \n| Stylised 3D, particles, camera moves | [Three.js](https://github.com/mrdoob/three.js) inside HyperFrames, seeked by time | MIT | \n| CAD models, materials, physics, exploded views | the optional [3D pack](#the-3d-pack) | MIT and Apache-2.0 parts | \n| Realistic products, materials, soft light | [Blender](https://www.blender.org) , scripted in Python, headless | GPL (external tool) | \n| Sound, joins, exact length, loudness, encoding | [ffmpeg](https://ffmpeg.org) | LGPL/GPL (external tool) | \n\nMixed briefs, recipes for each mix and the architecture in detail: [docs/architecture.md](https://github.com/qualixar/brief2mp4/blob/main/docs/architecture.md) for people, [references/pipelines.md](https://github.com/qualixar/brief2mp4/blob/main/plugin/skills/brief2mp4/references/pipelines.md) for the agent.\n\nExample 04, rendered by the 3D pack on a laptop: five parts drop and settle with baked rigid-body physics, open into an exploded view, and the title lands. 8 seconds of 1080p rendered in about 5 seconds; `check_delivery.sh` passes.\n\nAn optional layer for briefs with 3D products. It turns a CAD or mesh spec into a GLB, applies material presets, bakes rigid-body physics once so every render frame is identical, writes a self-contained HyperFrames project from a short shot JSON, and renders photoreal hero shots through Blender. The skill detects it; without it, 3D beats use the Three.js template.\n\n| Component | What it adds | Built on | \n|---|---|---|\n| `core` | models from mesh specs, material presets, physics bakes, GLB optimisation, shot JSON to HyperFrames | [three.js](https://github.com/mrdoob/three.js) ,[glTF-Transform](https://github.com/donmccurdy/glTF-Transform) ,[meshoptimizer](https://github.com/zeux/meshoptimizer) ,[Jolt Physics](https://github.com/jrouwe/JoltPhysics) ,[Manifold](https://github.com/elalish/manifold) ,[trimesh](https://github.com/mikedh/trimesh) | \n| `cad` | exact parametric parts: enclosures, gears, brackets | [CadQuery](https://github.com/CadQuery/cadquery) | \n| `blender` | photoreal hero renders on the GPU (Metal, OptiX, CUDA or CPU) | your installed [Blender](https://www.blender.org) | \n\n```\nbash install.sh --with-3d              # core\nbash install.sh --with-3d=core,cad     # core + CadQuery\npowershell -ExecutionPolicy Bypass -File .\\install.ps1 -With3D core,cad\n```\n\nThe brief does the asking. \"Parts fall and settle\" becomes a physics bake with a camera that frames the landing zone; \"show what's inside\" becomes an exploded view; \"hero product\" becomes a Blender render with a dramatic light rig. The full mapping, the shot JSON and the look rules are in [3d/README-3D.md](https://github.com/qualixar/brief2mp4/blob/main/plugin/skills/brief2mp4/3d/README-3D.md).\n\nMotion graphics are half of a video. The other half is editing: cutting your screen recording or footage on a timeline, mixing a voiceover over music so the music ducks when you speak, compositing titles, making the thumbnail. The optional edit pack installs the command-line tools of five free, open-source desktop editors, the ArtCraft apps by [storytold](https://github.com/storytold) (MIT or Apache-2.0, at your option), so Claude Code or Codex can do that work too, headless, and hand the result to the same checks.\n\n| Component | App | Like | The agent uses it for | Tested recipe | \n|---|---|---|---|---|\n| `film` | [FilmCraft](https://github.com/storytold/filmcraft) 0.20.1 | Premiere | cutting clips on a timeline, transitions, titles, export | `film_timeline.sh` | \n| `sound` | [SoundCraft](https://github.com/storytold/soundcraft) 0.20.1 | a DAW | voice + music mix, ducking with automation, bounce | `sound_mix.sh` | \n| `effect` | [EffectCraft](https://github.com/storytold/effectcraft) 0.24.1 | After Effects | layered, keyframed compositing and titles | `effect_title.sh` | \n| `photo` | [PhotoCraft](https://github.com/storytold/photocraft) 0.23.1 | Photoshop | thumbnails, title cards | `photo_thumbnail.sh` | \n| `vector` | [VectorCraft](https://github.com/storytold/vectorcraft) 0.24.1 | Illustrator | logos and lower thirds as SVG | `vector_lower_third.sh` | \n\n```\nbash install.sh --with-edit                                  # film + sound\nbash install.sh --with-edit=film,sound,effect,photo,vector   # all five, about 420 MB download on macOS\npowershell -ExecutionPolicy Bypass -File .\\install.ps1 -WithEdit film,sound\n```\n\nEvery download is checked before anything is unpacked: its SHA-256 must match both the release's `SHA256SUMS.txt` and the hash pinned in this repository, and when `gpg` is installed the release signature must verify against the pinned signing-key fingerprint. Versions are pinned because these apps are alpha and move fast; the skill tells the agent to look up each app's real commands (`<app>-cli commands`) before using one a recipe does not cover. Details, sizes per platform and uninstall: [edit/README-EDIT.md](https://github.com/qualixar/brief2mp4/blob/main/plugin/skills/brief2mp4/edit/README-EDIT.md).\n\n| # | Brief | Route | Length | \n|---|---|---|---|\n| 01 | [Kinetic type](https://github.com/qualixar/brief2mp4/blob/main/examples/01-kinetic-type/BRIEF.md) : \"Finish something today\" ([sample report](https://github.com/qualixar/brief2mp4/blob/main/examples/01-kinetic-type/SAMPLE-REPORT.md) ) | HyperFrames | 12 s | \n| 02 | [Three.js](https://github.com/qualixar/brief2mp4/blob/main/examples/02-threejs-orbit/BRIEF.md) : a low-poly planet, three moons, \"ORBIT\" | Three.js in HyperFrames | 10 s | \n| 03 | [Blender](https://github.com/qualixar/brief2mp4/blob/main/examples/03-blender-product/BRIEF.md) : a smart-speaker turntable, \"LISTEN.\" | Blender | 8 s | \n| 04 | [3D product](https://github.com/qualixar/brief2mp4/blob/main/examples/04-3d-product/BRIEF.md) : parts drop and settle, explode, title | 3D pack | 8 s | \n| 05 | [2D explainer](https://github.com/qualixar/brief2mp4/blob/main/examples/05-2d-explainer/BRIEF.md) : \"How a cache works\" | HyperFrames | 20 s | \n| 06 | [Vertical Short](https://github.com/qualixar/brief2mp4/blob/main/examples/06-vertical-short/BRIEF.md) : \"3 easing rules\", 1080x1920 with safe zones | HyperFrames | 15 s | \n| 07 | [Edited tutorial](https://github.com/qualixar/brief2mp4/blob/main/examples/07-edit-tutorial/BRIEF.md) : two clips cut together with a title and a ducked voice-over mix | edit pack + HyperFrames | 14 s | \n\nThe agent guesses less when the brief says more. A brief that works well has these parts:\n\n```\nLength and size: 15 s, 1920x1080, 30 fps.\nLook: background #F2EDE4, text #16130F, one accent #FF5A1F. Font: Space Grotesk Bold.\nWords on screen, exactly: \"First line.\" / \"Second line.\" / \"Last line.\"\nWhat happens when:\n- 0.0 to 4.0 s: the first line types on, one word at a time.\n- 4.0 s: a hard cut to the second line.\n- 9.0 s: the last line lands and holds still until the end.\nSound: a quiet bed with a low hit at 4.0 s.\nDone when: every line is readable, nothing touches the frame edge, headlines are at least 100 px tall.\n```\n\nThe \"done when\" lines matter most, because they are what the self-check measures. The [free 69-page field guide](https://qualixar.com/learn/guides/brief2mp4-guide) goes through brief writing, every format, each tool, the 3D and edit packs and the checks in detail, and includes every brief and setting from the contest in the video. The [technical deep dive](https://qualixar.com/research/blog/brief2mp4-deep-dive) explains the engineering: determinism, baked physics, the loudness loop and the self-check.\n\nbrief2mp4 sits on top of the tools below rather than replacing them. The table compares scope as each project describes itself.\n\n|  | brief2mp4 | [HyperFrames skills](https://github.com/heygen-com/hyperframes) | [Remotion skills](https://github.com/remotion-dev/skills) | Prompting an agent with no skill | \n|---|---|---|---|---|\n| Input | a written brief | a request | a request in a Remotion project | a request | \n| Writes a spec with a checkable done-when list | yes |  |  |  | \n| Routes beats across HyperFrames, Three.js, a 3D pack and Blender | yes | HyperFrames | Remotion | whatever the agent picks | \n| Measures the delivered file (duration, size, codecs, loudness) | yes, PASS/WARN/FAIL |  |  |  | \n| Looks at frames and reports evidence per brief line | yes, `REPORT.md` | lint and preview |  |  | \n| Physics and CAD 3D | optional 3D pack |  |  |  | \n| Licence | MIT | Apache-2.0 | see repo; Remotion has its own licence |  | \n\nThey work well together: install the HyperFrames skills next to brief2mp4 for deeper HyperFrames know-how, and the agent uses both. For more than 45 other open-source motion, 3D, capture and agent-skill projects, with licences and how to bring each one into a brief2mp4 pipeline, see [references/ecosystem.md](https://github.com/qualixar/brief2mp4/blob/main/plugin/skills/brief2mp4/references/ecosystem.md).\n\n**Does it cost anything?** The skill is free and MIT licensed. The agent runs on your own Claude Code or Codex plan, and rendering happens on your machine.\n\n**Which models has it been tested with?** Claude Code on Sonnet made briefs 01, 05 and 06 from the brief as written, each passing the delivery check (05 and 06 rendered in about 7 seconds each on an Apple M-series laptop). Stronger models handle harder briefs better, but the loop and the checks are the same for all of them.\n\n**Does it work on Windows?** Yes, with Git for Windows installed (`install.ps1 -InstallTools` does it), because the scripts are bash. CI runs the install, the doctor and the tests on Windows, macOS and Ubuntu on every change. Full renders are tested on macOS.\n\n**Does it upload my files anywhere?** No. Rendering, checks and reports stay in your project folder. The only network traffic is what the tools fetch: npm and PyPI packages at install time and any web fonts your brief names.\n\n**What about music?** `sound_bed.sh` makes a quiet original placeholder so the file is never silent. For a real soundtrack, pass your own licensed track to `finish.sh --audio`.\n\n**Can I use the scripts without an agent?** Yes. They are plain bash and ffmpeg, for example `bash plugin/skills/brief2mp4/scripts/check_delivery.sh my-video.mp4 --seconds 30`.\n\n**How do I update or remove it?** Claude Code plugin: `claude plugin update brief2mp4@brief2mp4` or `claude plugin uninstall brief2mp4@brief2mp4`. Codex plugin: `codex plugin marketplace upgrade` or `codex plugin remove brief2mp4@brief2mp4`. Script install: `git pull` and run the installer again, or `install.sh --uninstall` / `install.ps1 -Uninstall`. The installers only replace or remove a folder they created; an existing `brief2mp4` folder is moved aside with a timestamp, never deleted.\n\n```\nSETUP.md                           the setup script an agent follows (macOS, Windows, Linux)\nAGENTS.md, CLAUDE.md               what an agent opened in this repo should do\ninstall.sh, install.ps1            install, update or remove for both apps; --with-3d / -With3D\n.claude-plugin/marketplace.json    marketplace entry, read by Claude Code and Codex\nplugin/\n  .claude-plugin/plugin.json       Claude Code plugin manifest\n  .codex-plugin/plugin.json        Codex plugin manifest\n  skills/brief2mp4/\n    SKILL.md                       the loop the agent follows\n    references/                    formats, pipelines, ecosystem, hyperframes, threejs, blender, ffmpeg\n    scripts/                       finish, check_delivery, contact_sheet, sound_bed, doctor, detect_3d,\n                                   detect_edit, bounds.py, vendor_libs\n    templates/                     SPEC.md, a Three.js scene, a Blender turntable\n    3d/                            the optional 3D pack and its installers\n    edit/                          the optional edit pack: verified installers, pinned versions, recipes\ndocs/                              getting started, architecture, 3D walkthrough\nexamples/                          seven briefs; 01, 05, 06 and 07 with sample reports, 04 with a worked build\ntests/                             fast checks and render tests (bash tests/run_tests.sh [--slow])\n```\n\nBad results are the most useful bug reports: open a **Brief result** issue with the brief, the app and model, and the `REPORT.md`. Code changes are welcome too; see [CONTRIBUTING.md](https://github.com/qualixar/brief2mp4/blob/main/CONTRIBUTING.md). Security reports go through [SECURITY.md](https://github.com/qualixar/brief2mp4/blob/main/SECURITY.md). Releases are listed in [CHANGELOG.md](https://github.com/qualixar/brief2mp4/blob/main/CHANGELOG.md).\n\nMIT. Use it, change it, ship videos with it. HyperFrames (Apache-2.0), Three.js (MIT), GSAP (standard no-charge licence), Jolt (MIT), glTF-Transform (MIT), meshoptimizer (MIT), Manifold (Apache-2.0), CadQuery (Apache-2.0), trimesh (MIT), Blender (GPL), ffmpeg (LGPL/GPL) and the ArtCraft apps by storytold (MIT or Apache-2.0, downloaded from their own releases by the edit pack) keep their own licences; this repo does not bundle them.\n\nMade by [Varun Pratap Bhardwaj](https://github.com/qualixar).", "url": "https://wpnews.pro/news/show-hn-brief2mp4-claudecode-codex-skill-that-checks-videos-against-the-brief", "canonical_source": "https://github.com/qualixar/brief2mp4", "published_at": "2026-11-16 06:55:56+00:00", "updated_at": "2026-11-16 07:26:06.488165+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "generative-ai"], "entities": ["Qualixar", "brief2mp4", "Claude Code", "Codex", "HyperFrames", "Three.js", "Blender", "ffmpeg"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-brief2mp4-claudecode-codex-skill-that-checks-videos-against-the-brief", "markdown": "https://wpnews.pro/news/show-hn-brief2mp4-claudecode-codex-skill-that-checks-videos-against-the-brief.md", "text": "https://wpnews.pro/news/show-hn-brief2mp4-claudecode-codex-skill-that-checks-videos-against-the-brief.txt", "jsonld": "https://wpnews.pro/news/show-hn-brief2mp4-claudecode-codex-skill-that-checks-videos-against-the-brief.jsonld"}}