kaizen-agent 1.47.0 → 1.49.0

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

@@ -0,0 +1,213 @@
+"""Build (and optionally render) a TikTok video from a preset + a per-video config.
+
+    python3 scripts/make_tiktok.py videos/<name> [--render]
+
+Run from the project folder. Writes the HyperFrames project into videos/<name>/tiktok/
+and, with --render, overwrites output/<name>/<preset>/<name>.mp4 so revisions of the
+same preset never pile up while different presets stay separate.
+
+The preset is found by folder name in ./presets/, then $KAIZEN_VIDEO_PRESETS
+(default ~/.kaizen/video-presets/), then the skill's bundled presets/. A preset file
+missing from its folder falls back to the skill's shared assets/, tools/ and
+hyperframes.json.
+"""
+import html
+import os
+import json
+import shutil
+import subprocess
+import re
+import sys
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parent.parent
+WORK = Path.cwd()
+HF = "hyperframes@0.8.176"
+FPS = 30
+SFX_TRACK = {"reveal": 4, "ending": 6, "shutter": 3, "stamp": 4, "ding": 4, "whoosh": 6}  # any other sound: track 5
+CARD_DUR = {"title": 1.8, "case": 3.2, "photo": 2.8}
+
+vdir = Path(sys.argv[1]).resolve()
+proj = vdir / "tiktok"
+proj.mkdir(exist_ok=True)
+cfg = json.loads((vdir / "config.json").read_text())
+dirs = [WORK / "presets", Path(os.environ.get("KAIZEN_VIDEO_PRESETS", Path.home() / ".kaizen/video-presets")), SKILL / "presets"]
+preset = next((d / cfg["preset"] for d in dirs if (d / cfg["preset"] / "index.html").exists()), None)
+if not preset:
+    names = sorted({p.parent.name for d in dirs if d.exists() for p in d.glob("*/index.html")})
+    sys.exit(f"preset {cfg['preset']!r} not found in {', '.join(map(str, dirs))}; available: {', '.join(names)}")
+print(f"preset {preset}")
+src_of = lambda p: next(f for f in (preset / p, SKILL / p) if f.exists())  # preset file, else the shared one
+rel = lambda p: (vdir / p).resolve()
+
+
+def run(*cmd, **kw):
+    subprocess.run(cmd, check=True, cwd=proj, **kw)
+
+
+# 1. Preset files and this video's images into the project.
+for f in ["package.json", "hyperframes.json"]:
+    shutil.copy(src_of(f), proj / f)
+for d in ["fonts", "sfx"]:
+    shutil.rmtree(proj / "assets" / d, ignore_errors=True)
+    for base in (SKILL, preset):  # shared assets first, the preset's own on top
+        if (base / "assets" / d).exists():
+            shutil.copytree(base / "assets" / d, proj / "assets" / d, dirs_exist_ok=True)
+if (vdir / "images").exists():
+    shutil.copytree(vdir / "images", proj / "assets/img", dirs_exist_ok=True)
+
+# 2. Captions: WhisperX words, remapped onto the cut when a render plan is given.
+words = [w for s in json.loads(rel(cfg["words"]).read_text())["segments"] for w in s["words"] if "start" in w]
+if cfg.get("plan"):
+    # Segment length is its time span: phone footage is often VFR, so frames / nominal fps is wrong.
+    segs = [(s["start_time"], s["end_time"], s["end_time"] - s["start_time"]) for s in json.loads(rel(cfg["plan"]).read_text())["segments"]]
+else:
+    segs = [(0.0, 1e9, None)]
+chunks, seg_starts, offset = [], [], 0.0
+for s0, s1, length in segs:
+    seg_starts.append(round(offset, 3))
+    end_cut = offset + length if length else words[-1]["end"]
+    cur = []
+    for w in words:
+        # Skip words the cut slices to a few frames (they flash as glitches).
+        if not (s0 - 0.05 <= w["start"] < s1) or (w["end"] > s1 and s1 - w["start"] < 0.12):
+            continue
+        word = w["word"].strip()
+        core = word.rstrip(",.?!")
+        word = cfg.get("fix", {}).get(core, core) + word[len(core):]  # caption spelling corrections
+        cur.append({"w": word, "s": round(offset + w["start"] - s0, 3),
+                    "e": round(min(offset + w["end"] - s0, end_cut), 3)})
+        # ponytail: fixed 3-word chunks, break early on punctuation
+        if len(cur) == 3 or cur[-1]["w"][-1] in ",.?!":
+            chunks.append(cur)
+            cur = []
+    if cur:
+        chunks.append(cur)
+    offset = end_cut
+cut_duration = offset
+flat = [w for c in chunks for w in c]
+
+
+def at(key, after=0):
+    try:
+        return next(w["s"] for w in flat if w["s"] >= after and w["w"].lower().strip(",.?!").startswith(key))
+    except StopIteration:
+        sys.exit(f"config error: no word starting with {key!r} after {after}s")
+
+
+# Cold open: replay one strong line before the intro (TikTok hook). Everything else shifts by its length.
+co = cfg.get("cold_open")
+if co:
+    co_a = at(co["from"], co.get("after", 0)) - 0.08
+    co_b = next(w["e"] for w in flat if w["s"] >= co_a and w["w"].lower().strip(",.?!").startswith(co["to"])) + 0.25
+else:
+    co_a = co_b = 0.0
+L = round(co_b - co_a, 3)
+beats = sorted(({**{k: v for k, v in b_.items() if k not in ("word", "after")}, "t": round(at(b_["word"], b_.get("after", 0)) + L, 3)}
+                for b_ in cfg["beats"]), key=lambda x: x["t"])
+shift = lambda w, d: {**w, "s": round(w["s"] + d, 3), "e": round(w["e"] + d, 3)}
+cold = [[shift(w, -co_a) for w in c if co_a <= w["s"] and w["e"] <= co_b] for c in chunks] if co else []
+chunks = [c for c in cold if c] + [[shift(w, L) for w in c] for c in chunks]
+seg_starts = ([0.0] if co else []) + [round(x + L, 3) for x in seg_starts]
+video_duration = round(cut_duration + L, 3)
+duration = round(video_duration + cfg.get("tail", 0), 3)  # tail: ending card holds after the footage ends
+for i, c in enumerate(chunks):  # hold each chunk until the next one starts
+    c[-1].pop("hold", None)
+    nxt = chunks[i + 1][0]["s"] if i + 1 < len(chunks) else video_duration
+    c[-1]["hold"] = round(max(c[-1]["e"], min(nxt, c[-1]["e"] + 0.6)), 3)
+cards = [(b["t"], b["t"] + b.get("dur", CARD_DUR.get(b["kind"], 0))) for b in beats if b["kind"] in CARD_DUR]
+for (a0, a1), (b0, _) in zip(cards, cards[1:]):
+    if b0 < a1:
+        print(f"warning: cards overlap at {a0:.2f}s and {b0:.2f}s")
+(proj / "captions.js").write_text(
+    f"window.CAPTIONS = {json.dumps(chunks, ensure_ascii=False)};\n"
+    f"window.SEG_STARTS = {json.dumps(seg_starts)};\n"
+    f"window.BEATS = {json.dumps(beats, ensure_ascii=False)};\n")
+
+# 3. Sound effects: shutter on every card, stamp/ding on their beats, reactions from the config.
+sfx = [("shutter", 0.3, 0.7)]
+for b in beats:
+    if b["kind"] in ("title", "case", "photo"):
+        sfx.append(("shutter", b["t"], 0.7))
+    if b["kind"] == "end":  # reversed gong swells in, hit lands 1.2 s in on the last word slam
+        sfx.append(("ending", max(0, b["t"] + 0.54 - 1.2), 0.9))
+    if b.get("stamp"):
+        sfx.append(("stamp", b["t"] + 1.12, 0.9))
+    if b["kind"] == "item":
+        sfx.append(("reveal", b["t"], 0.6))
+for r in cfg.get("reactions", []):
+    sfx.append((r["sfx"], max(0, at(r["word"], r.get("after", 0)) + L + r.get("offset", 0)), r.get("volume", 0.5)))
+
+
+def sfx_dur(n):
+    f = proj / "assets/sfx" / f"{n}.wav"
+    if not f.exists():
+        sys.exit(f"config error: sound {n!r} is not in preset {cfg['preset']!r}; available: "
+                 + ", ".join(sorted(p.stem for p in (proj / "assets/sfx").glob("*.wav"))))
+    # ffprobe, not the wave module: user-added effects are often float or extensible WAVs
+    return round(float(subprocess.check_output(["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                                                "-of", "csv=p=0", str(f)])), 2)
+
+
+tags = "\n".join(f'      <audio id="sfx-{i}" src="assets/sfx/{n}.wav" data-start="{t:.2f}" data-duration="{sfx_dur(n)}" '
+                 f'data-track-index="{SFX_TRACK.get(n, 5)}" data-volume="{v}"></audio>'
+                 for i, (n, t, v) in enumerate(sorted(sfx, key=lambda x: x[1])))
+
+# 4. Source video: cold open + cut, lanczos upscale to 1080x1920 with light sharpening,
+#    dialogue cleanup (denoise, de-ess). Cached until the inputs or settings change.
+src, key = rel(cfg["video"]), proj / "source.key"
+vf = "scale=1080:1920:flags=lanczos,unsharp=5:5:0.6:5:5:0,fps=30,format=yuv420p"
+af = "afftdn=nf=-28,deesser=i=0.35,aformat=sample_rates=48000:channel_layouts=stereo"
+k = json.dumps([str(src), src.stat().st_mtime, co_a, co_b, vf, af, "g30"])
+if not (proj / "source.mp4").exists() or not key.exists() or key.read_text() != k:
+    if co:
+        graph = (f"[0:v]split[v1][v2];[0:a]asplit[a1][a2];"
+                 f"[v1]trim={co_a}:{co_b},setpts=PTS-STARTPTS[cv];[a1]atrim={co_a}:{co_b},asetpts=PTS-STARTPTS[ca];"
+                 f"[cv][ca][v2][a2]concat=n=2:v=1:a=1[v0][a0];[v0]{vf}[v];[a0]{af}[a]")
+    else:
+        graph = f"[0:v]{vf}[v];[0:a]{af}[a]"
+    run("ffmpeg", "-v", "error", "-y", "-i", str(src), "-filter_complex", graph, "-map", "[v]", "-map", "[a]",
+        "-c:v", "libx264", "-crf", "14", "-preset", "medium", "-g", "30", "-c:a", "aac", "-b:a", "256k", "source.mp4")
+    key.write_text(k)
+
+# 5. Music bed trimmed to length, then the composition from the template.
+run("ffmpeg", "-v", "error", "-y", "-i", str(src_of(f"assets/music/{cfg['music']}.mp3")), "-af",
+    f"aloop=loop=-1:size=2e9,atrim=0:{duration},afade=t=in:d=1,afade=t=out:st={duration - 3.5}:d=3.5,"
+    "aformat=sample_rates=48000:channel_layouts=stereo", "assets/music.wav")  # fades over the tail too
+h = cfg["hook"]
+page = (preset / "index.html").read_text()
+for k, v in {"DURATION": duration, "VIDEO_DURATION": video_duration, "VIDEO": "source.mp4", "MUSIC_VOLUME": cfg.get("music_volume", 0.32),
+             "HOOK_1": html.escape(h["line1"]), "HOOK_2": html.escape(h["line2"]), "HOOK_SUB": html.escape(h["sub"])}.items():
+    page = page.replace("{{" + k + "}}", str(v))
+page = page.replace("<!-- SFX:BEGIN -->", "<!-- SFX:BEGIN -->\n" + tags + "\n      ")
+(proj / "index.html").write_text(page)
+
+# 6. Carve the music around the voice (hyperframes-audio), validate, render.
+if not (proj / "node_modules/@hyperframes/core").exists():
+    run("npm", "install", "--silent")
+run("node", str(src_of("tools/carve.mjs")), "--comp", "index.html", "--bed", "music", "--voice", "a-roll")
+run("npx", "--yes", HF, "check")
+print(f"{len(chunks)} caption chunks, {len(beats)} beats, {len(sfx)} sfx, {duration}s")
+if "--render" in sys.argv:
+    out = WORK / "output" / cfg["name"] / cfg["preset"] / f"{cfg['name']}.mp4"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    # Frame extraction writes gigabytes of temp files; /tmp is often a small tmpfs, which fails as VIDEO_SOURCE_UNRENDERABLE.
+    tmp = proj / ".render-tmp"
+    tmp.mkdir(exist_ok=True)
+    run("npx", "--yes", HF, "render", "--crf", str(cfg.get("crf", 23)), "-o", str(out),  # CRF 23: ~1/3 the size of the default 16, same resolution
+        env={**os.environ, "TMPDIR": str(tmp)})
+    shutil.rmtree(tmp, ignore_errors=True)
+    shutil.rmtree(proj / "renders", ignore_errors=True)
+    # The video's own credits (images, footage), the music bed actually used, then the preset's (fonts, sound effects).
+    # A music credit is the line "- <music>.mp3: ..." in the preset's CREDITS.txt, else in the shared assets/CREDITS.txt.
+    line = re.compile(rf"^- {re.escape(cfg['music'])}\.mp3: (.+)$", re.M)
+    music = next((m.group(1) for f in (preset / "CREDITS.txt", SKILL / "assets/CREDITS.txt")
+                  if f.exists() and (m := line.search(f.read_text()))), None)
+    if not music:
+        print(f"warning: no credit for music {cfg['music']!r}; add '- {cfg['music']}.mp3: ...' to the preset's CREDITS.txt")
+    credits = [f.read_text().strip() for f in (vdir / "CREDITS.txt",) if f.exists()]
+    credits += [f"Music: {music}"] if music else []
+    credits += [f.read_text().strip() for f in (preset / "CREDITS.txt",) if f.exists()]
+    if credits:
+        (out.parent / "CREDITS.txt").write_text("\n\n".join(credits) + "\n")
+    print(f"rendered {out}")

package/skills/{story-video → media/kaizen-video}/scripts/master.sh

@@ -1,26 +1,27 @@
 #!/usr/bin/env bash
-# Render one format of a film, master loudness (two-pass), write .srt + thumbnail + credits.
-# Earlier deliveries move to out/previous/ (never overwritten).
-# Usage: scripts/master.sh <film-dir> <16x9|9x16> <out-name> [lufs: -14 social | -16 presentation] [thumb-second]
+# Render a built film (make_film.py), master loudness (two-pass), write .srt + thumbnail + credits.
+# Run from the project folder. Earlier deliveries move to output/<name>/<preset>/previous/ (never overwritten).
+# Usage: scripts/master.sh <film-dir> [lufs: default from the style, -14 social | -16 presentation] [thumb-second]
+# Writes output/<film>/<preset>/<name>.mp4; <name> is <film>-<shape> when make_film.py ran with --format.
 set -euo pipefail
-DIR=$(cd "${1:?film dir}" && pwd); FMT=${2:?format}; NAME=${3:?name}; LUFS=${4:--16}; THUMB=${5:-3}
+DIR=$(cd "${1:?film dir}" && pwd); THUMB=${3:-3}
 SKILL=$(cd "$(dirname "$0")/.." && pwd)
-ENGINE=${STORY_VIDEO_ENGINE:-$HOME/.kaizen/story-video/engine}
-OUT="$DIR/out"; mkdir -p "$OUT/previous"
+m(){ python3 -c "import json;print(json.load(open('$DIR/film/meta.json')).get('$1',''))"; }
+# folder: the film's name; name: the file's, which make_film.py --format suffixes (gerbang-4x5) so shapes sit side by side.
+NAME=$(m name); FOLDER=$(m folder); PRESET=$(m preset); LUFS=${2:-$(m loudness)}
+OUT="$PWD/output/${FOLDER:-$NAME}/$PRESET"; mkdir -p "$OUT/previous"
 if [ -f "$OUT/$NAME.mp4" ]; then
   stamp=$(date +%Y%m%d-%H%M%S)
   for x in "$OUT/$NAME".mp4 "$OUT/$NAME".srt "$OUT/$NAME"-thumb.jpg; do [ -f "$x" ] && mv "$x" "$OUT/previous/$(basename "${x%.*}")-$stamp.${x##*.}"; done
 fi
-python3 -c "import json,sys; json.dump({'film': json.load(open('$DIR/film.json')), 'words': json.load(open('$DIR/words.json'))}, open('$DIR/.props.json','w'))"
-(cd "$ENGINE" && npx remotion render src/index.ts "Film-$FMT" "$OUT/$NAME.raw.mp4" --props="$DIR/.props.json" --public-dir="$DIR" --log=error 2>&1 | grep -v "network requests" || true)
+(cd "$DIR/film" && npx --yes hyperframes@0.8.176 render --crf 20 -o "$OUT/$NAME.raw.mp4" >/dev/null)
 J=$(ffmpeg -hide_banner -i "$OUT/$NAME.raw.mp4" -af loudnorm=I=$LUFS:TP=-1.5:LRA=11:print_format=json -f null - 2>&1 | sed -n '/{/,/}/p')
 g(){ echo "$J" | python3 -c "import sys,json;print(json.load(sys.stdin)['$1'])"; }
 ffmpeg -v error -y -i "$OUT/$NAME.raw.mp4" -c:v copy -c:a aac -b:a 192k \
   -af "loudnorm=I=$LUFS:TP=-1.5:LRA=11:measured_I=$(g input_i):measured_TP=$(g input_tp):measured_LRA=$(g input_lra):measured_thresh=$(g input_thresh):offset=$(g target_offset):linear=true" \
   "$OUT/$NAME.mp4"
-rm "$OUT/$NAME.raw.mp4" "$DIR/.props.json"
+rm "$OUT/$NAME.raw.mp4"; rm -rf "$DIR/film/renders"
 python3 "$SKILL/scripts/srt.py" "$DIR" "$OUT/$NAME.srt"
 ffmpeg -v error -y -ss "$THUMB" -i "$OUT/$NAME.mp4" -frames:v 1 -q:v 2 "$OUT/$NAME-thumb.jpg"
-cat "$DIR"/CREDITS-*.txt > "$OUT/$NAME-credits.txt" 2>/dev/null || true
-echo "Voice & sound effects: see the voice provider in film.json (ElevenLabs commercial use requires a paid plan)." >> "$OUT/$NAME-credits.txt"
+cp "$DIR/film/CREDITS.txt" "$OUT/CREDITS.txt"
 ffprobe -v error -show_entries format=duration -of csv=p=0 "$OUT/$NAME.mp4" | xargs -I{} echo "done: $OUT/$NAME.mp4 ({} s, $LUFS LUFS)"

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Render the approved word-timed cut and a Resolve Free import copy."""
+
+import bisect
+import json
+import subprocess
+import sys
+from fractions import Fraction
+from pathlib import Path
+
+
+ROOT = Path(sys.argv[1]).resolve()  # videos/<name>
+RAW = ROOT / "work/censored.mp4"  # censored copy of raw/, when a video needs one
+RAW = RAW if RAW.exists() else next(f for f in sorted((ROOT / "raw").iterdir())
+                                     if f.suffix.lower() in (".mp4", ".mov", ".m4v", ".mkv", ".webm"))
+CUTS = ROOT / "transcript/cuts.json"
+MP4 = ROOT / "work/cut.mp4"
+RESOLVE = ROOT / "work/cut-resolve.mov"
+
+
+def probe(*args):
+    return json.loads(subprocess.check_output(["ffprobe", "-v", "error", *args, str(RAW)]))
+
+
+def count_frames(path):
+    data = json.loads(subprocess.check_output([
+        "ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0",
+        "-show_entries", "stream=nb_read_frames:format=duration", "-of", "json", str(path)
+    ]))
+    return int(data["streams"][0]["nb_read_frames"]), float(data["format"]["duration"])
+
+
+def main():
+    stream = probe("-select_streams", "v:0", "-show_entries", "stream=r_frame_rate,width,height", "-of", "json")["streams"][0]
+    fps = Fraction(stream["r_frame_rate"])
+    frames = probe("-select_streams", "v:0", "-show_frames", "-show_entries", "frame=best_effort_timestamp_time", "-of", "json")["frames"]
+    pts = [float(frame["best_effort_timestamp_time"]) for frame in frames]
+    segments = json.loads(CUTS.read_text())["segments"]
+    assert pts == sorted(pts) and len(segments) > 0
+
+    def nearest(time):
+        i = bisect.bisect_left(pts, time)
+        return min((j for j in (i - 1, i) if 0 <= j < len(pts)), key=lambda j: abs(pts[j] - time))
+
+    plan = []
+    for segment in segments:
+        start, end = nearest(segment["start"]), nearest(segment["end"])
+        assert 0 <= start < end < len(pts)
+        if plan:
+            assert start >= plan[-1]["end_frame"]
+        plan.append({"start_frame": start, "end_frame": end, "start_time": pts[start],
+                     "end_time": pts[end], "frames": end - start, "text": segment["text"]})
+    (ROOT / "transcript/render-plan.json").write_text(json.dumps({
+        "fps": str(fps), "width": stream["width"], "height": stream["height"],
+        "segments": plan
+    }, indent=2) + "\n")
+
+    MP4.parent.mkdir(exist_ok=True)
+    n = len(plan)
+    filters = [f"[0:v]split={n}" + "".join(f"[v{i}]" for i in range(n)),
+               f"[0:a]asplit={n}" + "".join(f"[a{i}]" for i in range(n))]
+    for i, part in enumerate(plan):
+        filters += [f"[v{i}]trim=start_frame={part['start_frame']}:end_frame={part['end_frame']},setpts=PTS-STARTPTS[v{i}o]",
+                    f"[a{i}]atrim=start={part['start_time']:.6f}:end={part['end_time']:.6f},asetpts=PTS-STARTPTS[a{i}o]"]
+    filters.append("".join(f"[v{i}o][a{i}o]" for i in range(n)) + f"concat=n={n}:v=1:a=1[vout][aout]")
+    subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-stats", "-i", str(RAW),
+                    "-filter_complex", ";".join(filters), "-map", "[vout]", "-map", "[aout]",
+                    "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p",
+                    "-c:a", "aac", "-b:a", "192k", "-fps_mode", "passthrough",
+                    "-movflags", "+faststart", "-y", str(MP4)], check=True)
+
+    expected_frames = sum(part["frames"] for part in plan)
+    expected_duration = sum(part["end_time"] - part["start_time"] for part in plan)
+    actual_frames, actual_duration = count_frames(MP4)
+    assert actual_frames == expected_frames, (actual_frames, expected_frames)
+    assert abs(actual_duration - expected_duration) < 2 / float(fps), (actual_duration, expected_duration)
+
+    subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-stats", "-i", str(MP4),
+                    "-c:v", "dnxhd", "-profile:v", "dnxhr_lb", "-pix_fmt", "yuv422p",
+                    "-c:a", "pcm_s16le", "-fps_mode", "passthrough", "-y", str(RESOLVE)], check=True)
+    resolve_frames, resolve_duration = count_frames(RESOLVE)
+    assert resolve_frames == expected_frames, (resolve_frames, expected_frames)
+    assert abs(resolve_duration - expected_duration) < 2 / float(fps), (resolve_duration, expected_duration)
+    print(f"{n} cuts; {expected_frames} frames at nominal {fps} fps; MP4 {actual_duration:.3f}s; Resolve MOV {resolve_duration:.3f}s")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Install WhisperX once per machine, shared by every project.
+# Usage: scripts/setup.sh   -> ~/.kaizen/kaizen-video/{whisperx-venv,huggingface}  (override KAIZEN_VIDEO_HOME)
+set -euo pipefail
+"$(dirname "$0")/check.sh" >/dev/null || { "$(dirname "$0")/check.sh"; exit 1; }
+HOME_DIR=${KAIZEN_VIDEO_HOME:-$HOME/.kaizen/kaizen-video}
+VENV="$HOME_DIR/whisperx-venv"
+if ! "$VENV/bin/python" -c "import whisperx" 2>/dev/null; then
+  mkdir -p "$HOME_DIR"
+  uv venv -q -p 3.11 "$VENV"
+  uv pip install -q -p "$VENV/bin/python" "whisperx==3.8.6"
+fi
+mkdir -p "$HOME_DIR/huggingface"
+echo "whisperx: HF_HOME=$HOME_DIR/huggingface $VENV/bin/python <skill>/scripts/transcribe.py videos/<name>"

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

@@ -1,8 +1,8 @@
-"""Build the sound-effect / room-tone library into the shared engine (~/.kaizen/story-video/engine/sfx/).
+"""Build the sound-effect / room-tone library on this machine (~/.kaizen/kaizen-video/sfx/; override KAIZEN_VIDEO_HOME).
 Usage: python3 scripts/sfx.py [--provider synth|elevenlabs] [--force]
   synth       (default without ELEVENLABS_API_KEY) — synthesized locally with ffmpeg; free, no licence limits.
   elevenlabs  (default with a key) — generated sound effects; commercial use needs a paid ElevenLabs plan.
-Only missing files are made unless --force. Names are what presets.json and beats (sfx/ambience) use.
+Only missing files are made unless --force. Names are what a film preset's style.json and beats (sfx/ambience) use.
 No sound files ship with the skill: every machine makes its own."""
 import json, os, subprocess, sys, urllib.request
 
@@ -43,7 +43,7 @@ SYNTH = {
 args = sys.argv[1:]
 force = "--force" in args
 provider = args[args.index("--provider") + 1] if "--provider" in args else ("elevenlabs" if os.environ.get("ELEVENLABS_API_KEY") else "synth")
-SFX = os.path.expanduser(os.environ.get("STORY_VIDEO_ENGINE", "~/.kaizen/story-video/engine")) + "/sfx"
+SFX = os.path.expanduser(os.environ.get("KAIZEN_VIDEO_HOME", "~/.kaizen/kaizen-video")) + "/sfx"
 os.makedirs(SFX, exist_ok=True)
 H = {"xi-api-key": os.environ.get("ELEVENLABS_API_KEY", ""), "Content-Type": "application/json"}
 print("sfx provider:", provider)

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

@@ -0,0 +1,9 @@
+"""Write an .srt from the cues make_film.py computed (<film-dir>/film/cues.json: [[start, end, text], ...]).
+Usage: python3 scripts/srt.py <film-dir> <out.srt>"""
+import json, sys
+cues = json.load(open(f"{sys.argv[1]}/film/cues.json"))
+def ts(sec):
+    ms = int(round(sec * 1000)); h, ms = divmod(ms, 3600000); m, ms = divmod(ms, 60000); s, ms = divmod(ms, 1000)
+    return f"{h:02}:{m:02}:{s:02},{ms:03}"
+open(sys.argv[2], "w").write("\n".join(f"{i}\n{ts(s)} --> {ts(e)}\n{t}\n" for i, (s, e, t) in enumerate(cues, 1)))
+print("srt", len(cues), "cues")

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Quick check frames of a built film: scripts/still.sh <film-dir> <second> [<second>...]
+# -> <film-dir>/film/check/at-<second>s.png (run make_film.py first; delete the folder after looking)
+set -euo pipefail
+DIR=$(cd "$1" && pwd); shift
+IFS=,; (cd "$DIR/film" && npx --yes hyperframes@0.8.176 snapshot --at "$*" --no-end -o check >/dev/null)
+ls "$DIR"/film/check/*.png

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

@@ -0,0 +1,45 @@
+"""Transcribe the footage in videos/<name>/raw/ with WhisperX: <whisperx python> transcribe.py videos/<name>
+
+Uses CUDA (float16) when torch sees a GPU, otherwise CPU (int8); KAIZEN_VIDEO_DEVICE=cpu|cuda overrides.
+"""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import torch
+import whisperx
+
+VIDEO = (".mp4", ".mov", ".m4v", ".mkv", ".webm")
+
+
+root = Path(sys.argv[1]).resolve()
+audio_path = root / "transcript/audio.wav"
+output_path = root / "transcript/words.json"
+
+if output_path.exists():
+    print(f"Using existing {output_path}")
+    raise SystemExit(0)
+
+if not audio_path.exists():
+    audio_path.parent.mkdir(exist_ok=True)
+    raw = next(f for f in sorted((root / "raw").iterdir()) if f.suffix.lower() in VIDEO)
+    subprocess.run(["ffmpeg", "-v", "error", "-i", str(raw), "-vn", "-ac", "1", "-ar", "16000", str(audio_path)], check=True)
+
+audio = whisperx.load_audio(str(audio_path))
+device = os.environ.get("KAIZEN_VIDEO_DEVICE") or ("cuda" if torch.cuda.is_available() else "cpu")
+print(f"device {device}, compute {'float16' if device == 'cuda' else 'int8'}")
+model = whisperx.load_model("large-v3", device, compute_type="float16" if device == "cuda" else "int8")
+result = model.transcribe(audio, batch_size=8)
+del model
+
+print(f"language {result['language']}")
+align_model, metadata = whisperx.load_align_model(language_code=result["language"], device=device)
+result = whisperx.align(result["segments"], align_model, metadata, audio, device)
+assert result["word_segments"], "Alignment returned no words"
+
+temporary_path = output_path.with_suffix(".json.tmp")
+temporary_path.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+temporary_path.replace(output_path)
+print(f"Saved {len(result['word_segments'])} words to {output_path}")