Magnifito B-Roll: motion graphics on footage
Turn a talking-head video and its captions into motion-graphic B-roll timed to the speaker's
words. Each clip is one spring-driven shape that morphs and never cuts (the vendored
Barty-Bart motion-graphics engine, MIT). Clips are either:
- panel: a transparent clip (
bg:null) in the empty part of the frame. The speaker stays
on screen. Rendered to ProRes 4444 .mov with alpha.
- full: an opaque full-frame cutaway that replaces the speaker for the length of one idea.
Rendered to H.264
.mp4.
Requirements: ffmpeg, Google Chrome (or CHROME_PATH), and playwright-core from the toolkit's
npm install. mgvideo doctor reports all three.
Workflow
mgvideo broll words captions.srt -o motion/transcript.json --txt motion/words.txt
# write motion/plan.json (below), then:
mgvideo broll check motion/plan.json
mgvideo broll render motion/plan.json # --only 01,03 to re-render some clips
mgvideo broll compose motion/plan.json motion/out/preview.mp4 --sheet motion/out/contact.png
- Transcript.
broll words reads an SRT or VTT file and spreads each cue's span across
its words by character count (about ±0.2 s). It writes a Transcript contract JSON (-o)
and/or upstream words.txt (--txt, one line per cue, start:word). There is no speech
recognition in the toolkit: if you only have the video, ask for an SRT/VTT export from the
editor or captioning tool. Put important changes on the first or last word of a cue, where
the estimate is best.
- Plan. Pick the moments, one idea per clip, and decide panel, full or nothing for each.
Timing rules (lead, sync, hold, rhythm, face-safe areas):
reference/word-timed-graphics.md.
Show the user a table (in–out, the line, what the shape does, panel/full, why) and get
approval before rendering.
- Check.
broll check validates the plan against its directory and the probed source.
- Render.
broll render renders each clip at the source video's resolution and frame
rate. Pages land in <plan dir>/dist/<id>.html (open one in a browser to preview it in a
loop); clips go to each clip's file. Rendering captures 4 sub-frames per frame for motion
blur, so it is slower than real time.
- Compose.
broll compose lays the clips over the source (TS port of upstream
composite.py): each clip shows from in to out, a clip shorter than its slot holds its
last frame, .mov clips composite with alpha, the original audio is kept (re-encoded to
AAC) and the output is H.264 with faststart. --sheet writes a contact sheet around every
clip window. Read the contact sheet yourself before handing anything over.
Say plainly that preview.mp4 is for review. For the final cut the user places the clips in
their editor, where they can nudge timing, add transitions and mix audio.
plan.json
{
"title": "Episode 12",
"video": "work/source.mp4",
"fps": "30000/1001",
"brand": "brand.json",
"clips": [
{ "id": "01", "title": "Pipeline", "line": "“First you plan, then render…”",
"in": 0.6, "out": 4.0, "kind": "panel", "area": "right",
"recipe": "motion-card-morph",
"scene": { "copy": "B-roll pipeline | Plan the clips | Render with motion | Compose" } },
{ "id": "02", "title": "Ship it", "line": "“And then you ship it.”",
"in": 4.4, "out": 5.8, "kind": "full",
"recipe": "motion-kinetic-type", "scene": { "copy": "Then you ship it" } },
{ "id": "03", "title": "Custom", "in": 9.0, "out": 14.0, "kind": "panel",
"fragment": "clips/03-custom.html", "file": "out/03-custom.mov" }
],
"notes": ["Bars in clip 03 are illustrative (relative size only)."]
}
| Field |
Meaning |
video |
Source footage. |
fps |
Optional. When given it must match the probed source; clips always render at the source fps. |
brand |
Optional brand.json (brand contract). Colours and font files drive the recipes. Without it, the upstream look: warm grey canvas, black ink, white cards, orange accent. |
clips[].in / out |
Seconds on the source timeline. in < out, out within the source, no two clips overlap (one clip's out may equal the next in). |
clips[].kind |
panel (transparent .mov) or full (opaque .mp4). |
clips[].recipe + scene.copy |
A motion recipe and its copy. scene.logo gives the logo file for motion-logo-reveal. |
clips[].fragment |
A hand-written clip fragment instead of a recipe. |
clips[].area |
Panel safe area: "right" (default), "left", "top", "bottom", or { "x", "y", "w", "h" } in source pixels. |
clips[].file |
Output clip. Defaults to `out/_ms.mov |
Every path is relative to the directory holding plan.json and must stay inside it (absolute
paths and .. escapes are rejected). Keep the source in that directory, e.g. work/source.mp4.
Recipes and minimum slot lengths:
| Recipe |
Panel |
Full |
Min |
Copy |
motion-card-morph |
yes |
yes |
3.0 s |
`Headline |
motion-bars-chart |
yes |
yes |
1.6 s |
`Title |
motion-kinetic-type |
no |
yes |
0.8 s |
the line, words land on a grid |
motion-logo-reveal |
no |
yes |
1.2 s |
tagline, plus scene.logo |
Recipe clips fill their slot and end holding their last state. For anything else (a terminal,
a slider, tabs, a file drag), write a fragment.
Panel or full: the creative call
Decide per clip and say why.
- Full-frame cutaway when the frame is all speaker and the line describes something to
see: a product, a process, a comparison, a number, a chapter change. Cut away for the
length of the idea (about 1.5–10 s), then give the face back. Not in the first second of the
hook, not on personal, emotional or opinion lines. Leave about 2 s of face between cutaways.
- Panel when the edit already leaves room: a PiP layout, a split, a plain side of the frame.
Panels can run long (15 s+) as one continuous morph because the speaker stays on screen.
- Nothing when the line is about the speaker or too close to another clip.
Safe areas for panels
- Look at the footage first (
mgvideo inspect, or a contact sheet of the source) and find where
the speaker is at every moment of the slot, not just the first frame.
- The presets take 45% of the frame on one side, with 5% horizontal and 8% vertical margins.
"right" suits a speaker on the left third, and so on. When the speaker sits near the centre,
give an explicit rectangle that clears their head and shoulders, or use a full clip.
- Recipe panels are centred in the area and sized to it. During morphs the camera is clamped so
the shape never grows past the area, and the cursor stays inside it.
- Keep panels clear of burned-in subtitles and lower thirds; use
"top" when captions sit at
the bottom.
- On dark footage the default cards are white with black ink; on light footage pass a brand
whose colours contrast with the background.
Custom clips (fragments)
Write fragments in the upstream motion-broll format, following
skills/magnifito-promo/reference/motion-engine.md (fragment skeleton, window.M engine API,
patterns). For B-roll:
- Set
W/H to the source resolution. Render fails if the stage size differs.
- Panel fragments use
bg:null and move the camera with center:[x,y] into the empty area;
full fragments set an opaque bg. Render fails if the alpha does not match kind.
- Clip-local time = word time − clip
in. Put each state change on its word.
- A fragment renders for its own
T; if that is shorter than the slot, compose holds its last
frame. If it is longer, compose cuts it at out.
Content rules
- Never invent numbers, quotes, prices or results. Use labels and figures from the transcript or
the user, or relative bars, and list what is illustrative in
notes.
- One idea per clip. Pace changes to speech, about 0.4–1.2 s apart.
- No particles, glows, gradients on UI chrome, bouncy easing or template-looking cards.
Stopping conditions
- Stop if a panel overlaps the speaker's face or body at any moment of its slot, or covers
subtitles.
- Stop if
broll check reports a problem; fix the plan rather than the paths.
- Stop if the contact sheet shows clipped, unreadable or off-word content.
1---2name: magnifito-broll3description: "Add speech-timed motion B-roll to talking-head footage: transparent panels beside the speaker and full-frame cutaways, planned in plan.json, rendered with the motion engine and composited over the source with its original audio."4metadata:5 source: https://skillmd.com/skills/magnifito/magnifito-broll6---78# Magnifito B-Roll: motion graphics on footage910Turn a talking-head video and its captions into motion-graphic B-roll timed to the speaker's11words. Each clip is one spring-driven shape that morphs and never cuts (the vendored12Barty-Bart motion-graphics engine, MIT). Clips are either:1314- **panel**: a transparent clip (`bg:null`) in the empty part of the frame. The speaker stays15 on screen. Rendered to ProRes 4444 `.mov` with alpha.16- **full**: an opaque full-frame cutaway that replaces the speaker for the length of one idea.17 Rendered to H.264 `.mp4`.1819Requirements: ffmpeg, Google Chrome (or `CHROME_PATH`), and `playwright-core` from the toolkit's20`npm install`. `mgvideo doctor` reports all three.2122## Workflow2324```bash25mgvideo broll words captions.srt -o motion/transcript.json --txt motion/words.txt26# write motion/plan.json (below), then:27mgvideo broll check motion/plan.json28mgvideo broll render motion/plan.json # --only 01,03 to re-render some clips29mgvideo broll compose motion/plan.json motion/out/preview.mp4 --sheet motion/out/contact.png30```31321. **Transcript.** `broll words` reads an SRT or VTT file and spreads each cue's span across33 its words by character count (about ±0.2 s). It writes a Transcript contract JSON (`-o`)34 and/or upstream `words.txt` (`--txt`, one line per cue, `start:word`). There is no speech35 recognition in the toolkit: if you only have the video, ask for an SRT/VTT export from the36 editor or captioning tool. Put important changes on the first or last word of a cue, where37 the estimate is best.382. **Plan.** Pick the moments, one idea per clip, and decide panel, full or nothing for each.39 Timing rules (lead, sync, hold, rhythm, face-safe areas): `reference/word-timed-graphics.md`.40 Show the user a table (in–out, the line, what the shape does, panel/full, why) and get41 approval before rendering.423. **Check.** `broll check` validates the plan against its directory and the probed source.434. **Render.** `broll render` renders each clip at the source video's resolution and frame44 rate. Pages land in `<plan dir>/dist/<id>.html` (open one in a browser to preview it in a45 loop); clips go to each clip's `file`. Rendering captures 4 sub-frames per frame for motion46 blur, so it is slower than real time.475. **Compose.** `broll compose` lays the clips over the source (TS port of upstream48 `composite.py`): each clip shows from `in` to `out`, a clip shorter than its slot holds its49 last frame, `.mov` clips composite with alpha, the original audio is kept (re-encoded to50 AAC) and the output is H.264 with faststart. `--sheet` writes a contact sheet around every51 clip window. **Read the contact sheet yourself** before handing anything over.5253Say plainly that `preview.mp4` is for review. For the final cut the user places the clips in54their editor, where they can nudge timing, add transitions and mix audio.5556## plan.json5758```json59{60 "title": "Episode 12",61 "video": "work/source.mp4",62 "fps": "30000/1001",63 "brand": "brand.json",64 "clips": [65 { "id": "01", "title": "Pipeline", "line": "“First you plan, then render…”",66 "in": 0.6, "out": 4.0, "kind": "panel", "area": "right",67 "recipe": "motion-card-morph",68 "scene": { "copy": "B-roll pipeline | Plan the clips | Render with motion | Compose" } },69 { "id": "02", "title": "Ship it", "line": "“And then you ship it.”",70 "in": 4.4, "out": 5.8, "kind": "full",71 "recipe": "motion-kinetic-type", "scene": { "copy": "Then you ship it" } },72 { "id": "03", "title": "Custom", "in": 9.0, "out": 14.0, "kind": "panel",73 "fragment": "clips/03-custom.html", "file": "out/03-custom.mov" }74 ],75 "notes": ["Bars in clip 03 are illustrative (relative size only)."]76}77```7879| Field | Meaning |80|---|---|81| `video` | Source footage. |82| `fps` | Optional. When given it must match the probed source; clips always render at the source fps. |83| `brand` | Optional brand.json (brand contract). Colours and font files drive the recipes. Without it, the upstream look: warm grey canvas, black ink, white cards, orange accent. |84| `clips[].in` / `out` | Seconds on the source timeline. `in < out`, `out` within the source, no two clips overlap (one clip's `out` may equal the next `in`). |85| `clips[].kind` | `panel` (transparent `.mov`) or `full` (opaque `.mp4`). |86| `clips[].recipe` + `scene.copy` | A motion recipe and its copy. `scene.logo` gives the logo file for `motion-logo-reveal`. |87| `clips[].fragment` | A hand-written clip fragment instead of a recipe. |88| `clips[].area` | Panel safe area: `"right"` (default), `"left"`, `"top"`, `"bottom"`, or `{ "x", "y", "w", "h" }` in source pixels. |89| `clips[].file` | Output clip. Defaults to `out/<id>_<m>m<ss>s<cc>.mov|mp4`, named by the in-point (`0m06s75` = 0:06.75). |9091Every path is relative to the directory holding plan.json and must stay inside it (absolute92paths and `..` escapes are rejected). Keep the source in that directory, e.g. `work/source.mp4`.9394Recipes and minimum slot lengths:9596| Recipe | Panel | Full | Min | Copy |97|---|---|---|---|---|98| `motion-card-morph` | yes | yes | 3.0 s | `Headline | row | row | row` (up to 4 rows) |99| `motion-bars-chart` | yes | yes | 1.6 s | `Title | Label: 12 min | Label: 40 min` (up to 6 values) |100| `motion-kinetic-type` | no | yes | 0.8 s | the line, words land on a grid |101| `motion-logo-reveal` | no | yes | 1.2 s | tagline, plus `scene.logo` |102103Recipe clips fill their slot and end holding their last state. For anything else (a terminal,104a slider, tabs, a file drag), write a fragment.105106## Panel or full: the creative call107108Decide per clip and say why.109110- **Full-frame cutaway** when the frame is all speaker and the line describes something to111 *see*: a product, a process, a comparison, a number, a chapter change. Cut away for the112 length of the idea (about 1.5–10 s), then give the face back. Not in the first second of the113 hook, not on personal, emotional or opinion lines. Leave about 2 s of face between cutaways.114- **Panel** when the edit already leaves room: a PiP layout, a split, a plain side of the frame.115 Panels can run long (15 s+) as one continuous morph because the speaker stays on screen.116- **Nothing** when the line is about the speaker or too close to another clip.117118## Safe areas for panels119120- Look at the footage first (`mgvideo inspect`, or a contact sheet of the source) and find where121 the speaker is at every moment of the slot, not just the first frame.122- The presets take 45% of the frame on one side, with 5% horizontal and 8% vertical margins.123 `"right"` suits a speaker on the left third, and so on. When the speaker sits near the centre,124 give an explicit rectangle that clears their head and shoulders, or use a full clip.125- Recipe panels are centred in the area and sized to it. During morphs the camera is clamped so126 the shape never grows past the area, and the cursor stays inside it.127- Keep panels clear of burned-in subtitles and lower thirds; use `"top"` when captions sit at128 the bottom.129- On dark footage the default cards are white with black ink; on light footage pass a brand130 whose colours contrast with the background.131132## Custom clips (fragments)133134Write fragments in the upstream motion-broll format, following135`skills/magnifito-promo/reference/motion-engine.md` (fragment skeleton, `window.M` engine API,136patterns). For B-roll:137138- Set `W`/`H` to the source resolution. Render fails if the stage size differs.139- Panel fragments use `bg:null` and move the camera with `center:[x,y]` into the empty area;140 full fragments set an opaque `bg`. Render fails if the alpha does not match `kind`.141- Clip-local time = word time − clip `in`. Put each state change on its word.142- A fragment renders for its own `T`; if that is shorter than the slot, compose holds its last143 frame. If it is longer, compose cuts it at `out`.144145## Content rules146147- Never invent numbers, quotes, prices or results. Use labels and figures from the transcript or148 the user, or relative bars, and list what is illustrative in `notes`.149- One idea per clip. Pace changes to speech, about 0.4–1.2 s apart.150- No particles, glows, gradients on UI chrome, bouncy easing or template-looking cards.151152## Stopping conditions153154- Stop if a panel overlaps the speaker's face or body at any moment of its slot, or covers155 subtitles.156- Stop if `broll check` reports a problem; fix the plan rather than the paths.157- Stop if the contact sheet shows clipped, unreadable or off-word content.