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.

fix: loudness reaches target on peaky mixes; example 07 proven; Windows-safe CI checks

Varun Pratap Bhardwaj787a134f7d16
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7440be3..51f398e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -55,7 +55,7 @@ jobs:
- name: Detect 3D pack
run: |
- bash plugin/skills/brief2mp4/scripts/detect_3d.sh | tee /dev/stderr | grep -q "3d: ready"
+ out="$(bash plugin/skills/brief2mp4/scripts/detect_3d.sh)"; echo "$out"; [[ "$out" == *"3d: ready"* ]]
- name: Install the edit pack, film + sound (bash)
if: runner.os != 'Windows'
@@ -68,7 +68,7 @@ jobs:
- name: Detect edit pack
run: |
- bash plugin/skills/brief2mp4/scripts/detect_edit.sh | tee /dev/stderr | grep -q "edit: ready"
+ out="$(bash plugin/skills/brief2mp4/scripts/detect_edit.sh)"; echo "$out"; [[ "$out" == *"edit: ready"* ]]
- name: Edit recipes (FilmCraft cut, SoundCraft mix)
run: |
diff --git a/examples/07-edit-tutorial/SAMPLE-REPORT.md b/examples/07-edit-tutorial/SAMPLE-REPORT.md
new file mode 100644
index 0000000..25d73e6
--- /dev/null
+++ b/examples/07-edit-tutorial/SAMPLE-REPORT.md
@@ -0,0 +1,40 @@
+# REPORT: Brief 07, "Tidy your layers"
+
+Deliverables in `brief07-edit-tutorial/`: `final.mp4` (14.0 s, 1920x1080, 30 fps, H.264 yuv420p, AAC 48 kHz stereo), `thumb.png` (1280x720), `SPEC.md`, `checks/` stills. Edit pack ready (`detect_edit.sh`: film,sound,effect,photo,vector). Cut in FilmCraft, mix in SoundCraft, thumbnail in PhotoCraft; clips from HyperFrames.
+
+## Done when, checked against the original brief
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| final.mp4 is 14.0 s, 1920x1080, 30 fps, H.264 + AAC, -14 LUFS; `check_delivery.sh` passes | met | `checks/delivery.txt`: duration 14.000000 s, h264, yuv420p, 1920x1080, 30/1, aac 48 kHz stereo, loudness -14.4 LUFS, true peak -2.0 dBTP, no black, nothing frozen. `RESULT: PASS` |
+| Clip A and B are 8 s HyperFrames clips; A used from 0.0 s, B from 0.5 to 7.5 s | met | `clipA/render.mp4` and `clipB/render.mp4` both 8.000000 s (ffprobe). FilmCraft timeline: A source 0-7.0 at 0.0 s, B source 0.5-7.5 at 7.0 s |
+| Clip A: about a dozen overlapping rounded rectangles, different sizes, palette colours | met | `checks/t_000.10s.png` and `t_005.00s.png`: 12 rectangles, widths 262-348 px, heights 128-168 px, overlaps visible, cream and accent only on #14213D |
+| Clip B: same rectangles in three aligned rows, slow push-in | met | `checks/t_010.00s.png`: 3 rows of 4. Painted-pixel width grows 1420 px (7.6 s) to 1480 px (10.0 s) to 1523 px (13.9 s) by `bounds.py`, so the camera pushes in |
+| Cross dissolve 1.0 s centred on the cut at 7.0 s | met | `checks/t_007.00s.png` shows messy and tidy rectangles at the same time at half strength; `t_007.60s.png` shows rows only (box x 250-1669) |
+| Title "Tidy your layers", 96 px, lower left, accent, on screen 1.0 to 4.0 s | met | `checks/t_002.00s.png`: spelled exactly, accent colour, `bounds.py` box x 96-815, y 890-977 (88 px from top of "T" and "d" to the foot of "y"; the font size is 96), inside the 96/54 margins. Title clip placed at 1.0 s for 3.0 s; `t_005.00s.png` has nothing in the title region (`bounds.py` box null) |
+| Sound: quiet bed, chime at 1.0 s and 7.0 s | met | SoundCraft session with tracks `bed`, `chime1` (at 1.0 s), `chime2` (at 7.0 s). In `final.mp4` the max level jumps to -1.5 dB in 1.0-2.5 s and -1.3 dB at 6.9-7.1 s, against -3.9 dB at 4.8-5.3 s |
+| Bed ducked 12 dB for 1.5 s under each chime, smooth return | met | Automation points on `bed`: -6 dB to 0.75 s, ramp to -18 dB at 1.0 s, hold to 2.5 s, ramp back to -6 dB at 3.0 s; same at 6.75-9.0 s. Bed-only bounce `work/snd/bedonly.wav` |
+| Bed at least 10 dB lower in 1.0-2.5 s than at 5.0 s | met | Bed stem mean volume: -41.1 dB over 1.0-2.5 s, -28.5 dB over 4.5-5.5 s: 12.6 dB lower. (In the full mix the window holds the chime, so the measure is on the bed stem.) |
+| thumb.png 1280x720, "Tidy your layers" large, one rectangle, no other text | met | ffprobe 1280x720; `thumb.png` shows only the title (150 pt, cream) and one accent rounded rectangle |
+| Title readable at 320 px wide | met | `checks/thumb_320.png` (thumb scaled to 320 px): the whole title reads clearly, letters about 30 px tall |
+| One typeface, bold, for everything | met | Helvetica Neue Bold in the title (FilmCraft) and thumbnail (PhotoCraft); clips have no text. Confirmed visually in the stills |
+| Flat shapes, no gradients inside clips | met | Solid fills (accent, cream) at 0.94 opacity with a 3 px outline in the background colour so overlaps read; no gradients |
+| Something visible by 0.3 s | met | `t_000.10s.png` has the pile in frame |
+
+## Decisions
+- Clip B is fully tidy from its first frame so both states are visible through the dissolve; only a push-in (scale 1.00 to 1.10, power1.out) moves.
+- The messy pile stays in y 76-760 so the lower-left title never sits on a rectangle.
+- Rectangles in B keep their widths from A but share one height (150 px) so the rows align.
+- The chimes are two sine bursts (880 and 1320 Hz, exponential decay) made with ffmpeg; the bed is `sound_bed.sh` with no accents.
+- The finish stage laid `work/snd/mix.wav` under the FilmCraft cut.
+
+## Render settings and timing
+- Clips: `hyperframes render . -o render.mp4 --quality delivery --fps 30 --workers 8`: 2.6 s and 2.4 s (7 s for both including start-up).
+- Cut: `filmcraft-cli run` in three stages, then export H.264 CRF 14, 2.0 s render time, 420 frames.
+- Mix: `soundcraft-cli run` with `--bounce`, under 1 s for the mix and the bed-only check.
+- Thumbnail: `photocraft-cli run --new ... --out`, under 1 s.
+- Finish: `finish.sh --in cut.mp4 --out final.mp4 --seconds 14 --audio work/snd/mix.wav`, 1 s.
+
+## Open
+- Loudness first landed at -15.2 LUFS, 1.2 dB below the -14 target (inside the check's tolerance). The quiet bed plus loud chimes leave too little peak headroom for loudnorm's linear mode, so it fell back to dynamic mode and undershot. This run led to a fix in `finish.sh` (it now measures the result and closes the gap through a limiter); re-finishing the same cut and mix gives -14.4 LUFS with true peak -2.0 dBTP, the numbers in the table above.
+- `hyperframes check` on clip A warned "first_frame_empty", but the snapshot at 0 s shows the full pile; the rectangles are added by script, which the static check misses.
diff --git a/plugin/skills/brief2mp4/SKILL.md b/plugin/skills/brief2mp4/SKILL.md
index 8fa03fe..54e4c1b 100644
--- a/plugin/skills/brief2mp4/SKILL.md
+++ b/plugin/skills/brief2mp4/SKILL.md
@@ -104,6 +104,10 @@ After every full render, do all three:
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? To measure instead of eyeballing (text height, distance from the edge, safe zones on a vertical video), run `python3 scripts/bounds.py <still.png> --bg "#rrggbb" [--region x0,y0,x1,y1] [--margin 96,54 | --safe top=288,bottom=672,left=64,right=192]`: it prints the pixel box of everything that is not background and whether it sits inside the zone.
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.
+To check a mix (for example "the bed is 10 dB under the voice"), measure the stems you bounced separately, not the final mix, where other sounds fall inside the same window.
+
+Run the skill's scripts with `bash` (they are bash scripts); in your own shell loops, remember that zsh, the default shell on macOS, does not split `$var` on spaces the way bash does.
+
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
diff --git a/plugin/skills/brief2mp4/edit/README-EDIT.md b/plugin/skills/brief2mp4/edit/README-EDIT.md
index 71b218b..9e776bd 100644
--- a/plugin/skills/brief2mp4/edit/README-EDIT.md
+++ b/plugin/skills/brief2mp4/edit/README-EDIT.md
@@ -138,6 +138,15 @@ How each app is driven, so you can adapt a recipe:
- **PhotoCraft**: `run --new '{"width":1280,"height":720}' --cmd ID --params '{...}' ... --out file.png`. Saving a layered document as PNG flattens it (the CLI says so).
- **VectorCraft**: `run --commands file.jsonl --export file.svg`. New shapes get a black stroke unless you switch it off with `paint.setStroke {"none":true}`.
+## Commands beyond the recipes (seen working with the pinned versions)
+
+The example 07 run needed a few commands the recipes do not use. All are in the pinned CLIs (`<app>-cli commands` lists them with their parameters):
+
+- FilmCraft `timeline.place` with `sourceIn` and `duration` trims a clip as it places it; `graphics.set` with `props` (`font`, `font_style`, `size`, `fill_color`, `position`, `opacity`) styles a title, and `keyframe: true` animates a property.
+- PhotoCraft `shape.create` draws a shape layer (a rounded rectangle for a thumbnail); `type.create` sets text.
+- PhotoCraft quirk: if the `box` given to `type.create` is too short for the text, only the first wrapped line shows, with no warning. Give text boxes generous height and check the PNG.
+- SoundCraft: `sound_mix.sh` ducks a music bed under any foreground track, not only a voice: pass chimes or sound effects as `--voice` to duck under them.
+
## Every route still ends in the same two scripts
Whatever made the picture and sound, the deliverable is checked the same way. An edit export is a rough render like any other:
diff --git a/plugin/skills/brief2mp4/references/hyperframes.md b/plugin/skills/brief2mp4/references/hyperframes.md
index eaea56e..b051e26 100644
--- a/plugin/skills/brief2mp4/references/hyperframes.md
+++ b/plugin/skills/brief2mp4/references/hyperframes.md
@@ -87,3 +87,4 @@ Quality presets: `draft` for iterating, `looks` (default) for review, `delivery`
- **Eases, by name.** GSAP's `power1` is quadratic, `power2` cubic, `power3` quartic and `power4` quintic; `.out` decelerates into place (arrivals), `.in` accelerates away (exits), `.inOut` does both. `none` is linear: use it only for constant spins and turntables. When a brief names a feel ("snappy", "soft"), write the ease you chose into SPEC.md.
- **Freeze warnings and small motion.** `check_delivery.sh` looks for whole-frame freezes. A small element that keeps moving (a counter, a dot) can still trip it, because the change is below its threshold. Pull two stills a second apart inside the flagged stretch and compare them before you call it dead air.
- **Starting states belong in CSS.** A `tl.set(el, {...}, 0)` at time 0 may not be applied when the renderer captures frame 0, so an element meant to start hidden flashes in the first frame. Put the starting state (`opacity: 0`, an offset transform) in CSS and animate from it; `hyperframes check` warns about this.
+- **`first_frame_empty` from `hyperframes check`** can be a false alarm when elements are created by script: the static check does not run your script. Confirm with `npx hyperframes snapshot . --at 0` and look at the frame.
diff --git a/plugin/skills/brief2mp4/scripts/bounds.py b/plugin/skills/brief2mp4/scripts/bounds.py
index 2d9e271..072583b 100644
--- a/plugin/skills/brief2mp4/scripts/bounds.py
+++ b/plugin/skills/brief2mp4/scripts/bounds.py
@@ -14,7 +14,7 @@ PNGs that contact_sheet.sh and ffmpeg write.
checks a left/right and top/bottom safe margin (5% at 1920x1080)
Prints one JSON object. Exit 0 when the box is inside the zones (or none were given), 1 otherwise.
-A box height is a good proxy for text height when you measure a single line.
+A box height is a good proxy for text height when you measure a single line. It measures ink, not font-size: a line without descenders (no g, j, p, q, y) is shorter than its font-size, a line with them is taller than its cap height. Compare like with like, or check the CSS for font-size.
Measuring one element (a moving dot, one label): pass a --region that contains only that element,
then read its box centre: cx = (x0 + x1) / 2, cy = (y0 + y1) / 2. For easing, measure the centre at
diff --git a/plugin/skills/brief2mp4/scripts/finish.sh b/plugin/skills/brief2mp4/scripts/finish.sh
index 89efce5..4d4d349 100755
--- a/plugin/skills/brief2mp4/scripts/finish.sh
+++ b/plugin/skills/brief2mp4/scripts/finish.sh
@@ -61,14 +61,14 @@ VF="scale=${W}:${H}:force_original_aspect_ratio=decrease:flags=lanczos,pad=${W}:
# loudnorm undershoots on short clips because it needs several seconds of look-ahead.
PRE="alimiter=limit=0.5:level=disabled"
TAIL="aresample=48000,apad,atrim=0:${SECONDS_},afade=t=out:st=$(awk "BEGIN{print ${SECONDS_}-0.4}"):d=0.4"
-loudness_filter() { # loudness_filter <input file> -> prints the -af chain
+loudness_core() { # loudness_core <input file> -> the normalising part of the chain ("" for silence)
local m val k f="${PRE},loudnorm=I=${LUFS}:TP=-1.5:LRA=11"
m="$(ffmpeg -hide_banner -nostats -t "$SECONDS_" -i "$1" -vn -af "${PRE},loudnorm=I=${LUFS}:TP=-1.5:LRA=11:print_format=json" -f null - 2>&1 | awk '/^\{/,/^\}/')"
for k in input_i input_tp input_lra input_thresh target_offset; do
val="$(printf '%s\n' "$m" | sed -n "s/.*\"$k\" : \"\([^\"]*\)\".*/\1/p")"
case "$val" in
- *inf*|*nan*) echo "${TAIL}"; return ;; # silent input: nothing to normalise
- "") echo "${PRE},loudnorm=I=${LUFS}:TP=-1.5:LRA=11,${TAIL}"; return ;;
+ *inf*|*nan*) echo ""; return ;; # silent input: nothing to normalise
+ "") echo "${PRE},loudnorm=I=${LUFS}:TP=-1.5:LRA=11"; return ;;
esac
case "$k" in
input_i) f="$f:measured_I=$val" ;; input_tp) f="$f:measured_TP=$val" ;;
@@ -76,7 +76,28 @@ loudness_filter() { # loudness_filter <input file> -> prints the -af chain
target_offset) f="$f:offset=$val" ;;
esac
done
- echo "$f:linear=true,${TAIL}"
+ echo "$f:linear=true"
+}
+
+measured_i() { # measured_i <input file> <chain> -> integrated loudness of the chain's output
+ ffmpeg -hide_banner -nostats -t "$SECONDS_" -i "$1" -vn -af "$2,ebur128" -f null - 2>&1 \
+ | awk '/Integrated loudness:/{f=1} f && /I:/{print $2; exit}'
+}
+
+loudness_filter() { # loudness_filter <input file> -> prints the full -af chain
+ # Peaky material (sparse hits, chimes) can need more gain than loudnorm's true-peak limit allows; it
+ # then falls back to dynamic mode and lands short. Measure the result and close the gap through a
+ # brick-wall limiter, at most twice, so the file reaches the target with peaks held under -1 dBTP.
+ local core i d round
+ core="$(loudness_core "$1")"
+ [[ -n "$core" ]] || { echo "${TAIL}"; return; }
+ for round in 1 2; do
+ i="$(measured_i "$1" "$core")"
+ d="$(awk -v t="$LUFS" -v i="$i" 'BEGIN{ if (i=="" || i ~ /inf|nan/) {print "0"; exit} d=t-i; if (d<0.5 && d>-0.5) print "0"; else printf "%.2f", d }')"
+ [[ "$d" == 0 ]] && break
+ core="${core},volume=${d}dB,alimiter=limit=0.79:level=disabled"
+ done
+ echo "${core},${TAIL}"
}
if [[ -n "$AUDIO" ]]; then