kaizen-agent 1.19.4 → 1.21.0

package/skills/story-deck/scripts/prep_images.py

@@ -0,0 +1,70 @@
+"""Crop photos to the slide and bake in the dark cinematic grade.
+
+Usage: python3 prep_images.py plan.json   (run from the deck folder; reads img/, writes bg/)
+
+plan.json:
+  {"backgrounds": {"s01": ["<photo id>", focusY, base, "left|right|bottom", strength]},
+   "panels":      {"p1":  ["<photo id>", focusY, [w_px, h_px]]}}
+  photo id = file name in img/ without .jpg. focusY 0..1 = vertical crop focus.
+  base = overall darkening 0..1. strength = gradient darkness on the text side 0..1.
+  Panel size must have the SAME ratio as its box on the slide (w_in/h_in); pptxgenjs
+  "sizing" is ignored by Google Slides and stretches the photo.
+
+pptxgenjs has no gradient fills, so the text-side shadow lives in the image.
+"""
+import json
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageEnhance
+
+W, H = 1800, 1273  # A5 landscape (210:148)
+INK = (20, 17, 15)
+
+
+def crop(im, w, h, focus_y):
+    r = w / h
+    if im.width / im.height > r:  # too wide: crop sides
+        nw = int(im.height * r)
+        x = (im.width - nw) // 2
+        im = im.crop((x, 0, x + nw, im.height))
+    else:  # too tall: crop around focus
+        nh = int(im.width / r)
+        y = int((im.height - nh) * focus_y)
+        im = im.crop((0, y, im.width, y + nh))
+    out = im.resize((w, h), Image.LANCZOS)
+    assert abs(out.width / out.height - r) < 0.01
+    return out
+
+
+def grade(im):
+    im = ImageEnhance.Color(im).enhance(0.75)  # mute colours, film look
+    return Image.blend(im, Image.new("RGB", im.size, (60, 40, 20)), 0.08)
+
+
+def overlay(im, base, side, strength):
+    ink = Image.new("RGB", im.size, INK)
+    im = Image.blend(im, ink, base)
+    g = Image.linear_gradient("L")  # black top -> white bottom
+    if side == "left":
+        g = g.rotate(-90)
+    elif side == "right":
+        g = g.rotate(90)
+    g = g.resize(im.size).point(lambda v: int(v * strength))
+    return Image.composite(ink, im, g)
+
+
+def main(plan_path):
+    plan = json.loads(Path(plan_path).read_text())
+    Path("bg").mkdir(exist_ok=True)
+    for sid, (pid, fy, base, side, s) in plan.get("backgrounds", {}).items():
+        im = Image.open(f"img/{pid}.jpg").convert("RGB")
+        overlay(grade(crop(im, W, H, fy)), base, side, s).save(f"bg/{sid}.jpg", quality=85)
+    for sid, (pid, fy, (pw, ph)) in plan.get("panels", {}).items():
+        im = grade(crop(Image.open(f"img/{pid}.jpg").convert("RGB"), pw, ph, fy))
+        Image.blend(im, Image.new("RGB", im.size, INK), 0.35).save(f"bg/{sid}.jpg", quality=85)
+    print("ok")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1] if len(sys.argv) > 1 else "plan.json")

package/skills/story-deck/scripts/qa.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Build a deck, check the file, render every slide, and write 2x4 contact sheets to qa/.
+# Usage (from the deck folder): qa.sh build-x.js      -> prints the qa/sheet*.jpg paths to look at
+# Uses the Anthropic pptx skill's validator when installed; otherwise a built-in structural check.
+set -euo pipefail
+BUILD=${1:?usage: qa.sh build-script.js}
+"$(dirname "$0")/check.sh" >/dev/null 2>&1 || { "$(dirname "$0")/check.sh" 2>/dev/null || true; }
+V=$HOME/.kaizen/decks/.venv
+[ -x "$V/bin/python" ] || { python3 -m venv "$V" && "$V/bin/pip" -q install defusedxml lxml pillow fonttools "qrcode[pil]"; }
+PY=$V/bin/python
+F=$(node "$BUILD")
+PPTX_SKILL=$(ls -d ~/.claude/skills/*/pptx/scripts ~/.claude/skills/synced/*/pptx/scripts 2>/dev/null | head -1 || true)
+if [ -n "$PPTX_SKILL" ] && [ -f "$PPTX_SKILL/office/validate.py" ]; then
+  $PY "$PPTX_SKILL/office/validate.py" "$F"
+  $PY "$PPTX_SKILL/office/soffice.py" --headless --convert-to pdf "$F" >/dev/null
+else
+  # structural check: valid zip, every XML part parses, every slide relationship target exists
+  $PY - "$F" <<'PYEOF'
+import sys, zipfile, posixpath
+from lxml import etree
+z = zipfile.ZipFile(sys.argv[1]); bad = z.testzip()
+assert bad is None, f"corrupt part: {bad}"
+names = {n for n in z.namelist() if not n.endswith("/")}  # skip directory entries
+for n in names:
+    if n.endswith(".xml") or n.endswith(".rels"):
+        etree.fromstring(z.read(n))
+for n in names:
+    if n.startswith("ppt/slides/_rels/"):
+        for r in etree.fromstring(z.read(n)):
+            t = r.get("Target")
+            if r.get("TargetMode") == "External" or not t: continue
+            p = posixpath.normpath(posixpath.join("ppt/slides", t))
+            assert p in names, f"{n}: missing {p}"
+print("structure OK:", sum(1 for n in names if n.startswith("ppt/slides/slide")), "slides")
+PYEOF
+  soffice --headless --convert-to pdf --outdir "$(dirname "$F")" "$F" >/dev/null 2>&1
+fi
+rm -rf qa && mkdir qa
+pdftoppm -jpeg -r 70 "${F%.pptx}.pdf" qa/s
+rm -f "${F%.pptx}.pdf"
+$PY - <<'PYEOF'
+from PIL import Image; import glob, os
+ims=[Image.open(f) for f in sorted(glob.glob('qa/s-*.jpg'))]; w,h=ims[0].size
+for p in range(0,len(ims),8):
+    g=ims[p:p+8]; sh=Image.new('RGB',(w*2,h*4),'white')
+    for i,im in enumerate(g): sh.paste(im,((i%2)*w,(i//2)*h))
+    sh.save(f'qa/sheet{p//8}.jpg'); print(f'{os.getcwd()}/qa/sheet{p//8}.jpg')
+PYEOF

package/skills/story-video/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: story-video
+description: Turn whatever a user brings for any product — a prompt, a story, product photos, app screenshots, a deck (.pptx/.pdf), footage — into a publish-ready video (MP4 + SRT + thumbnail + credits) in a chosen style (cinematic-drama, promo-booth, fun-energetic, viral-social 9:16) with the product's own brand, narration in the user's language with emotional direction, word-synced captions, sound design, music, logo reveal and loudness mastering; then revise it on request. Use for promo / launch / opener / social / viral / explainer videos or "turn this deck into a video". Not for hand-editing an existing video timeline.
+---
+
+# Story video
+
+Product-agnostic. A film is data: `~/.kaizen/videos/<slug>/film.json` (storyboard + brand) + `lines.json`
+(narration with emotion tags) + `words.json` (word timings, generated) + a preset.
+Worked example: [`examples/sample-film/`](examples/sample-film/) (fictional product, no images needed).
+Run `scripts/check.sh` first on a new machine.
+
+Read before producing:
+- [`references/production.md`](references/production.md) — what makes a video publish-grade; QA list.
+- [`references/presets.md`](references/presets.md) — styles, when to use each, adding one.
+- [`references/script.md`](references/script.md) — **how to write the narration** (a told story, not slide text).
+- [`references/revisions.md`](references/revisions.md) — how user revisions are applied and versioned.
+- [`references/licensing.md`](references/licensing.md) — **before anything is published**.
+
+## 0. Voice — ask first
+Ask: "Do you have an ElevenLabs account? Which plan?" Then:
+- **Paid ElevenLabs** (Starter+): best and commercially licensed. Use a **native speaker of the
+  narration language** from the voice library (e.g. Indonesian: search `shared-voices?language=id`,
+  add it, let the user pick from 3 samples). Non-native voices sound synthetic — this is the
+  biggest single factor in how natural the video sounds.
+- **Free ElevenLabs**: premade voices only (non-native for most languages) and **no commercial use**;
+  fine for drafts and internal review. Offer samples (v3 with `stability: 0` sounds most natural).
+- **No ElevenLabs**: free Microsoft neural voices via edge-tts (`pip install edge-tts`), set
+  `"voiceProvider": "edge"` (automatic when no key). No emotion control; usable for drafts.
+- Or the user records the narration: write the script with timings, cut the film to their audio.
+Set `voiceProvider` / `voice` / `edgeVoice` in film.json accordingly.
+
+## Where things live
+- **Film workspace:** `~/.kaizen/videos/<slug>/` (one home for every video, whatever the product; override `STORY_VIDEO_HOME`) — `inputs/` (the user's material), generated
+  assets (photos, voice `vNN.mp3`, `music.mp3`), `lines.json`, `film.json`, `words.json`,
+  `REVISIONS.md`, `out/` (deliverables) and `out/previous/` (earlier versions). Nothing is written to the user's project folders.
+- **Engine:** `~/.kaizen/story-video/engine/` (Remotion + node_modules + sfx), installed once per machine
+  and shared by every project. `scripts/setup.sh <slug>` (run from the project root) installs or updates
+  it and creates the film workspace (from any directory). Override with `STORY_VIDEO_ENGINE`.
+- Scripts run from the skill: `S=<this skill>/scripts`, every script takes the film dir.
+
+## 1. Intake — whatever the user brings
+`$S/setup.sh <slug>`, put the user's material in `~/.kaizen/videos/<slug>/inputs/` sorted as
+`photos/`, `screens/`, `footage/`, `logo*.png`, a deck (`*.pptx` / `*.pdf`) and/or `brief.md` (their
+prompt or story, verbatim), then `python3 $S/intake.py ~/.kaizen/videos/<slug>`. It crops photos for
+16:9 and 9:16, keeps screenshots untouched (records ratios), transcodes footage, renders deck slides +
+text to `intake/`, and suggests a brand palette from the logo. Read the deck text, the brief and the
+slide images before writing anything.
+
+Missing material is fine: no photos → source candid ones (story-deck rules); no screenshots →
+ask for them (product beats need the real product); no story → propose one.
+
+## 2. Brief — ask with options (one round)
+Purpose and where it plays · style preset · length · formats · language · voice (from step 0;
+ask gender/tone) · music mood · brand (logo, colours, fonts — propose from the
+logo palette) · CTA (URL / QR target / contact / event details — never invent them) · claims the
+user can back up.
+
+## 3. Treatment — approve before generating
+A beat table: time · picture · narration line + emotion tag · on-screen text · SFX/ambience.
+Write the narration as one told story (references/script.md) — the user's text is source, not script.
+Show the full script as continuous prose too, so the user can judge how it flows. Only claims the material supports. The user approves or edits it; that is revision 0.
+
+## 4. Produce (F = ~/.kaizen/videos/<slug>)
+1. `F/film.json`: `preset`, `language` (`id`, `en`, …), `voiceProvider`, `voice`, `stability`,
+   `brand` (`palette`, `fonts`), `labels` (on-screen words in that language: `source`, `next`),
+   `logo` (light, for dark backgrounds), `logoOnLight`, `qr`, `cta`, `beats` — table below.
+   File names in beats are relative to `F`.
+2. `F/lines.json` (approved script) → `python3 $S/vo.py F` (or only some lines: `vo.py F "" v04,v07`).
+3. Music: `$S/music.sh F "Track"`; offer 3–5 previews when the mood is not settled.
+4. QR: `python3 -c "import qrcode; qrcode.make('<url>').save('F/qr.png')"`.
+5. Check frames: `$S/still.sh F 16x9 60 400 900`, contact-sheet, look at it (or send it to the user), fix. Delete the check images after.
+6. Master each format: `$S/master.sh F <16x9|9x16> <name> <-14|-16> <thumb-second>` → `F/out/`.
+
+## 5. Deliver, then revise
+Report files, lengths, loudness, licence status, placeholders, claims to verify, and ask the user
+to listen once (the agent cannot hear). Revisions follow `references/revisions.md`: change only
+the touched beats/lines, re-render, keep earlier versions in `out/previous/`, log in `REVISIONS.md`.
+
+## Beat kinds
+
+| kind | use | key fields |
+|---|---|---|
+| `photo` | story beat on a photo | `img, side, kick, title, sub, ambience, sfx` |
+| `list` | items arrive one by one with the line | `img, kick, title, items[]` |
+| `stat` | numbers count up, source on screen | `stat[{value,suffix,label,source}], title` |
+| `black` | silence / pause | `title, sub, hold` |
+| `triptych` | three viewpoints | `panels[{img,title,sub}]` |
+| `question` | the turn ("what if") | `title` |
+| `reveal` | logo wipe-in + tagline | `sub, line` |
+| `shot` | real product screenshot, framed | `img, shotRatio, kick, title, sub` |
+| `footage` | video clip | `video, kick, title` |
+| `cta` | the ask: QR, contacts, URL | `img, hold` + `film.cta` |
+
+Any beat: `vo`, `sfx[]` (whoosh, hit, riser, tick, pop, chime, ping, pings, bell, keyboard) and
+`ambience` (amb-morning, amb-classroom, amb-office, amb-night). Add sounds with `scripts/sfx.py` (writes to the shared engine).
+Fonts available: Playfair Display, Inter, Fraunces, Montserrat, Poppins, DM Sans, Lora,
+Plus Jakarta Sans, Space Grotesk (add more in `engine/Film.tsx` FONTS).
+
+## Distribution
+Shipped with kaizen (`skills/story-video` in the kaizen repo).
+
+## Agent notes (Claude Code, Codex, Gemini CLI, OpenCode, Cursor…)
+Steps name capabilities, not tools. Where your agent lacks one:
+- **web fetch** (finding stock photos, sources): ask the user for photos/links instead.
+- **viewing images** (checking contact sheets / frames): send the image paths to the user and ask them to look.
+- **sub-agents** (reading several repos at once): read them one after another.
+- **structured questions**: ask in plain text with numbered options.

package/skills/story-video/engine/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "story-video-films",
+  "private": true,
+  "scripts": { "studio": "remotion studio src/index.ts" },
+  "dependencies": {
+    "@remotion/cli": "4.0.529",
+    "@remotion/google-fonts": "4.0.529",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "remotion": "4.0.529"
+  }
+}

package/skills/story-video/engine/src/Root.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Composition, getInputProps } from 'remotion';
+import { FilmView, FPS, timeline, type Film, type Words } from './engine/Film';
+
+// One film per render: scripts/master.sh passes { film, words } as props and the film folder as public dir.
+const SIZE = { '16x9': [1920, 1080], '9x16': [1080, 1920] } as const;
+type Props = { film: Film; words: Words };
+const props = getInputProps() as Partial<Props>;
+
+export const Root: React.FC = () => (
+  <>
+    {(Object.keys(SIZE) as (keyof typeof SIZE)[]).map((fmt) => (
+      <Composition
+        key={fmt} id={`Film-${fmt}`} component={FilmView as unknown as React.FC<Record<string, unknown>>}
+        fps={FPS} width={SIZE[fmt][0]} height={SIZE[fmt][1]} durationInFrames={1}
+        defaultProps={props as Record<string, unknown>}
+        calculateMetadata={({ props: pr }) => {
+          const { film, words } = pr as unknown as Props;
+          return { durationInFrames: film && words ? timeline(film, words).total : 1 };
+        }}
+      />
+    ))}
+  </>
+);