kaizen-agent 1.19.4 → 1.20.0

package/skills/story-video/examples/sample-film/film.json

@@ -0,0 +1,16 @@
+{
+ "preset": "cinematic-drama",
+ "language": "en",
+ "voiceProvider": "edge",
+ "edgeVoice": "en-US-AriaNeural",
+ "brand": { "palette": { "accent": "#D9A441", "accentBg": "#D9A441" } },
+ "labels": { "source": "Source", "next": "Next step" },
+ "cta": { "title": "See your own numbers in 20 minutes.", "sub": "Book a demo", "url": "[website]" },
+ "beats": [
+  { "vo": "v01", "kind": "black", "title": "Every café closes at ten.", "sub": "The real work starts after.", "ambience": "amb-night" },
+  { "vo": "v02", "kind": "stat", "kick": "The hidden shift", "stat": [{ "value": 4, "suffix": "+ hours", "label": "a week reconciling receipts (example figure — replace with a sourced one)", "source": "[source]" }] },
+  { "vo": "v03", "kind": "question", "title": "What if the books closed themselves?" },
+  { "vo": "v04", "kind": "reveal", "title": "Ledgerly", "sub": "Bookkeeping that closes with the café.", "line": "Invoices · Cash · Reports" },
+  { "vo": "v05", "kind": "cta", "hold": 2.5 }
+ ]
+}

package/skills/story-video/examples/sample-film/lines.json

@@ -0,0 +1,7 @@
+{
+ "v01": "[calm, warm storyteller] Every café in the city closes at ten. But for the owner, that's when the real work begins.",
+ "v02": "[thoughtful] Most small cafés spend more than four hours a week just reconciling receipts, invoices and cash.",
+ "v03": "[gently curious, rising hope] So what if the books could close themselves, right when the doors do?",
+ "v04": "[warm, proud] Meet Ledgerly. Bookkeeping that closes with the café.",
+ "v05": "[warm, inviting] See your own numbers in twenty minutes. Book a demo today."
+}

package/skills/story-video/references/licensing.md

@@ -0,0 +1,14 @@
+# Licensing — read before publishing
+
+- **Voice provider is the user's choice** (SKILL.md step 0). Edge-tts voices: Microsoft service terms apply; treat as draft quality.
+- **ElevenLabs voice and sound effects**: the free plan does NOT allow commercial use and requires
+  attribution. Anything published for a business (ads, booth, client) needs a paid plan
+  (Starter or above) active when the audio is generated — regenerate after upgrading.
+  Library (community) voices also need a paid plan for API use.
+- **Music**: Kevin MacLeod / incompetech tracks are CC BY 4.0 — credit "Music: <Track> — Kevin MacLeod
+  (incompetech.com), CC BY 4.0" in the description or end credits. `music.sh` writes the credit file.
+- **Photos**: Unsplash licence (free commercial use, no attribution required; credit anyway in notes).
+  Don't use photos with identifiable people in a way that implies endorsement.
+- **Data on screen**: every statistic carries its source on screen (stat `source`).
+- **Contacts on the CTA**: confirm phone numbers, booth numbers and URLs with the user — never reuse
+  contacts seen in someone else's material without confirmation.

package/skills/story-video/references/presets.md

@@ -0,0 +1,21 @@
+# Presets (src/engine/presets.json)
+
+| 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 an entry in presets.json; fields: palette, fonts (Playfair Display / Inter / Fraunces are loaded —
+add others in Film.tsx FONTS), 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/references/production.md

@@ -0,0 +1,29 @@
+# What makes a video publish-grade
+
+Learned by comparing deck-to-video renders against richer productions . The examples are from an Indonesian school product; apply the principles to any product.
+
+## Layers, in order of impact
+1. **Sound design**: room tone under every beat (`ambience`), one-shots on story moments (`pings` for
+   "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.
+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,
+   warm and bright after the reveal. Fix mispronounced words by rewording, not by hoping.
+5. **Rhythm**: vary beat length; hold on silence (`black` with `hold`); pace by preset.
+6. **Real product**: actual screenshots / screen recordings for product beats. Stock photos of code
+   or generic laptops are a last resort.
+7. **Brand**: real logo reveal, consistent palette and type, the same end card every time.
+8. **Texture**: grain + vignette for drama, light leaks for fun; consistent grade on every photo.
+9. **Format-native**: 9:16 has its own script (hook in the first 2 s, ≤ 30 s), not a crop of 16:9.
+10. **Delivery**: master loudness (−14 LUFS social, −16 presentation), SRT, thumbnail, credits.
+
+## QA before delivering
+- Stills from every film at 3–4 points: no text overlap, captions inside safe area, CTA not covered.
+- Length matches the brief (tell the user when the story needs more).
+- `master.sh` printed the final duration and LUFS.
+- Credits file present; licence status stated (see licensing.md).
+- Ask the user to listen once for pronunciation and the mix — the agent cannot hear.

package/skills/story-video/references/revisions.md

@@ -0,0 +1,25 @@
+# Revisions
+
+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 |
+| "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.
+
+## Before re-delivering
+Re-check stills of the beats that changed, master, and say exactly what changed and what did not.

package/skills/story-video/references/script.md

@@ -0,0 +1,30 @@
+# Writing the narration
+
+The user's text (deck, brochure, feature list, brief) is **source material, not the script**.
+Keep its facts and its promise; rewrite everything else for the ear and for the film's theme.
+
+## A narrator tells, a slide lists
+Slide text is fragments ("Tagihan SPP dicatat tangan."). Narration is a person talking to a person:
+full sentences that lead into each other. Read the whole script aloud in one go — if it sounds like
+someone reading bullet points, rewrite it.
+
+| slide-style (don't) | narration (do) |
+|---|---|
+| "Pukul 06.45. Seorang ibu melepas tangan anaknya." | "Seperti ibu ini. Pukul enam empat puluh lima, ia melepas tangan anaknya di depan gerbang, melambaikan tangan, lalu berbalik pulang." |
+| "Tagihan dicatat tangan. Nilai diketik ulang." | "Di ruang tata usaha, tagihan masih ditulis tangan… Sore harinya, para guru mengetik ulang nilai ke Excel." |
+
+## Rules
+1. **One throughline.** Pick one character or situation and return to it ("ibu tadi", "surat izin yang ia kirim pagi tadi"). Callbacks make separate scenes one story.
+2. **Connective tissue.** Open lines with links that carry time and logic: *Dan, Padahal, Sementara itu, Sore harinya, Malam itu, Lalu, Di sini, Bahkan* (en: *And, Meanwhile, That evening, But, So*).
+3. **Vary the rhythm.** Mostly flowing sentences; one short line where it lands ("Lalu… bagaimana jika gerbang itu tetap terbuka?"). Fragments only as deliberate emphasis, at most once or twice per film.
+4. **Narration ≠ on-screen text.** The screen carries the short headline; the voice carries the story around it. Never read the slide.
+5. **Numbers as story, not data dumps.** "Di balik gerbang itu ada lima puluh tiga juta anak…" rather than "Lima puluh tiga juta siswa." Keep the source on screen.
+6. **Match the preset:** drama = documentary storyteller, unhurried; booth = warm presenter, clear; fun = friendly, a smile in the voice, talks to "kamu/Anda"; viral = one sharp hook sentence, then quick, direct.
+7. **Write for the voice:** numbers and acronyms spelled as spoken; avoid words the voice mis-stresses; one emotion tag per line at most, at the start. Commas and "…" make natural pauses.
+8. **Product only after the turn**, introduced like a character ("Inilah <Produk> — …" / "Meet <Product> — …"), then what changes for each person in the story, ending back on the opening image when possible.
+9. **Only claims the source supports** — rewording must not upgrade a feature.
+
+## Check before voicing
+Read it aloud start to finish (or `edge-tts` a quick draft): does each line follow from the last?
+Could a listener retell the story after one hearing? Show the full script to the user for approval —
+voice credits are spent only on an approved script.

package/skills/story-video/scripts/check.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Requirements for story-video. Prints what is missing and how to install it; exit 1 if anything required is missing.
+miss=0
+need(){ command -v "$1" >/dev/null 2>&1 && echo "ok   $1" || { echo "MISSING $1 — $2"; miss=1; }; }
+opt(){ command -v "$1" >/dev/null 2>&1 && echo "ok   $1" || echo "opt  $1 — $2"; }
+need node    "Node.js 18+ (https://nodejs.org or your package manager)"
+need npm     "comes with Node.js"
+need python3 "Python 3.9+"
+need ffmpeg  "ffmpeg (brew install ffmpeg / apt install ffmpeg / pacman -S ffmpeg / winget install ffmpeg)"
+need ffprobe "comes with ffmpeg"
+opt  soffice   "LibreOffice — only for importing .pptx decks"
+opt  pdftoppm  "poppler-utils — only for importing decks"
+opt  markitdown "pip install 'markitdown[pptx]' — only for reading .pptx text"
+python3 -c "import PIL" 2>/dev/null && echo "ok   Pillow" || { echo "MISSING Pillow — pip install pillow"; miss=1; }
+python3 -c "import edge_tts" 2>/dev/null && echo "ok   edge-tts (free voices)" || echo "opt  edge-tts — pip install edge-tts (free voice when there is no 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 — free voice (edge-tts) and synthesized sound effects will be used"
+echo "note first setup downloads the Remotion engine (~750 MB) into ~/.kaizen/story-video/engine"
+exit $miss

package/skills/story-video/scripts/intake.py

@@ -0,0 +1,73 @@
+"""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)
+  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
+  *.pptx/*.pdf deck                     -> slide images in <film-dir>/intake/slides/, text in intake/deck.md
+  brief.md     the user's story/prompt -> copied to <film-dir>/intake/ (read it when writing the treatment)
+Writes <film-dir>/intake.json (asset list) and prints a summary."""
+import json, os, shutil, subprocess, sys
+from pathlib import Path
+from PIL import Image, ImageEnhance
+
+out = Path(sys.argv[1]); src = Path(sys.argv[2]) if len(sys.argv) > 2 else out / "inputs"
+out.mkdir(parents=True, exist_ok=True)
+work = out / "intake"; work.mkdir(parents=True, exist_ok=True)
+manifest = {"photos": [], "screens": [], "footage": [], "logos": [], "slides": [], "palette_suggestion": []}
+IMG = {".jpg", ".jpeg", ".png", ".webp"}
+
+
+def crop(im, w, h, fy=0.5):
+    r = w / h
+    if im.width / im.height > r:
+        nw = int(im.height * r); x = (im.width - nw) // 2; im = im.crop((x, 0, x + nw, im.height))
+    else:
+        nh = int(im.width / r); y = int((im.height - nh) * fy); im = im.crop((0, y, im.width, y + nh))
+    return im.resize((w, h), Image.LANCZOS)
+
+
+def grade(im):
+    im = ImageEnhance.Color(im).enhance(0.85)
+    return Image.blend(im, Image.new("RGB", im.size, (60, 40, 20)), 0.06)
+
+
+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))):
+        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 []:
+    if f.suffix.lower() not in IMG: continue
+    im = Image.open(f); shutil.copy(f, out / f.name)
+    manifest["screens"].append({"file": f.name, "ratio": round(im.width / im.height, 3)})
+for f in sorted((src / "footage").glob("*")) if (src / "footage").exists() else []:
+    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", str(f), "-an", "-vf", "scale='min(1920,iw)':-2", "-c:v", "libx264", "-crf", "20", str(out / (f.stem + ".mp4"))], check=True)
+    manifest["footage"].append(f.stem + ".mp4")
+for f in sorted(src.glob("logo*")):
+    shutil.copy(f, out / f.name); manifest["logos"].append(f.name)
+    im = Image.open(f).convert("RGBA"); im.thumbnail((200, 200))
+    px = [p[:3] for p in (im.get_flattened_data() if hasattr(im, "get_flattened_data") else im.getdata()) if p[3] > 200 and not (max(p[:3]) > 235 and min(p[:3]) > 235) and max(p[:3]) > 30]
+    if px:
+        q = Image.new("RGB", (len(px), 1)); q.putdata(px)
+        cols = q.quantize(colors=4).convert("RGB").getcolors(4) or []
+        manifest["palette_suggestion"] += ["#%02X%02X%02X" % c for _, c in sorted(cols, reverse=True)]
+for f in list(src.glob("*.pptx")) + list(src.glob("*.pdf")):
+    pdf = f
+    if f.suffix == ".pptx":
+        subprocess.run(["soffice", "--headless", "--convert-to", "pdf", "--outdir", str(work), str(f)], check=True, capture_output=True)
+        pdf = work / (f.stem + ".pdf")
+        subprocess.run(f"markitdown '{f}' > '{work}/deck.md'", shell=True)
+    else:
+        subprocess.run(["pdftotext", "-layout", str(f), str(work / "deck.md")])
+    (work / "slides").mkdir(exist_ok=True)
+    subprocess.run(["pdftoppm", "-jpeg", "-r", "80", str(pdf), str(work / "slides" / "s")], check=True)
+    manifest["slides"] = sorted(p.name for p in (work / "slides").glob("*.jpg"))
+if (src / "brief.md").exists():
+    shutil.copy(src / "brief.md", work / "brief.md")
+json.dump(manifest, open(out / "intake.json", "w"), indent=1)
+print(json.dumps({k: (len(v) if isinstance(v, list) else v) for k, v in manifest.items()}))
+print("palette suggestion:", manifest["palette_suggestion"][:4])
+print("read:", work)

package/skills/story-video/scripts/master.sh

@@ -0,0 +1,26 @@
+#!/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]
+set -euo pipefail
+DIR=$(cd "${1:?film dir}" && pwd); FMT=${2:?format}; NAME=${3:?name}; LUFS=${4:--16}; THUMB=${5:-3}
+SKILL=$(cd "$(dirname "$0")/.." && pwd)
+ENGINE=${STORY_VIDEO_ENGINE:-$HOME/.kaizen/story-video/engine}
+OUT="$DIR/out"; 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)
+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"
+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"
+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/story-video/scripts/music.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Fetch a Kevin MacLeod track (incompetech.com, CC BY 4.0 — credit required) into <film-dir>/music.mp3,
+# loudness-normalised and cut to 3 minutes. Usage: scripts/music.sh <film-dir> "Track Name"
+set -euo pipefail
+f=$1; name=$2
+url="https://incompetech.com/music/royalty-free/mp3-royaltyfree/$(python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1]))' "$name").mp3"
+curl -sfL -o /tmp/sv-music.mp3 "$url"
+ffmpeg -v error -y -t 180 -i /tmp/sv-music.mp3 -af loudnorm=I=-16:TP=-1.5:LRA=11 -ar 44100 "$f/music.mp3"
+echo "Music: $name — Kevin MacLeod (incompetech.com), CC BY 4.0" > "$f/CREDITS-music.txt"
+rm -f /tmp/sv-music.mp3; echo "music ok: $name"

package/skills/story-video/scripts/setup.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Prepare a video workspace inside the project's .kaizen and the shared engine (installed once).
+# Usage: scripts/setup.sh <slug>
+#   -> ~/.kaizen/videos/<slug>/{inputs,out,intake}  (all film data and deliverables; override STORY_VIDEO_HOME)
+#   -> ~/.kaizen/story-video/engine                 (Remotion engine + node_modules, shared by all projects)
+set -euo pipefail
+"$(dirname "$0")/check.sh" >/dev/null || { "$(dirname "$0")/check.sh"; exit 1; }
+SLUG=${1:?usage: setup.sh <slug>}
+SKILL=$(cd "$(dirname "$0")/.." && pwd)
+ENGINE=${STORY_VIDEO_ENGINE:-$HOME/.kaizen/story-video/engine}
+if [ ! -d "$ENGINE/node_modules/remotion" ]; then
+  mkdir -p "$ENGINE"
+  cp -r "$SKILL/engine/." "$ENGINE/"
+  (cd "$ENGINE" && npm install --silent --no-audit --no-fund)
+fi
+# keep engine code current with the skill (node_modules untouched)
+cp -r "$SKILL/engine/src" "$SKILL/engine/package.json" "$SKILL/engine/tsconfig.json" "$ENGINE/"
+# sound library: made on this machine (never shipped) — ElevenLabs with a key, otherwise synthesized
+[ "$(ls "$ENGINE/sfx" 2>/dev/null | wc -l)" -ge 14 ] || STORY_VIDEO_ENGINE="$ENGINE" python3 "$SKILL/scripts/sfx.py" ${SFX_PROVIDER:+--provider "$SFX_PROVIDER"}
+DIR="${STORY_VIDEO_HOME:-$HOME/.kaizen/videos}/$SLUG"
+mkdir -p "$DIR/inputs" "$DIR/out/previous" "$DIR/intake"
+[ -e "$DIR/sfx" ] || ln -s "$ENGINE/sfx" "$DIR/sfx"
+[ -f "$DIR/REVISIONS.md" ] || printf '# Revisions — %s\n\n' "$SLUG" > "$DIR/REVISIONS.md"
+echo "engine: $ENGINE"
+echo "film:   $DIR  (put the user's material in $DIR/inputs)"

package/skills/story-video/scripts/sfx.py

@@ -0,0 +1,64 @@
+"""Build the sound-effect / room-tone library into the shared engine (~/.kaizen/story-video/engine/sfx/).
+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.
+No sound files ship with the skill: every machine makes its own."""
+import json, os, subprocess, sys, urllib.request
+
+LIB = {
+    "whoosh": ("soft airy cinematic whoosh transition, short, clean", 1.2),
+    "hit": ("deep warm cinematic impact boom with soft tail, for a logo reveal", 2.5),
+    "riser": ("gentle airy riser building tension, soft, ends cleanly", 2.5),
+    "tick": ("very soft subtle UI tick, minimal click", 0.5),
+    "pop": ("playful bubbly pop sound, bright, short", 0.5),
+    "chime": ("bright happy chime sparkle for a reveal", 1.8),
+    "ping": ("single smartphone chat message notification ping", 0.8),
+    "pings": ("many chat message notification pings stacking up quickly, overwhelming", 3.0),
+    "bell": ("school bell ringing in the distance, Indonesian school morning", 3.0),
+    "keyboard": ("typing on a laptop keyboard in a quiet office", 4.0),
+    "amb-morning": ("quiet morning outdoor ambience with birds and distant children near a school gate", 10.0),
+    "amb-classroom": ("soft classroom room tone with murmuring students and pencil sounds", 10.0),
+    "amb-office": ("quiet office room tone, air conditioner hum, occasional paper rustle", 10.0),
+    "amb-night": ("quiet night ambience indoors at home, crickets outside", 10.0),
+}
+# ffmpeg recipes for the free synthesized library (lavfi sources + filters)
+SYNTH = {
+    "whoosh": "anoisesrc=d=1.2:c=pink:a=0.6,highpass=f=300,lowpass=f=5000,afade=t=in:d=0.5,afade=t=out:st=0.6:d=0.6",
+    "hit": "sine=f=55:d=2.5,volume=1.5,afade=t=out:st=0.05:d=2.4,lowpass=f=200",
+    "riser": "anoisesrc=d=2.5:c=pink:a=0.5,highpass=f=200,afade=t=in:d=2.3,afade=t=out:st=2.35:d=0.15",
+    "tick": "sine=f=1800:d=0.05,afade=t=out:d=0.05,volume=0.6",
+    "pop": "sine=f=620:d=0.12,afade=t=out:d=0.12,volume=0.9",
+    "chime": "sine=f=1318:d=1.8,afade=t=out:d=1.8,volume=0.5",
+    "ping": "sine=f=1046:d=0.4,afade=t=out:d=0.4,volume=0.7",
+    "pings": "sine=f=1046:d=0.18,afade=t=out:d=0.18,apad=pad_dur=0.12,aloop=loop=9:size=13230,volume=0.6",
+    "bell": "sine=f=880:d=3,afade=t=out:d=3,volume=0.5",
+    "keyboard": "anoisesrc=d=4:c=white:a=0.3,highpass=f=2000,volume=0.4,apulsator=hz=9:amount=1",
+    "amb-morning": "anoisesrc=d=10:c=brown:a=0.15,lowpass=f=800,afade=t=in:d=1,afade=t=out:st=9:d=1",
+    "amb-classroom": "anoisesrc=d=10:c=pink:a=0.08,lowpass=f=1200,afade=t=in:d=1,afade=t=out:st=9:d=1",
+    "amb-office": "anoisesrc=d=10:c=brown:a=0.12,lowpass=f=400,afade=t=in:d=1,afade=t=out:st=9:d=1",
+    "amb-night": "anoisesrc=d=10:c=brown:a=0.08,lowpass=f=300,afade=t=in:d=1,afade=t=out:st=9:d=1",
+}
+
+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"
+os.makedirs(SFX, exist_ok=True)
+H = {"xi-api-key": os.environ.get("ELEVENLABS_API_KEY", ""), "Content-Type": "application/json"}
+print("sfx provider:", provider)
+for name, (prompt, sec) in LIB.items():
+    path = f"{SFX}/{name}.mp3"
+    if os.path.exists(path) and not force:
+        continue
+    if provider == "elevenlabs":
+        req = urllib.request.Request("https://api.elevenlabs.io/v1/sound-generation",
+                                     data=json.dumps({"text": prompt, "duration_seconds": sec, "prompt_influence": 0.5}).encode(), headers=H)
+        open(path + ".raw", "wb").write(urllib.request.urlopen(req).read())
+        src = ["-i", path + ".raw"]
+    else:
+        src = ["-f", "lavfi", "-i", SYNTH[name]]
+    subprocess.run(["ffmpeg", "-v", "error", "-y", *src, "-af", "loudnorm=I=-18:TP=-2", "-ar", "44100", "-ac", "2", path], check=True)
+    if os.path.exists(path + ".raw"):
+        os.remove(path + ".raw")
+    print("made", name)

package/skills/story-video/scripts/srt.py

@@ -0,0 +1,30 @@
+"""Write an .srt from film.json + words.json using the same timeline as the engine.
+Usage: python3 scripts/srt.py <film-dir> <out.srt>"""
+import json, sys
+folder, out = sys.argv[1], sys.argv[2]
+film = json.load(open(f"{folder}/film.json")); words = json.load(open(f"{folder}/words.json"))
+import os
+ENGINE = os.path.expanduser(os.environ.get("STORY_VIDEO_ENGINE", "~/.kaizen/story-video/engine"))
+p = json.load(open(f"{ENGINE}/src/engine/presets.json"))[film["preset"]]
+FPS = 30
+def blen(b):
+    v = (p["pace"]["lead"] + words[b["vo"]]["dur"] + p["pace"]["tail"]) if b.get("vo") else 0
+    return round((v + b.get("hold", 0)) * FPS)
+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}"
+start, cues = 0, []
+for b in film["beats"]:
+    if b.get("vo"):
+        ws = words[b["vo"]]["words"]; t0 = start / FPS + p["pace"]["lead"]
+        chunk = []
+        for w in ws:
+            chunk.append(w)
+            if len(chunk) >= 7 or w["w"][-1] in ".,?!" or w is ws[-1]:
+                cues.append([t0 + chunk[0]['s'], t0 + chunk[-1]['e'] + 0.2, ' '.join(x['w'] for x in chunk)])
+                chunk = []
+    start += blen(b)
+for a_, b_ in zip(cues, cues[1:]):
+    a_[1] = min(a_[1], b_[0] - 0.02)  # no overlapping cues
+lines = [f"{i}\n{ts(s)} --> {ts(e)}\n{t}\n" for i, (s, e, t) in enumerate(cues, 1)]
+open(out, "w").write("\n".join(lines)); print("srt", len(cues), "cues")

package/skills/story-video/scripts/still.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Quick check frames: scripts/still.sh <film-dir> <16x9|9x16> <frame> [<frame>...]  -> <film-dir>/out/check-<frame>.jpg
+set -euo pipefail
+DIR=$(cd "$1" && pwd); FMT=$2; shift 2
+ENGINE=${STORY_VIDEO_ENGINE:-$HOME/.kaizen/story-video/engine}
+python3 -c "import json; json.dump({'film': json.load(open('$DIR/film.json')), 'words': json.load(open('$DIR/words.json'))}, open('$DIR/.props.json','w'))"
+for fr in "$@"; do
+  (cd "$ENGINE" && npx remotion still src/index.ts "Film-$FMT" "$DIR/out/check-$fr.jpg" --frame="$fr" --props="$DIR/.props.json" --public-dir="$DIR" --image-format=jpeg --scale=0.33 --log=error 2>&1 | grep -iv network | tail -1 || true)
+done
+rm "$DIR/.props.json"; ls "$DIR"/out/check-*.jpg

package/skills/story-video/scripts/vo.py

@@ -0,0 +1,99 @@
+"""Voice-over with word timings (ElevenLabs eleven_v3, with-timestamps).
+Usage: python3 scripts/vo.py <film-dir> [voice_id] [only,keys]
+Reads <film-dir>/lines.json {"v01": "[softly] Text...", ...}; writes vNN.mp3 + words.json.
+Emotion tags in [brackets] direct the delivery and are removed from the captions.
+Voice and language come from film.json ("voice", "language"); defaults: Matilda, "id"."""
+import base64, json, os, re, subprocess, sys, urllib.request
+
+film_dir = sys.argv[1].rstrip("/")
+out = film_dir + "/"
+film = json.load(open(out + "film.json")) if os.path.exists(out + "film.json") else {}
+voice = (sys.argv[2] if len(sys.argv) > 2 and sys.argv[2] else None) or film.get("voice") or "XrExE9yKIg1WjnnlVkGX"
+lang = film.get("language", "id")
+H = {"xi-api-key": os.environ.get("ELEVENLABS_API_KEY", ""), "Content-Type": "application/json"}
+lines = json.load(open(out + "lines.json"))
+prev = json.load(open(out + "words.json")) if os.path.exists(out + "words.json") else {}
+only = set(sys.argv[3].split(",")) if len(sys.argv) > 3 else None  # regenerate only these keys
+
+
+def words_from(alignment):
+    chars, starts, ends = alignment["characters"], alignment["character_start_times_seconds"], alignment["character_end_times_seconds"]
+    words, cur, s, e, depth = [], "", None, None, 0
+    for ch, cs, ce in zip(chars, starts, ends):
+        if ch == "[": depth += 1; continue
+        if ch == "]": depth -= 1; continue
+        if depth: continue
+        if ch.isspace():
+            if cur.strip(): words.append({"w": cur.strip(), "s": s, "e": e})
+            cur, s = "", None
+            continue
+        if s is None: s = cs
+        cur += ch; e = ce
+    if cur.strip(): words.append({"w": cur.strip(), "s": s, "e": e})
+    return [w for w in words if re.search(r"\w", w["w"])]
+
+
+EDGE_DEFAULT = {"id": "id-ID-GadisNeural", "en": "en-US-AriaNeural", "ms": "ms-MY-YasminNeural"}
+
+
+def edge_line(key, text):
+    """Free fallback (Microsoft Edge neural voices via edge-tts, `pip install edge-tts`). No emotion
+    control: tags are removed. Word timings come from the WordBoundary events."""
+    import asyncio, edge_tts
+    clean = re.sub(r"\[[^\]]*\]\s*", "", text)
+    v = film.get("edgeVoice") or EDGE_DEFAULT.get(lang, "en-US-AriaNeural")
+    words, audio = [], bytearray()
+    async def run():
+        async for ch in edge_tts.Communicate(clean, v, rate="-5%", boundary="WordBoundary").stream():
+            if ch["type"] == "audio": audio.extend(ch["data"])
+            elif ch["type"] == "WordBoundary":
+                st = ch["offset"] / 1e7; words.append({"w": ch["text"], "s": st, "e": st + ch["duration"] / 1e7})
+    asyncio.run(run())
+    return bytes(audio), words, clean
+
+
+provider = film.get("voiceProvider") or ("elevenlabs" if os.environ.get("ELEVENLABS_API_KEY") else "edge")
+print("voice provider:", provider)
+result = dict(prev)
+for key, text in lines.items():
+    if only and key not in only:
+        continue
+    if provider == "edge":
+        audio, ws, clean = edge_line(key, text)
+        raw = out + key + ".raw.mp3"; open(raw, "wb").write(audio)
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", raw, "-af", "loudnorm=I=-16:TP=-1.5", "-ar", "44100", out + key + ".mp3"], check=True)
+        os.remove(raw)
+        ws = [w for w in ws if re.search(r"\w", w["w"])]
+        # edge-tts drops punctuation; take each word's spelling from the script so captions keep it
+        toks = clean.split(); ti = 0
+        for w in ws:
+            core = re.sub(r"\W", "", w["w"]).lower()
+            for j in range(ti, min(ti + 4, len(toks))):
+                if re.sub(r"\W", "", toks[j]).lower() == core:
+                    w["w"] = toks[j]; ti = j + 1; break
+        offset = max(0.0, ws[0]["s"] - 0.05)
+        for w in ws:
+            w["s"] = round(w["s"] - offset, 3); w["e"] = round(w["e"] - offset, 3)
+        result[key] = {"dur": round(ws[-1]["e"] + 0.15, 3), "offset": round(offset, 3), "text": clean, "words": ws}
+        print(key, result[key]["dur"], "s")
+        json.dump(result, open(out + "words.json", "w"), ensure_ascii=False, indent=1); continue
+    body = {"text": text, "model_id": "eleven_v3", "language_code": lang, "voice_settings": {"stability": film.get("stability", 0.0)}}
+    req = urllib.request.Request(f"https://api.elevenlabs.io/v1/text-to-speech/{voice}/with-timestamps",
+                                 data=json.dumps(body).encode(), headers=H)
+    try:
+        d = json.load(urllib.request.urlopen(req))
+    except urllib.error.HTTPError as e:
+        sys.exit(f"{key}: ElevenLabs refused ({e.code}): {e.read()[:300].decode(errors='ignore')} — lines before {key} are saved.")
+    raw = out + key + ".raw.mp3"
+    open(raw, "wb").write(base64.b64decode(d["audio_base64"]))
+    # loudness only — never trim, so the timings stay valid
+    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", raw, "-af", "loudnorm=I=-16:TP=-1.5", "-ar", "44100", out + key + ".mp3"], check=True)
+    os.remove(raw)
+    ws = words_from(d["alignment"])
+    offset = max(0.0, ws[0]["s"] - 0.05)
+    for w in ws:
+        w["s"] = round(w["s"] - offset, 3); w["e"] = round(w["e"] - offset, 3)
+    clean = re.sub(r"\[[^\]]*\]\s*", "", text)
+    result[key] = {"dur": round(ws[-1]["e"] + 0.15, 3), "offset": round(offset, 3), "text": clean, "words": ws}
+    print(key, result[key]["dur"], "s")
+    json.dump(result, open(out + "words.json", "w"), ensure_ascii=False, indent=1)  # after every line: a failure never leaves audio and timings out of step