@olegkoval/agent-skills 1.59.3 → 1.61.0

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/edge/media.ts

@@ -0,0 +1,105 @@
+// ffmpeg and files: every process and disk write the pipeline makes, kept out of the domain.
+import { spawn, spawnSync, type SpawnSyncOptions } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { Json, Timeline } from "../domain/types.ts";
+
+export const SR = 48000;
+
+export function run(cmd: string, args: readonly string[], opts: SpawnSyncOptions = {}): string {
+  const r = spawnSync(cmd, args, { encoding: "utf8", maxBuffer: 1 << 28, ...opts });
+  if (r.status !== 0) {
+    const out = String(r.stderr || r.stdout || r.error?.message || "");
+    throw new Error(`${cmd} ${args.slice(0, 3).join(" ")}... failed:\n${out.slice(-1500)}`);
+  }
+  return String(r.stdout);
+}
+
+export const has = (cmd: string, args: readonly string[] = ["-version"]): boolean => spawnSync(cmd, args, { stdio: "ignore" }).status === 0;
+
+export const readJson = (f: string): unknown => JSON.parse(fs.readFileSync(f, "utf8"));
+export const writeJson = (f: string, v: Json | object): void => fs.writeFileSync(f, JSON.stringify(v, null, 2) + "\n");
+export const mkdir = (...parts: string[]): string => {
+  const d = path.join(...parts);
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+};
+
+export const duration = (f: string): number =>
+  parseFloat(run("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=nk=1:nw=1", f]));
+
+/** Mono 48 kHz float samples of a file, or of a slice of it. */
+export function pcm(file: string, from = 0, dur?: number): Float32Array {
+  const args = ["-v", "error", ...(from ? ["-ss", String(from)] : []), ...(dur ? ["-t", String(dur)] : []), "-i", file, "-ac", "1", "-ar", String(SR), "-f", "f32le", "-"];
+  const b = spawnSync("ffmpeg", args, { maxBuffer: 1 << 30 }).stdout;
+  return new Float32Array(b.buffer, b.byteOffset, b.length / 4);
+}
+
+export function wav(file: string, data: Float32Array): void {
+  const n = data.length;
+  const buf = Buffer.alloc(44 + n * 2);
+  buf.write("RIFF", 0); buf.writeUInt32LE(36 + n * 2, 4); buf.write("WAVE", 8); buf.write("fmt ", 12);
+  buf.writeUInt32LE(16, 16); buf.writeUInt16LE(1, 20); buf.writeUInt16LE(1, 22); buf.writeUInt32LE(SR, 24);
+  buf.writeUInt32LE(SR * 2, 28); buf.writeUInt16LE(2, 32); buf.writeUInt16LE(16, 34); buf.write("data", 36); buf.writeUInt32LE(n * 2, 40);
+  data.forEach((x, i) => buf.writeInt16LE(Math.max(-32767, Math.min(32767, Math.round(x * 32767))), 44 + i * 2));
+  fs.writeFileSync(file, buf);
+}
+
+export type Mix = { readonly voice: string; readonly music: string | null; readonly hasVoice: boolean; readonly volume: number; readonly duration: number };
+
+/** Voice ducks the music (sidechain), then loudness to the -14 LUFS the platforms normalise to. */
+const MIX_ARGS: Record<"both" | "music" | "voice", (m: Mix) => readonly string[]> = {
+  both: (m) => ["-i", m.voice, "-i", m.music ?? "", "-filter_complex",
+    `[1:a]volume=${m.volume}[m];[0:a]asplit=2[v][sc];[m][sc]sidechaincompress=threshold=0.04:ratio=3:attack=30:release=500[md];[v][md]amix=inputs=2:duration=longest:normalize=0,loudnorm=I=-14:TP=-1.5:LRA=11[o]`,
+    "-map", "[o]", "-ar", String(SR)],
+  music: (m) => ["-i", m.music ?? "", "-af", `volume=${m.volume},loudnorm=I=-15:TP=-1.5`],
+  voice: (m) => ["-i", m.voice, "-af", "loudnorm=I=-14:TP=-1.5"],
+};
+
+export function mix(m: Mix, out: string): string {
+  const kind = m.music && m.hasVoice ? "both" : m.music ? "music" : "voice";
+  run("ffmpeg", ["-v", "error", "-y", ...MIX_ARGS[kind](m), "-t", String(m.duration), out]);
+  return out;
+}
+
+const sheetWidth = (tl: Timeline): number => (tl.W > tl.H ? 480 : 300);
+const tile = (tl: Timeline): string => {
+  const cols = Math.min(6, tl.beats.length);
+  return `scale=${sheetWidth(tl)}:-2,tile=${cols}x${Math.ceil(tl.beats.length / cols)}:padding=6:color=white`;
+};
+
+/** One contact sheet from numbered stills (frames/s000.jpg...). */
+export const stillSheet = (tl: Timeline, pattern: string, out: string): void =>
+  void run("ffmpeg", ["-v", "error", "-y", "-framerate", "1", "-i", pattern, "-vf", tile(tl), "-frames:v", "1", out]);
+
+/** One frame per shot, taken from the finished file at 60% of the shot: what a viewer actually sees. */
+export function videoSheet(tl: Timeline, video: string, out: string): void {
+  const sel = tl.beats.map((b) => `between(t\\,${(b.start + b.dur * 0.6).toFixed(2)}\\,${(b.start + b.dur * 0.6 + 0.04).toFixed(2)})`).join("+");
+  run("ffmpeg", ["-v", "error", "-y", "-i", video, "-vf", `select='${sel}',${tile(tl)}`, "-frames:v", "1", "-fps_mode", "vfr", out]);
+}
+
+export type Encoder = { readonly write: (jpeg: Buffer) => Promise<void>; readonly done: () => Promise<number> };
+
+/** Drawings in at fps/twos, out at fps: each drawing holds for `twos` frames, like hand animation. */
+// Every drawing is re-stroked, so nothing carries over between them and quality alone sets the size:
+// crf 17 made ~50 Mbit/s, crf 23 halves it with no visible change. The JPEGs arrive full-range;
+// converting to tv range stops players and platforms from showing them with the wrong contrast.
+export function encoder(tl: Timeline, audio: string, out: string): Encoder {
+  const ff = spawn("ffmpeg", ["-v", "error", "-y", "-f", "image2pipe", "-c:v", "mjpeg", "-framerate", String(tl.fps / tl.twos), "-i", "-", "-i", audio,
+    "-map", "0:v", "-map", "1:a", "-r", String(tl.fps), "-vf", "scale=out_range=tv", "-c:v", "libx264", "-preset", "medium", "-crf", "23",
+    "-pix_fmt", "yuv420p", "-color_range", "tv", "-movflags", "+faststart",
+    "-c:a", "aac", "-b:a", "192k", "-shortest", out], { stdio: ["pipe", "inherit", "inherit"] });
+  const closed = new Promise<number>((r) => ff.on("close", (code) => r(code ?? 1)));
+  return {
+    write: (buf) => new Promise((r) => (ff.stdin.write(buf) ? r() : ff.stdin.once("drain", () => r()))),
+    done: () => {
+      ff.stdin.end();
+      return closed;
+    },
+  };
+}
+
+export const jpeg = (dataUrl: unknown): Buffer => {
+  if (typeof dataUrl !== "string" || !dataUrl.startsWith("data:")) throw new Error("the page returned no image");
+  return Buffer.from(dataUrl.slice(dataUrl.indexOf(",") + 1), "base64");
+};

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/edge/page.ts

@@ -0,0 +1,53 @@
+// The page a short is painted on: the runtime (type-stripped to classic scripts), the scenes, the assets.
+// Everything is written under <project>/build so the skill folder itself stays read-only.
+import fs from "node:fs";
+import { stripTypeScriptTypes } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { JsonMap } from "../domain/types.ts";
+import { openPage, type Page } from "./chrome.ts";
+import { mkdir } from "./media.ts";
+
+const RUNTIME = path.join(import.meta.dirname, "..", "runtime");
+const SCRIPTS = ["kit", "paint", "stage"];
+const IMAGE = /\.(png|jpe?g|webp|svg)$/i;
+const GPU = "(()=>{const c=document.createElement('canvas').getContext('webgl2');const d=c&&c.getExtension('WEBGL_debug_renderer_info');return c?c.getParameter(d?d.UNMASKED_RENDERER_WEBGL:c.RENDERER):'none'})()";
+
+/** The browser loads these as classic scripts, so nothing may import or export. */
+export function classicScript(file: string): string {
+  const js = stripTypeScriptTypes(fs.readFileSync(file, "utf8"), { mode: "strip" });
+  if (/^\s*(import|export)\s/m.test(js)) throw new Error(`${file}: import/export survives stripping`);
+  return js;
+}
+
+const html = (state: JsonMap, imgs: readonly string[]): string => `<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;background:#000}</style></head><body>
+<canvas id="out"></canvas>
+<script>window.SHORT=${JSON.stringify(state)};window.IMAGES={};</script>
+<script src="kit.js"></script><script src="paint.js"></script><script src="scenes.js"></script>
+<script>
+Promise.all(${JSON.stringify(imgs)}.map(f=>new Promise(r=>{const i=new Image();i.onload=()=>{IMAGES[f.replace(/\\.[^.]+$/,"")]=i;r()};i.onerror=r;i.src="assets/"+f}))).then(()=>{const s=document.createElement("script");s.src="stage.js";document.body.appendChild(s)});
+</script></body></html>`;
+
+/** Writes build/index.html and what it loads. `state` becomes window.SHORT. */
+export function buildPage(dir: string, state: JsonMap): string {
+  const scenes = path.join(dir, "scenes.js");
+  if (!fs.existsSync(scenes)) throw new Error("no scenes.js");
+  const b = mkdir(dir, "build");
+  SCRIPTS.forEach((n) => fs.writeFileSync(path.join(b, `${n}.js`), classicScript(path.join(RUNTIME, `${n}.ts`))));
+  fs.copyFileSync(scenes, path.join(b, "scenes.js"));
+  const assets = path.join(dir, "assets");
+  const imgs = fs.existsSync(assets) ? fs.readdirSync(assets).filter((f) => IMAGE.test(f)) : [];
+  if (imgs.length) imgs.forEach((f) => fs.copyFileSync(path.join(assets, f), path.join(mkdir(b, "assets"), f)));
+  const index = path.join(b, "index.html");
+  fs.writeFileSync(index, html(state, imgs));
+  return index;
+}
+
+export async function paintPage(dir: string, state: JsonMap, width: number, height: number): Promise<Page> {
+  const pg = await openPage(pathToFileURL(buildPage(dir, state)).href, width, height);
+  const gl = await pg.evaluate(GPU);
+  if (/swiftshader|llvmpipe/i.test(String(gl))) console.log("· no GPU in this browser, painting on the CPU (slower, same picture)");
+  return pg;
+}
+
+export const pageErrors = (pg: Page): readonly string[] => pg.logs().filter((l) => /error/i.test(l)).slice(0, 8);

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/edge/probe.ts

@@ -0,0 +1,75 @@
+// `SA check` facts: run every scene once against a recording kit, without a browser.
+// The kit records each call it sees, so the domain rules can judge calls, not pixels.
+import fs from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+import type { Call, Probe } from "../domain/check.ts";
+import { isMap } from "../domain/schema.ts";
+import type { JsonMap, Timeline } from "../domain/types.ts";
+
+const KIT_SRC = path.join(import.meta.dirname, "..", "runtime", "kit.ts");
+const IMAGE = /\.(png|jpe?g|webp|svg)$/i;
+const VALUES = ["g", "W", "H", "u", "t", "p", "r", "pal", "beat", "mix", "alpha", "rng", "noise1", "X", "Y"];
+
+/** Every name a scene may call or read on k, read from the kit itself so the two cannot drift. */
+export const kitNames = (): readonly string[] => [
+  ...VALUES,
+  ...[...fs.readFileSync(KIT_SRC, "utf8").matchAll(/(\w+): \((?:o|list)\) =>/g)].flatMap((m) => (m[1] ? [m[1]] : [])),
+];
+
+const plain = (o: unknown): JsonMap => {
+  try {
+    const v: unknown = JSON.parse(JSON.stringify(o ?? {}));
+    return isMap(v) ? v : {};
+  } catch {
+    return {};
+  }
+};
+
+/** A canvas context that accepts anything and draws nothing. */
+const sink = (): unknown => {
+  const handler: ProxyHandler<() => void> = {
+    get: (_t, key) => (key === Symbol.toPrimitive ? () => 0 : proxy),
+    set: () => true,
+    apply: () => proxy,
+  };
+  const proxy: unknown = new Proxy(() => undefined, handler);
+  return proxy;
+};
+
+function recordingKit(tl: Timeline, calls: Call[]): object {
+  const { W, H } = tl;
+  const values: Readonly<Record<string, unknown>> = {
+    g: sink(), W, H, u: H / 1920, t: 0.6, p: 0.6, X: (x: number) => x * W, Y: (y: number) => y * H,
+    r: () => 0.5, rng: () => () => 0.5, noise1: () => 0.5, mix: () => "#808080", alpha: () => "#808080", pal: {}, beat: tl.beats[0] ?? {},
+  };
+  const record = (fn: string) => (o: unknown) => {
+    if (fn === "people" && Array.isArray(o)) o.forEach((x) => calls.push({ fn: "person", opts: plain(x) }));
+    else calls.push({ fn, opts: plain(o) });
+  };
+  return new Proxy({}, { get: (_t, key) => (typeof key !== "string" ? undefined : key in values ? values[key] : record(key)) });
+}
+
+const message = (e: unknown): string =>
+  typeof e === "object" && e !== null && "message" in e ? String(e.message) : String(e);
+
+/** One probe per scene in scenes.js; a scene that throws (or runs past a second) reports that instead. */
+export function probeScenes(dir: string, tl: Timeline): readonly Probe[] {
+  const assets = path.join(dir, "assets");
+  const names = fs.existsSync(assets) ? fs.readdirSync(assets).filter((f) => IMAGE.test(f)) : [];
+  // The page loads assets/ into IMAGES before the scenes run; a stand-in of the same shape keeps them honest here.
+  const IMAGES = Object.fromEntries(names.map((f) => [f.replace(/\.[^.]+$/, ""), { width: 512, height: 512 }]));
+  const ctx = vm.createContext({ window: { IMAGES }, IMAGES });
+  vm.runInContext(fs.readFileSync(path.join(dir, "scenes.js"), "utf8"), ctx, { filename: "scenes.js", timeout: 1000 });
+  const scenes: unknown = vm.runInContext("Object.keys(window.SCENES || {})", ctx);
+  if (!Array.isArray(scenes) || scenes.length === 0) throw new Error("scenes.js sets no window.SCENES");
+  return scenes.map(String).map((scene): Probe => {
+    const calls: Call[] = [];
+    try {
+      vm.runInContext(`window.SCENES[${JSON.stringify(scene)}](globalThis.__kit)`, Object.assign(ctx, { __kit: recordingKit(tl, calls) }), { timeout: 1000 });
+      return { scene, calls };
+    } catch (e) {
+      return { scene, calls, error: message(e) };
+    }
+  });
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/edge/sound.ts

@@ -0,0 +1,46 @@
+// The soundtrack: every take at its moment on one voice track, the score, and the ducked mix.
+import path from "node:path";
+import { PRESETS, renderSoundtrack } from "../audio/soundtrack.ts";
+import type { Short, Take, Timeline } from "../domain/types.ts";
+import { mix, mkdir, pcm, SR, wav } from "./media.ts";
+
+export const MOODS = ["tender", "hopeful", "night", "wonder", "playful"];
+const LEAD_IN = 0.05;
+
+type Placed = { readonly at: number; readonly data: Float32Array };
+
+const place = (tl: Timeline) => (t: Take, i: number): readonly Placed[] => {
+  if (!t.file) return [];
+  const at = tl.voiceAt[i] ?? 0;
+  return t.slice
+    ? [{ at: Math.round((at - LEAD_IN) * SR), data: pcm(t.file, Math.max(0, (t.from ?? 0) - LEAD_IN), t.dur + 0.15) }]
+    : [{ at: Math.round(at * SR), data: pcm(t.file) }];
+};
+
+/** Sums the takes into one buffer; a take that runs past the end is cut there. */
+function voiceTrack(tl: Timeline, takes: readonly Placed[]): Float32Array {
+  const track = new Float32Array(Math.ceil((tl.duration + 0.5) * SR));
+  takes.forEach(({ at, data }) => data.subarray(0, Math.max(0, track.length - at)).forEach((x, j) => { track[at + j] = (track[at + j] ?? 0) + x; }));
+  return track;
+}
+
+/** Returns the mixed WAV the encoder muxes in. */
+export function soundtrack(dir: string, s: Short, tl: Timeline, takes: readonly Take[]): string {
+  const a = mkdir(dir, "build", "audio");
+  const placed = takes.flatMap(place(tl));
+  const voice = path.join(a, "voice.wav");
+  wav(voice, voiceTrack(tl, placed));
+  const m = s.music;
+  const own = !MOODS.includes(m.mood) && !(m.mood in PRESETS);
+  const music = m.mood === "none" ? null : path.join(a, "music.wav");
+  if (music) {
+    renderSoundtrack(
+      { duration: tl.duration, preset: own ? "tender" : m.mood, music: own ? path.resolve(dir, m.mood) : "auto", cues: [], outroAt: tl.duration - 1.5, musicStart: m.start },
+      music,
+      { seed: m.seed ?? 11 },
+    );
+  }
+  const hasVoice = placed.length > 0;
+  const volume = m.volume ?? (hasVoice ? 0.42 : 0.9);
+  return mix({ voice, music, hasVoice, volume, duration: tl.duration }, path.join(a, "mix.wav"));
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/edge/voice.ts

@@ -0,0 +1,183 @@
+// The narrator: Kokoro-82M in a private Python, or the person's own recording, timed by transcript.
+// Everything is pinned and the model files are checked by sha256, so a setup is the same setup.
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { words } from "../domain/captions.ts";
+import { isMap } from "../domain/schema.ts";
+import type { Json, Short, Take } from "../domain/types.ts";
+import { duration, mkdir, run } from "./media.ts";
+
+const HOME = path.join(os.homedir(), ".cache", "shorts-animator");
+const VENV = path.join(HOME, "venv");
+const PY = path.join(VENV, process.platform === "win32" ? "Scripts/python.exe" : "bin/python");
+const TTS = path.join(import.meta.dirname, "..", "tts.py");
+const PACKAGES = ["kokoro-onnx==0.6.1", "soundfile==0.14.0"];
+export const HYPERFRAMES = "hyperframes@0.8.150";
+const NPX = process.platform === "win32" ? "npx.cmd" : "npx";
+const RELEASE = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0";
+const MODEL = {
+  "kokoro-v1.0.onnx": "7d5df8ecf7d4b1878015a32686053fd0eebe2bc377234608764cc0ef3636a6c5",
+  "voices-v1.0.bin": "bca610b8308e8d99f32e6fe4197e7ec01679264efed0cac9140fe9c29f1fbf7d",
+};
+type ModelFile = keyof typeof MODEL;
+
+export const hash = (...xs: readonly Json[]): string =>
+  crypto.createHash("sha1").update(xs.map((x) => JSON.stringify(x)).join("|")).digest("hex").slice(0, 10);
+
+const sha256 = (f: string): string => crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+
+/** HyperFrames' cache first (it ships the same files), then ours. */
+const modelFiles = (): readonly [string, string] | undefined => {
+  const hf = path.join(os.homedir(), ".cache", "hyperframes", "tts");
+  const pairs: readonly (readonly [string, string])[] = [
+    [path.join(hf, "models", "kokoro-v1.0.onnx"), path.join(hf, "voices", "voices-v1.0.bin")],
+    [path.join(HOME, "kokoro", "kokoro-v1.0.onnx"), path.join(HOME, "kokoro", "voices-v1.0.bin")],
+  ];
+  return pairs.find(([m, v]) => fs.existsSync(m) && fs.existsSync(v));
+};
+
+const pythonReady = (): boolean => fs.existsSync(PY) && spawnSync(PY, ["-I", "-c", "import kokoro_onnx, soundfile"]).status === 0;
+export const narratorReady = (): boolean => pythonReady() && modelFiles() !== undefined;
+
+const PYTHONS = ["python3.13", "python3.12", "python3.11", "python3.10", "python3", "python", "py"];
+const modernPython = (): string | undefined =>
+  PYTHONS.find((b) => spawnSync(b, ["-c", "import sys; print(sys.version_info >= (3, 10) and sys.version_info < (3, 14))"], { encoding: "utf8" }).stdout?.trim() === "True");
+
+function installPython(log: (m: string) => void): string | undefined {
+  mkdir(HOME);
+  if (spawnSync("uv", ["--version"]).status === 0) {
+    log("· setting up the narrator's Python (uv)...");
+    spawnSync("uv", ["venv", "-q", "--allow-existing", "-p", "3.12", VENV], { stdio: "inherit" });
+    spawnSync("uv", ["pip", "install", "-q", "-p", PY, ...PACKAGES], { stdio: "inherit" });
+  } else {
+    const py = modernPython();
+    if (!py) return 'the narrator needs Python 3.10 to 3.13, or uv (https://docs.astral.sh/uv/). Or set voice to "none", or use your own recording';
+    log(`· setting up the narrator's Python (${py})...`);
+    spawnSync(py, ["-m", "venv", VENV], { stdio: "inherit" });
+    spawnSync(PY, ["-m", "pip", "install", "-q", ...PACKAGES], { stdio: "inherit" });
+  }
+  return pythonReady() ? undefined : `couldn't install ${PACKAGES.join(" ")} into ${VENV}`;
+}
+
+async function download(dir: string, f: ModelFile, log: (m: string) => void): Promise<string | undefined> {
+  log(`· downloading the voice model: ${f}...`);
+  const res = await fetch(`${RELEASE}/${f}`);
+  if (!res.ok) return `couldn't download ${f} (${res.status})`;
+  const part = path.join(dir, f + ".part");
+  fs.writeFileSync(part, Buffer.from(await res.arrayBuffer()));
+  if (sha256(part) !== MODEL[f]) {
+    fs.rmSync(part);
+    return `${f} failed its checksum; nothing was installed`;
+  }
+  fs.renameSync(part, path.join(dir, f));
+  return undefined;
+}
+
+/** Sets the narrator up. Returns undefined when ready, or what is missing. */
+export async function setupNarrator(log: (m: string) => void = console.log): Promise<string | undefined> {
+  const py = pythonReady() ? undefined : installPython(log);
+  if (py || modelFiles()) return py;
+  const dir = mkdir(HOME, "kokoro");
+  const files: readonly ModelFile[] = ["voices-v1.0.bin", "kokoro-v1.0.onnx"];
+  return files.reduce<Promise<string | undefined>>(async (prev, f) => (await prev) ?? download(dir, f, log), Promise.resolve(undefined));
+}
+
+/* ------------------------------------------------------------------ takes */
+
+const silent = (s: Short): readonly Take[] => s.lines.map((l) => ({ file: null, dur: Math.max(1.3, words(l.say).length * 0.36) }));
+
+type Job = { readonly text: string; readonly file: string };
+
+const kokoroJobs = (s: Short, vdir: string, id: string, speed: number): readonly (Job & { readonly fresh: boolean })[] =>
+  s.lines.map((l, i) => {
+    const text = (l.speak ?? l.say).replace(/\*|\|/g, "");
+    const n = String(i + 1).padStart(2, "0");
+    const file = path.join(vdir, `${n}-${hash(text, id, speed)}.wav`);
+    return { text, file, fresh: fs.existsSync(file) };
+  });
+
+/** A line's text changed: its old take goes, so the folder never holds two takes of one line. */
+const dropStale = (vdir: string, file: string): void => {
+  const prefix = path.basename(file).slice(0, 3);
+  fs.readdirSync(vdir).filter((f) => f.startsWith(prefix) && f !== path.basename(file)).forEach((f) => fs.rmSync(path.join(vdir, f)));
+};
+
+async function kokoro(s: Short, vdir: string, id: string, speed: number, quiet: boolean): Promise<readonly Take[]> {
+  const jobs = kokoroJobs(s, vdir, id, speed);
+  const todo = jobs.filter((j) => !j.fresh);
+  if (todo.length) {
+    const why = narratorReady() ? undefined : await setupNarrator();
+    const files = modelFiles();
+    if (why || !files) throw new Error(why ?? "no voice model");
+    todo.forEach((j) => dropStale(vdir, j.file));
+    if (!quiet) console.log(`· narrating ${todo.length} line${todo.length > 1 ? "s" : ""} with ${id} (Kokoro, on this computer)...`);
+    run(PY, ["-I", TTS, ...files, id, String(speed)], { input: JSON.stringify(todo.map((j) => [j.text, j.file])) });
+  }
+  return jobs.map((j) => ({ file: j.file, dur: duration(j.file) }));
+}
+
+type Word = { readonly start: number; readonly end: number };
+
+/** Every {word|text, start, end} in a transcript, wherever the tool nested it. */
+const pickWords = (o: Json | undefined): readonly Word[] => {
+  if (Array.isArray(o)) return o.flatMap(pickWords);
+  if (!isMap(o)) return [];
+  const { start, end } = o;
+  if ((o.word || o.text) && typeof start === "number" && typeof end === "number" && !o.words) return [{ start, end }];
+  return Object.values(o).flatMap(pickWords);
+};
+
+const parseTranscript = (raw: string): Json | undefined => {
+  try {
+    const v: unknown = JSON.parse(raw.slice(raw.indexOf("{")));
+    return isMap(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+function transcriptWords(src: string, vdir: string, quiet: boolean): readonly Word[] {
+  const tj = path.join(vdir, `transcript-${hash(fs.statSync(src).mtimeMs, src)}.json`);
+  if (!fs.existsSync(tj)) {
+    if (!quiet) console.log("· transcribing your recording for the timing...");
+    fs.writeFileSync(tj, run(NPX, ["--yes", HYPERFRAMES, "transcribe", src, "--json", "-d", vdir], { cwd: vdir }));
+  }
+  const direct = pickWords(parseTranscript(fs.readFileSync(tj, "utf8")));
+  const side = fs.readdirSync(vdir).find((f) => f.endsWith("transcript.json") && !f.startsWith("transcript-"));
+  const ws = direct.length || !side ? direct : pickWords(parseTranscript(fs.readFileSync(path.join(vdir, side), "utf8")));
+  return ws.toSorted((a, b) => a.start - b.start);
+}
+
+/** Their own recording: each line takes the next run of words, in order. */
+function ownRecording(s: Short, dir: string, vdir: string, file: string, quiet: boolean): readonly Take[] {
+  const src = path.resolve(dir, file);
+  if (!fs.existsSync(src)) throw new Error(`voice.file ${file} not found`);
+  const ws = transcriptWords(src, vdir, quiet);
+  if (!ws.length) throw new Error("couldn't read word timings from the transcript");
+  const word = (i: number): Word => ws[Math.min(i, ws.length - 1)] ?? { start: 0, end: 0 };
+  const firsts = s.lines.map((_, i) => s.lines.slice(0, i).reduce((n, l) => n + words(l.say).length, 0));
+  return s.lines.map((l, i) => {
+    const a = word(firsts[i] ?? 0);
+    const b = word((firsts[i] ?? 0) + words(l.say).length - 1);
+    return { file: src, from: a.start, dur: Math.max(0.6, b.end - a.start), slice: true };
+  });
+}
+
+export async function narrate(dir: string, s: Short, quiet = false): Promise<readonly Take[]> {
+  const vdir = mkdir(dir, "voice");
+  const v = s.voice;
+  if (v.kind === "none") return silent(s);
+  if (v.kind === "file") return ownRecording(s, dir, vdir, v.file, quiet);
+  return kokoro(s, vdir, v.id, v.speed, quiet);
+}
+
+/** Timing without narrating: cached Kokoro takes when every line has one, word-count estimates otherwise. */
+export function cachedTakes(dir: string, s: Short): readonly Take[] {
+  const v = s.voice;
+  if (v.kind !== "kokoro") return silent(s);
+  const jobs = kokoroJobs(s, path.join(dir, "voice"), v.id, v.speed);
+  return jobs.every((j) => j.fresh) ? jobs.map((j) => ({ file: j.file, dur: duration(j.file) })) : silent(s);
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/looks/gouache.json

@@ -0,0 +1,7 @@
+{
+  "about": "Gouache storybook: flat matte shapes, crisp edges, a little brush texture and paper. Calm and graphic.",
+  "mode": "strokes", "brush": 6, "length": 2.2, "layers": 2, "swirl": 0.2, "flow": 300, "curve": 0.3,
+  "bristle": 0.35, "impasto": 0.1, "hueJitter": 0.05, "valueJitter": 0.07, "satJitter": 0.1, "respect": 1,
+  "boil": 0.3, "paper": 0.8, "grain": 0.35, "saturation": 1.02, "contrast": 1.02, "warmth": 0.1, "vignette": 0.15, "bloom": 0.05,
+  "captions": { "style": "box", "size": 44 }
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/looks/ink.json

@@ -0,0 +1,6 @@
+{
+  "about": "Ink and wash, like a graphic novel: wobbly hand-inked outlines that boil, flat washes of colour, paper.",
+  "mode": "wash", "wash": 0.5, "bleed": 0.3, "outline": 0.95, "ink": "#1b1712", "paper": 0.7, "paperColor": "#f4efe3",
+  "grain": 0.3, "boil": 1, "posterize": 0, "saturation": 0.85, "contrast": 1.05, "warmth": 0.1, "vignette": 0.1, "bloom": 0,
+  "captions": { "style": "box", "size": 44, "box": "rgba(27,23,18,0.8)" }
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/looks/oil.json

@@ -0,0 +1,7 @@
+{
+  "about": "Oil paint on canvas: swirling strokes, deep saturated colour, a slow shimmer. The painted-shorts look.",
+  "mode": "strokes", "brush": 11, "length": 2.8, "layers": 3, "swirl": 0.7, "flow": 160, "curve": 0.9,
+  "bristle": 0.75, "impasto": 0.6, "hueJitter": 0.2, "valueJitter": 0.22, "satJitter": 0.35, "respect": 0.85,
+  "boil": 0.5, "paper": 0.6, "grain": 0.5, "saturation": 1.18, "contrast": 1.06, "warmth": 0.2, "vignette": 0.35, "bloom": 0.3,
+  "captions": { "style": "box", "size": 44, "y": 0.775 }
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/looks/pastel.json

@@ -0,0 +1,7 @@
+{
+  "about": "Soft pastel / crayon on toned paper: straight chalky hatching, paper tooth everywhere, pale gentle colour.",
+  "mode": "strokes", "brush": 6, "length": 4.6, "layers": 3, "swirl": 0.05, "flow": 600, "curve": 0,
+  "bristle": 1, "impasto": 0, "hueJitter": 0.1, "valueJitter": 0.3, "satJitter": 0.2, "respect": 0.5,
+  "boil": 0.8, "paper": 1.6, "grain": 0.8, "saturation": 0.82, "contrast": 0.9, "warmth": 0.35, "vignette": 0.2, "bloom": 0.1,
+  "captions": { "style": "box", "size": 44 }
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/looks/watercolor.json

@@ -0,0 +1,6 @@
+{
+  "about": "Watercolour on cold-press paper: soft bleeding washes, pigment pooled at the edges, granulation, light and airy.",
+  "mode": "wash", "wash": 0.9, "bleed": 0.8, "paper": 0.9, "paperColor": "#f6f1e6", "grain": 0.25, "boil": 0.4,
+  "outline": 0, "saturation": 0.92, "contrast": 0.96, "warmth": 0.1, "vignette": 0.12, "bloom": 0.1,
+  "captions": { "style": "box", "size": 44, "box": "rgba(34,38,58,0.58)" }
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}