kaizen-agent 1.47.0 → 1.49.0

package/skills/media/kaizen-video/references/presets.md

@@ -0,0 +1,76 @@
+# Presets
+
+A preset is a folder. `make_tiktok.py` finds it by the name in the video's `config.json` (`"preset"`),
+looking in this order and taking the first folder that has an `index.html`:
+
+1. `presets/<name>/` in the project folder — styles for this project.
+2. `$KAIZEN_VIDEO_PRESETS/<name>/`, default `~/.kaizen/video-presets/<name>/` — your own styles, for every project.
+3. `<skill>/presets/<name>/` — the bundled ones.
+
+A local preset with a bundled name overrides the bundled one. An unknown name stops the build and lists
+every preset it can see. Nothing is registered anywhere: adding a folder is adding a preset.
+
+## What goes in the folder
+
+| File | Required | Notes |
+|---|---|---|
+| `index.html` | yes | The HyperFrames composition template. |
+| `package.json` | yes | Pins `@hyperframes/core` (copy one from a bundled preset). |
+| `README.md` | yes | Look, motion, card types, sounds and config keys, for whoever picks a style. |
+| `CREDITS.txt` | yes | Source, author and license of every font and sound file the preset uses, copied into every render's credits. Credit a preset's own music as a line `- <name>.mp3: <title, author, license>`; the render credits only the track the video uses, looked up here and then in the skill's `assets/CREDITS.txt`. |
+| `assets/sfx/*.wav` | yes | Sound effects, 48 kHz, any WAV encoding. Durations are read from the files with ffprobe. |
+| `assets/fonts/*.ttf` | no | Falls back to the skill's `assets/fonts/` (Montserrat, Fredoka, Special Elite). |
+| `assets/music/*.mp3` | no | Falls back to the skill's `assets/music/` (`lights`, `investigations`, `sunny`). |
+| `tools/carve.mjs`, `hyperframes.json` | no | Fall back to the skill's copies. |
+
+A file in the preset always wins over the shared one with the same name, so a preset can replace a font or
+a track without touching the others.
+
+## Template contract
+
+`make_tiktok.py` fills these in `index.html`; keep them:
+
+- `{{DURATION}}`, `{{VIDEO_DURATION}}`, `{{VIDEO}}`, `{{MUSIC_VOLUME}}`
+- `{{HOOK_1}}`, `{{HOOK_2}}`, `{{HOOK_SUB}}`
+- `<!-- SFX:BEGIN -->` — where the sound-effect `<audio>` tags are inserted.
+
+The composition also reads `captions.js` (`window.CAPTIONS`, `window.SEG_STARTS`, `window.BEATS`), and its
+voice element must have the id `a-roll` and the music bed the id `music`, because the music is carved around
+the voice by those ids.
+
+Sounds the script places itself: `shutter` (every card), `stamp` (a beat with `"stamp"`), `reveal` (each
+`item`) and `ending` (the `end` beat). Any other wav in `assets/sfx/` can be used as a reaction in the
+config (`{"sfx": "<file name>", "word", "after", "offset", "volume"}`). Keep peaks around −6.5 to −8.5 dBFS.
+
+## Adding one
+
+1. Copy the closest preset to the project's `presets/<style>/` (or `~/.kaizen/video-presets/<style>/`).
+2. Change `index.html` and the assets, update `README.md`, and write `CREDITS.txt` for every file you add.
+3. Set `"preset": "<style>"` in a video's config and build it.
+
+To ship it to everyone who installs kaizen, copy the folder into this skill's `presets/` in the kaizen
+repository. Move any music or font another preset could use into the shared `assets/`, credit it in
+`assets/CREDITS.txt`, and keep only the preset's own files in its folder: every byte here goes into the
+kaizen package.
+
+# Film presets (from scratch)
+
+`make_film.py` finds a film preset by the folder holding `style.json` (same three places as above), so the two kinds never collide. Bundled: `film-cinematic-drama`, `film-promo-booth`, `film-fun-energetic`, `film-viral-social`. Each works in 9:16 and 16:9; the `window` and `card` layouts fall back to full-bleed in 9:16.
+| preset | use for | look & motion | audio | captions | loudness |
+|---|---|---|---|---|---|
+| cinematic-drama | pitch opener, brand film | dark, full-bleed photos, slow push-in, rise text, grain + vignette, fades | quiet music, hit on reveal, riser into the question, room tone | subtitle bar | −16 |
+| promo-booth | exhibition loop, deck-faithful promo (the friend's style) | photo in a framed window beside the text, wipes, slide-in text, staged builds | whoosh on cuts, tick on titles, slightly louder music | subtitle bar | −16 |
+| fun-energetic | social posts, parents, events | cream background, rounded photo cards that bounce in, pop text, light leaks | bright track (Carefree), pops and a chime | subtitle bar | −14 |
+| viral-social | TikTok / Reels / Shorts (9:16) | full-bleed, fast punch-in cuts, bold Inter, strong Ken Burns | Easy Lemon-type track, whooshes | kinetic 2–3 words, accent on the spoken word | −14 |
+
+Pace: `lead` / `tail` = silence before and after each line. Drama 0.8/1.1, booth 0.45/0.7, fun 0.2/0.35, viral 0.05/0.2.
+
+## Writing for each preset
+- **drama**: full story arc, 70–110 s, long pauses allowed.
+- **booth**: the deck's beats in order, 80–100 s, must make sense when joined mid-loop; real contacts on the CTA.
+- **fun**: 35–50 s, playful lines ("Kenal rasanya?"), one problem montage, three quick benefits.
+- **viral**: ≤ 30 s, line 1 is the hook (a sharp, relatable pain), product by second ~12, one CTA.
+
+## Adding a preset
+Copy a `film-*` folder to `presets/<name>/` in the project and edit its `style.json` (no `index.html`: `film.html` is shared); fields: palette, fonts (any font file in `assets/film-fonts/` or the preset's `assets/fonts/`, named like `PlayfairDisplay.ttf`), pace, text (rise|slide|pop), transition (fade|wipe|punch),
+layout (fullbleed|window|card), grade, captions (subtitle|kinetic|none), music levels, sfx names, kenburns, loudness.

package/skills/{story-video → media/kaizen-video}/references/production.md

@@ -7,8 +7,8 @@ Learned by comparing deck-to-video renders against richer productions . The exam
    "140 pesan", `keyboard`, `bell`), soft whoosh/tick on cuts, a hit on the reveal, a riser into the
    question. Music ducks under speech and only lifts at the reveal — never a dramatic swell unless
    the preset is drama.
-2. **Captions**: always. Projectors and phones are often muted. Subtitle bar for 16:9, kinetic
-   2–3-word captions for 9:16. Captions come from `words.json`, so they follow the voice exactly.
+2. **Captions**: always. Projectors and phones are often muted. Subtitle bar (cinematic, booth, fun) or kinetic
+   2–3-word captions (viral), in either shape. Captions come from `words.json`, so they follow the voice exactly.
 3. **Staged builds inside a beat**: numbers count up, list items arrive one by one with the voice,
    triptych panels arrive in turn. A whole slide appearing at once reads as a slideshow.
 4. **Directed voice**: emotion tag per line, low and slow through the problem, lift at the question,

package/skills/{story-video → media/kaizen-video}/references/revisions.md

@@ -5,21 +5,21 @@ Clients revise. Make every revision cheap, traceable and reversible.
 ## Classify the request, then touch only that layer
 | request | what changes | redo |
 |---|---|---|
-| "change this sentence / say it warmer / mispronounced X" | `lines.json` entry | `vo.py <film-dir> "" v04` (only that key; empty voice = use film.json), then master |
-| "different text on screen" | beat `kick/title/sub/items` in `film.json` | master |
-| "swap this picture" | beat `img` (+ intake for new photos) | master |
-| "slower / faster / shorter" | preset `pace`, beat `hold`, drop or merge beats | master |
-| "music too loud / different mood" | preset `music.base/lift` or `music.sh` new track | master |
-| "other colours / logo / font" | `film.brand`, `logo` | master |
+| "change this sentence / say it warmer / mispronounced X" | `lines.json` entry | `vo.py <film-dir> "" v04` (only that key; empty voice = use film.json), then build and render |
+| "different text on screen" | beat `kick/title/sub/items` in `film.json` | build + master |
+| "swap this picture" | beat `img` (+ intake for new photos) | build + render |
+| "slower / faster / shorter" | preset `pace`, beat `hold`, drop or merge beats | build + render |
+| "music too loud / different mood" | preset `music.base/lift` or `music.sh` new track | build + render |
+| "other colours / logo / font" | `film.brand`, `logo` | build + render |
 | "make a vertical / 15 s version" | new film entry with its own (shorter) script | vo + master |
 | "different style" | `preset` (and usually a rewritten script) | vo + master |
 
 Never regenerate all narration for a one-line change: voices vary between takes and credits cost money.
 
 ## Versioning
-- `master.sh` moves the previous delivery to `out/previous/<name>-<timestamp>.*` before writing the new one.
-- Append to `~/.kaizen/videos/<slug>/REVISIONS.md`: date, the user's words verbatim, what changed, output file.
-- When a revision is rejected, restore from `out/previous/` instead of re-rendering.
+- `master.sh` moves the previous delivery to `output/<name>/<preset>/previous/<name>-<timestamp>.*` before writing the new one.
+- Append to `videos/<name>/REVISIONS.md`: date, the user's words verbatim, what changed, output file.
+- When a revision is rejected, restore from `previous/` instead of re-rendering.
 
 ## Before re-delivering
 Re-check stills of the beats that changed, master, and say exactly what changed and what did not.

package/skills/media/kaizen-video/scripts/check.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Requirements for kaizen-video. Prints what is missing and how to install it; exit 1 if anything required is missing.
+miss=0
+HOME_DIR=${KAIZEN_VIDEO_HOME:-$HOME/.kaizen/kaizen-video}
+need(){ command -v "$1" >/dev/null 2>&1 && echo "ok   $1" || { echo "MISSING $1 — $2"; miss=1; }; }
+need ffmpeg  "ffmpeg (brew install ffmpeg / apt install ffmpeg / pacman -S ffmpeg / winget install ffmpeg)"
+need ffprobe "comes with ffmpeg"
+need node    "Node.js 18+ (https://nodejs.org or your package manager)"
+need npm     "comes with Node.js"
+need npx     "comes with Node.js"
+need python3 "Python 3.9+"
+command -v uv >/dev/null 2>&1 && echo "ok   uv" || { echo "MISSING uv — https://docs.astral.sh/uv/ (installs Python 3.11 for WhisperX)"; miss=1; }
+[ -x "$HOME_DIR/whisperx-venv/bin/python" ] && echo "ok   WhisperX ($HOME_DIR/whisperx-venv)" || echo "todo WhisperX — run setup.sh (about 2 GB of packages, plus a 3 GB model on the first transcription)"
+# From-scratch films (make_film.py) need these too; WhisperX is footage-only.
+opt(){ command -v "$1" >/dev/null 2>&1 && echo "ok   $1" || echo "opt  $1 — $2"; }
+opt soffice  "LibreOffice — only for importing .pptx decks"
+opt pdftoppm "poppler-utils — only for importing decks"
+python3 -c "import PIL" 2>/dev/null && echo "ok   Pillow" || echo "opt  Pillow — pip install pillow (from-scratch: intake.py)"
+python3 -c "import edge_tts" 2>/dev/null && echo "ok   edge-tts (free voices)" || echo "opt  edge-tts — pip install edge-tts (from-scratch voice without an ElevenLabs key)"
+python3 -c "import qrcode" 2>/dev/null && echo "ok   qrcode" || echo "opt  qrcode — pip install 'qrcode[pil]' (QR on the CTA)"
+[ -n "${ELEVENLABS_API_KEY:-}" ] && echo "ok   ELEVENLABS_API_KEY set" || echo "info no ELEVENLABS_API_KEY — from-scratch uses edge-tts and synthesized sound effects"
+exit $miss

package/skills/{story-video → media/kaizen-video}/scripts/intake.py

@@ -1,7 +1,7 @@
 """Turn whatever the user brought into film-ready assets.
 Usage: python3 scripts/intake.py <film-dir> [input_dir]   (default input_dir: <film-dir>/inputs)
 <input_dir> may contain, in any mix:
-  photos/      story photos            -> <name>-16x9.jpg + <name>-9x16.jpg (cropped, light grade)
+  photos/      story photos            -> <name>-16x9.jpg, -9x16.jpg, -4x5.jpg (cropped, light grade)
   screens/     app/web screenshots     -> copied untouched; ratio recorded (use kind "shot")
   footage/     video clips (.mp4/.mov) -> <name>.mp4 (H.264, no audio, 1080p max)
   logo*.png    logo(s)                  -> copied; dominant colours suggested for brand.palette
@@ -36,7 +36,7 @@ def grade(im):
 for f in sorted((src / "photos").glob("*")) if (src / "photos").exists() else []:
     if f.suffix.lower() not in IMG: continue
     im = Image.open(f).convert("RGB")
-    for tag, size in (("16x9", (1920, 1080)), ("9x16", (1080, 1920))):
+    for tag, size in (("16x9", (1920, 1080)), ("9x16", (1080, 1920)), ("4x5", (1080, 1350))):
         grade(crop(im, *size)).save(out / f"{f.stem}-{tag}.jpg", quality=88)
     manifest["photos"].append(f.stem)
 for f in sorted((src / "screens").glob("*")) if (src / "screens").exists() else []:

package/skills/media/kaizen-video/scripts/make_film.py

@@ -0,0 +1,263 @@
+"""Build (and optionally render) a film made from nothing: narration, pictures, music, sound effects.
+
+    python3 scripts/make_film.py videos/<name> [--render] [--format 9x16|16x9|4x5]
+
+Run from the project folder. videos/<name>/ holds film.json (storyboard + brand), lines.json (the script),
+words.json (word timings from vo.py), the voice files vNN.mp3 and the pictures. Writes the HyperFrames project
+into videos/<name>/film/; with --render, scripts/master.sh renders it, masters the loudness and writes
+output/<name>/<preset>/<name>.mp4 with the .srt, thumbnail and credits.
+
+film.json: "preset" (a folder under presets/ with a style.json, e.g. film-cinematic-drama), "format"
+("9x16" default, "16x9", or "4x5" for an Instagram feed post), "beats", "brand", "labels", "cta", "logo", "qr", "music" (a bundled track name;
+without it videos/<name>/music.mp3 is used). The preset is found in ./presets/, $KAIZEN_VIDEO_PRESETS
+(default ~/.kaizen/video-presets/), then the skill's presets/, like make_tiktok.py.
+--format overrides film.json's format for one build and adds -<format> to the output name, so one film can be
+rendered for several shapes (the Video page in kaizen web does this) without one render replacing another.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parent.parent
+WORK = Path.cwd()
+HF = "hyperframes@0.8.176"
+FPS = 30
+HOME = Path(os.environ.get("KAIZEN_VIDEO_HOME", Path.home() / ".kaizen/kaizen-video"))
+SIZES = {"9x16": (1080, 1920, "portrait"), "16x9": (1920, 1080, "landscape"), "4x5": (1080, 1350, "portrait")}
+
+vdir = Path(sys.argv[1]).resolve()
+proj = vdir / "film"
+film = json.loads((vdir / "film.json").read_text())
+words = json.loads((vdir / "words.json").read_text())
+forced = sys.argv[sys.argv.index("--format") + 1] if "--format" in sys.argv[:-1] else None
+fmt = forced or film.get("format", "9x16")
+if fmt not in SIZES:
+    sys.exit(f"film.json format {fmt!r} must be one of {', '.join(SIZES)}")
+W, H, RES = SIZES[fmt]
+LANG = film.get("language", "id")
+
+# 1. Preset: a folder with style.json.
+dirs = [WORK / "presets", Path(os.environ.get("KAIZEN_VIDEO_PRESETS", Path.home() / ".kaizen/video-presets")), SKILL / "presets"]
+want = film["preset"]
+preset = next((d / n for n in (want, "film-" + want) for d in dirs if (d / n / "style.json").exists()), None)
+if not preset:
+    names = sorted({p.parent.name for d in dirs if d.exists() for p in d.glob("*/style.json")})
+    sys.exit(f"preset {want!r} not found in {', '.join(map(str, dirs))}; available: {', '.join(names)}")
+print(f"preset {preset}")
+style = json.loads((preset / "style.json").read_text())
+brand = film.get("brand", {})
+style["palette"] = {**style["palette"], **brand.get("palette", {})}
+style["fonts"] = {**style["fonts"], **brand.get("fonts", {})}
+pace = style["pace"]
+shutil.rmtree(proj / "assets", ignore_errors=True)
+for d in ("img", "video", "sfx", "fonts"):
+    (proj / "assets" / d).mkdir(parents=True)
+
+
+def probe(f, entry, kind="format"):
+    out = subprocess.check_output(["ffprobe", "-v", "error", "-show_entries", f"{kind}={entry}", "-of", "csv=p=0", str(f)])
+    return out.decode().strip()
+
+
+def run(*cmd, cwd=proj):
+    subprocess.run(cmd, check=True, cwd=cwd)
+
+
+# 2. Timeline: every beat is lead + its voice line + tail (+ hold), in whole frames, one after another.
+t, beats = 0, []
+for n, b in enumerate(film["beats"]):
+    v = b.get("vo")
+    if v and v not in words:
+        sys.exit(f"beat {n + 1}: voice {v!r} is not in words.json; run vo.py first")
+    frames = round(((pace["lead"] + words[v]["dur"] + pace["tail"]) if v else 0) * FPS + b.get("hold", 0) * FPS)
+    if frames:
+        beats.append({**b, "n": n, "start": t / FPS, "len": frames / FPS, "dur": words[v]["dur"] if v else 0})
+    else:
+        print(f"warning: beat {n + 1} ({b['kind']}) has no voice and no hold, so it is skipped")
+    t += frames
+total = t / FPS
+reveal = next((b["start"] for b in beats if b["kind"] == "reveal"), total / 2)
+
+# 3. Pictures, footage, logo, QR into the project (a photo name may be a stem: intake writes <stem>-9x16.jpg).
+def stage(name, sub):
+    if not name:
+        return name
+    src = vdir / name
+    for tag in (fmt, "9x16") if fmt == "4x5" else (fmt,):   # a film intaken before 4x5 existed uses its 9x16 crops
+        if not src.exists():
+            src = vdir / f"{Path(name).stem}-{tag}.jpg"
+    if not src.exists():
+        sys.exit(f"file {name!r} not found in {vdir}")
+    flat = re.sub(r"[\\/]", "_", str(src.relative_to(vdir)))
+    shutil.copy(src, proj / "assets" / sub / flat)
+    return f"assets/{sub}/{flat}"
+
+
+for b in beats:
+    b["img"], b["video"] = stage(b.get("img"), "img"), stage(b.get("video"), "video")
+    if b.get("panels"):
+        b["panels"] = [{**p, "img": stage(p["img"], "img")} for p in b["panels"]]
+    if b["kind"] == "shot" and b["img"] and not b.get("shotRatio"):
+        b["shotRatio"] = round(int(probe(proj / b["img"], "width", "stream")) / int(probe(proj / b["img"], "height", "stream")), 3)
+labels = {"source": "Sumber" if LANG == "id" else "Source", "next": "Langkah berikutnya" if LANG == "id" else "Next step", **film.get("labels", {})}
+
+# 4. Captions: subtitle chunks of up to 7 words (also the .srt cues), or kinetic groups of 2-3 words.
+def chunks(ws):
+    out, cur = [], []
+    for w in ws:
+        cur.append(w)
+        if len(cur) >= 7 or re.search(r"[.,?!]$", w["w"]):
+            out.append(cur)
+            cur = []
+    return out + ([cur] if cur else [])
+
+
+def groups(ws):
+    out, i = [], 0
+    while i < len(ws):
+        k = 2 if len("".join(w["w"] for w in ws[i:i + 3])) > 16 else 3
+        out.append(ws[i:i + k])
+        i += k
+    return out
+
+
+captions, cues = [], []
+for b in beats:
+    if not b.get("vo"):
+        continue
+    t0 = b["start"] + pace["lead"]
+    ws = [{"w": w["w"], "s": round(t0 + w["s"], 3), "e": round(t0 + w["e"], 3)} for w in words[b["vo"]]["words"]]
+    cues += [[c[0]["s"], c[-1]["e"] + 0.2, " ".join(w["w"] for w in c)] for c in chunks(ws)]
+    if b["kind"] == "cta" or style["captions"] == "none":
+        continue
+    gs = chunks(ws) if style["captions"] == "subtitle" else groups(ws)
+    for i, g in enumerate(gs):
+        nxt = gs[i + 1][0]["s"] if i + 1 < len(gs) else min(g[-1]["e"] + 0.4, b["start"] + b["len"])
+        captions.append({"s": round(max(b["start"], g[0]["s"] - (0.05 if i == 0 else 0)), 3), "e": round(nxt, 3), "words": g})
+for a, c in zip(cues, cues[1:]):
+    a[1] = round(min(a[1], c[0] - 0.02), 3)  # no overlapping cues
+proj.mkdir(exist_ok=True)
+(proj / "cues.json").write_text(json.dumps(cues, ensure_ascii=False))
+
+film_data = {"fmt": fmt, "W": W, "H": H, "language": LANG, "style": style, "labels": labels, "total": total, "beats": beats, "captions": captions,
+             "cta": film.get("cta"), "logo": stage(film.get("logo"), "img"), "logoOnLight": stage(film.get("logoOnLight"), "img"), "qr": stage(film.get("qr"), "img")}
+(proj / "film-data.js").write_text("window.FILM = " + json.dumps(film_data, ensure_ascii=False) + ";\n")
+
+# 5. Audio: the voice lines on one track, the music bed with the style's levels, sound effects and room tone.
+def ffmpeg(*args):
+    run("ffmpeg", "-v", "error", "-y", *args)
+
+
+ins, graph = [], []
+for i, b in enumerate(x for x in beats if x.get("vo")):
+    ins += ["-i", str(vdir / f"{b['vo']}.mp3")]
+    ms = round((b["start"] + pace["lead"]) * 1000)
+    graph.append(f"[{i}:a]aformat=sample_rates=48000:channel_layouts=stereo,atrim=start={words[b['vo']]['offset']},asetpts=PTS-STARTPTS,adelay={ms}|{ms}[a{i}]")
+if not graph:
+    sys.exit("no beat has a voice line (vo); a film needs narration")
+mix = "".join(f"[a{i}]" for i in range(len(graph)))
+ffmpeg(*ins, "-filter_complex", ";".join(graph) + f";{mix}amix=inputs={len(graph)}:normalize=0:duration=longest,apad[o]",
+       "-map", "[o]", "-t", str(total), "-ar", "48000", "assets/vo.wav")
+
+music = style["music"]
+track = vdir / music["track"]
+if film.get("music"):
+    track = SKILL / "assets/music" / f"{film['music']}.mp3"
+if not track.exists():
+    sys.exit(f"no music: put {music['track']} in {vdir} (scripts/music.sh) or set film.json \"music\" to one of: "
+             + ", ".join(sorted(p.stem for p in (SKILL / "assets/music").glob("*.mp3"))))
+pts = [(0, 0), (1, music["base"]), (max(1, reveal - 0.5), music["base"]), (reveal + 1 / 3, music["lift"]), (reveal + 3, music["base"] + 0.04),
+       (total - 2, music["base"] + 0.04), (total, 0)]
+pts = [p for i, p in enumerate(pts) if i == 0 or p[0] > pts[i - 1][0]]  # a short film can fold the points back on themselves
+expr = f"{pts[-1][1]}"
+for (t0, a0), (t1, a1) in reversed(list(zip(pts, pts[1:]))):
+    expr = f"if(lt(t,{t1}),{a0}+({a1}-{a0})*(t-{t0})/({t1}-{t0}),{expr})"
+ffmpeg("-i", str(track), "-af", f"aloop=loop=-1:size=2e9,atrim=0:{total},loudnorm=I=-16:TP=-1.5,volume='{expr}':eval=frame,aformat=sample_rates=48000:channel_layouts=stereo", "assets/music.wav")
+
+LIB = HOME / "sfx"
+
+
+def sound(name):
+    def find():
+        return next((f for d in (vdir / "sfx", preset / "assets/sfx", LIB) for e in (".wav", ".mp3") if (f := d / (name + e)).exists()), None)
+    if not find() and not (LIB / "whoosh.mp3").exists():  # make the shared library once, synthesized (no ElevenLabs credits spent unless SFX_PROVIDER says so)
+        run("python3", str(SKILL / "scripts/sfx.py"), "--provider", os.environ.get("SFX_PROVIDER", "synth"))
+    f = find()
+    if not f:
+        sys.exit(f"sound {name!r} not found in {vdir / 'sfx'}, {preset / 'assets/sfx'} or {LIB}")
+    shutil.copy(f, proj / "assets/sfx" / f.name)
+    return f.name
+
+
+fx = style["sfx"]
+sfx, amb = [], []   # (file, start, volume)
+for i, b in enumerate(beats):
+    cut = fx["reveal"] if b["kind"] == "reveal" else fx["question"] if b["kind"] == "question" else fx["cut"] if i else ""
+    if cut:
+        sfx.append((sound(cut), b["start"], 0.7 if b["kind"] == "reveal" else 0.35))
+    sfx += [(sound(s), b["start"] + pace["lead"], 0.45) for s in b.get("sfx", [])]
+    if fx["text"] and b.get("title") and i:
+        sfx.append((sound(fx["text"]), b["start"] + pace["lead"] + 0.2, 0.25))
+    if b.get("ambience"):
+        a = sound(b["ambience"])
+        ffmpeg("-stream_loop", "-1", "-i", f"assets/sfx/{a}", "-t", str(b["len"]), "-af", f"afade=t=in:d=0.3,afade=t=out:st={max(0, b['len'] - 0.3)}:d=0.3,aformat=sample_rates=48000:channel_layouts=stereo", f"assets/amb-{i}.wav")
+        amb.append((f"amb-{i}.wav", b["start"], b["len"]))
+tracks, tags = {}, []   # greedy track numbers from 3, so no two sounds overlap on one track (HyperFrames lint)
+
+
+def place(tag, start, dur):
+    k = next(k for k in range(3, 99) if tracks.get(k, -1) <= start)
+    tracks[k] = start + dur
+    tags.append(tag.replace("TRACK", str(k)))
+
+
+for i, (name, start, vol) in enumerate(sorted(sfx, key=lambda x: x[1])):
+    d = round(float(probe(proj / "assets/sfx" / name, "duration")), 2)
+    place(f'<audio id="sfx-{i}" src="assets/sfx/{name}" data-start="{start:.2f}" data-duration="{d}" data-track-index="TRACK" data-volume="{vol}"></audio>', start, d)
+for i, (name, start, dur) in enumerate(amb):
+    place(f'<audio id="amb-{i}" src="assets/{name}" data-start="{start:.2f}" data-duration="{dur}" data-track-index="TRACK" data-volume="0.18"></audio>', start, dur)
+audio = "\n      ".join([f'<audio id="vo" src="assets/vo.wav" data-start="0" data-duration="{total}" data-track-index="1"></audio>',
+                        f'<audio id="music" src="assets/music.wav" data-start="0" data-duration="{total}" data-track-index="2"></audio>'] + tags)
+
+# 6. Fonts (the style's, plus Inter for kinetic captions), the page, carve the music around the voice, check.
+faces = []
+fonts = set(style["fonts"].values()) | ({"Inter"} if style["captions"] == "kinetic" else set())
+for fam in sorted(fonts):
+    stem = fam.replace(" ", "")
+    for suffix, slant in (("", "normal"), ("-Italic", "italic")):
+        src = next((f for d in (preset / "assets/fonts", SKILL / "assets/film-fonts", SKILL / "assets/fonts") if (f := d / f"{stem}{suffix}.ttf").exists()), None)
+        if src:
+            shutil.copy(src, proj / "assets/fonts" / src.name)
+            faces.append(f'@font-face {{ font-family: "{fam}"; src: url("assets/fonts/{src.name}"); font-weight: 100 900; font-style: {slant}; }}')
+        elif not suffix:
+            sys.exit(f"font {fam!r} not found: add {stem}.ttf to the preset's assets/fonts or the skill's assets/film-fonts")
+page = (SKILL / "film.html").read_text()
+for k, v in {"W": W, "H": H, "RES": RES, "DURATION": total, "LANG": LANG}.items():
+    page = page.replace("{{" + k + "}}", str(v))
+page = page.replace("/*FONTS*/", "\n      ".join(faces)).replace("<!-- AUDIO -->", audio)
+(proj / "index.html").write_text(page)
+shutil.copy(SKILL / "hyperframes.json", proj / "hyperframes.json")
+(proj / "package.json").write_text(json.dumps({"name": "kaizen-film", "private": True, "type": "module", "devDependencies": {"@hyperframes/core": HF.split("@")[1]}}, indent=2))
+if not (proj / "node_modules/@hyperframes/core").exists():
+    run("npm", "install", "--silent")
+run("node", str(SKILL / "tools/carve.mjs"), "--comp", "index.html", "--bed", "music", "--voice", "vo")
+run("npx", "--yes", HF, "check")
+print(f"{len(beats)} beats, {len(captions)} caption groups, {len(sfx)} sfx, {fmt}, {total}s")
+
+# 7. Credits and master data, then render + master with --render.
+name = film.get("name", vdir.name) + (f"-{fmt}" if forced else "")
+line = re.compile(rf"^- {re.escape(music['track'] if not film.get('music') else film['music'])}\.mp3: (.+)$", re.M)
+bundled = (SKILL / "assets/CREDITS.txt").read_text() if (SKILL / "assets/CREDITS.txt").exists() else ""
+credits = [f.read_text().strip() for f in [vdir / "CREDITS.txt", *sorted(vdir.glob("CREDITS-*.txt"))] if f.exists()]
+if film.get("music") and (m := line.search(bundled)):
+    credits.append("Music: " + m.group(1))
+credits += [f.read_text().strip() for f in (preset / "CREDITS.txt",) if f.exists()]
+credits.append("Voice and sound effects: see the voice provider in film.json (ElevenLabs commercial use requires a paid plan).")
+(proj / "CREDITS.txt").write_text("\n\n".join(credits) + "\n")
+(proj / "meta.json").write_text(json.dumps({"name": name, "folder": film.get("name", vdir.name), "preset": preset.name, "loudness": style["loudness"]}))
+if "--render" in sys.argv:
+    run("bash", str(SKILL / "scripts/master.sh"), str(vdir), cwd=WORK)