@keepylabs/cutroom 0.5.0 → 0.5.1

package/cutroom.mjs

@@ -21533,7 +21533,7 @@ function toError(value) {
 
 // src/community/local/render.ts
 import { spawnSync as spawnSync3 } from "node:child_process";
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { basename, extname, join as join3, resolve as resolve2 } from "node:path";
 
@@ -21631,7 +21631,7 @@ function technicalChecks(file) {
 
 // src/community/local/tools.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { createWriteStream, existsSync, mkdirSync as mkdirSync2, writeFileSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join as join2, resolve } from "node:path";
 import { Readable } from "node:stream";
@@ -21685,8 +21685,28 @@ function approxWords(text, duration3) {
   const words = (text ?? "").split(/\s+/).filter(Boolean);
   return words.map((w, i) => ({ t: i / Math.max(words.length, 1) * duration3, w }));
 }
+var MIN_BEAT = 4;
+function beatBounds(duration3, cuts, words) {
+  const ends = words.filter((w) => /[.!?]["”']?$/.test(w.w)).map((w) => w.e ?? w.t);
+  const all = [...new Set([...cuts, ...ends].map((x) => Math.round(x * 10) / 10))].filter((x) => x > 0 && x < duration3).sort((a, b) => a - b);
+  const out = [0];
+  for (const x of all) if (x - out[out.length - 1] >= MIN_BEAT && duration3 - x >= MIN_BEAT / 2) out.push(x);
+  return [...out, duration3];
+}
+function localWords(file, dir) {
+  const r = spawnSync2("npx", ["--yes", "hyperframes@0.8.99", "transcribe", file, "--json", "-d", dir], { cwd: dir, encoding: "utf8", maxBuffer: 1 << 28 });
+  try {
+    const meta2 = JSON.parse(r.stdout.trim().split("\n").pop() ?? "{}");
+    if (r.status !== 0 || !meta2.ok) return null;
+    const raw = JSON.parse(readFileSync2(meta2.transcriptPath ?? join2(dir, "transcript.json"), "utf8"));
+    const words = raw.map((w) => ({ t: Math.round(w.start * 100) / 100, e: Math.round(w.end * 100) / 100, w: w.text.trim() })).filter((w) => w.w);
+    return words.length ? words : null;
+  } catch {
+    return null;
+  }
+}
 function beats(m, words, frames) {
-  const bounds = [0, ...m.cuts, m.duration];
+  const bounds = beatBounds(m.duration, m.cuts, words);
   return bounds.slice(1).map((end, i) => {
     const start = bounds[i];
     const inShot = frames.filter((f) => f.t >= start && f.t < end);
@@ -21715,8 +21735,10 @@ async function breakdownReel(input) {
   const m = measure(file);
   const { frames, interval } = sampleFrames(file, join2(dir, "frames"), m.duration, 1, 40);
   const match = await call("match", { frames: frames.map(({ t, jpg_base64 }) => ({ t, jpg_base64 })), interval });
-  const words = approxWords(transcript, m.duration);
+  const timed = localWords(file, dir);
+  const words = timed ?? approxWords(transcript, m.duration);
   const bs = beats(m, words, match.frames);
+  if (!transcript && timed) transcript = timed.map((w) => w.w).join(" ");
   const hook = transcript ? transcript.split(/(?<=[.!?])\s/)[0] : null;
   const s = match.summary;
   const md = [
@@ -21739,10 +21761,10 @@ async function breakdownReel(input) {
     ...Object.entries(s.layout_share).map(([k, v]) => `- ${k}: ${pct(v)}`),
     "Captions:",
     ...Object.entries(s.caption_share).map(([k, v]) => `- ${k}: ${pct(v)}`),
-    "Effects seen:",
-    ...s.effects.length ? s.effects.map((e) => `- ${e.title}: ${e.spans.map((x) => `${fmt(x.start)}-${fmt(x.end)}`).join(", ")}`) : ["- none from the Cutroom library"],
+    'Effects seen ("in your menu" = render_reel can make it):',
+    ...s.effects.length ? s.effects.map((e) => `- ${e.title}${e.in_menu === false ? "" : " (in your menu)"}: ${e.spans.map((x) => `${fmt(x.start)}-${fmt(x.end)}`).join(", ")}`) : ["- none from the Cutroom library"],
     "",
-    `## Beats${transcript ? " (words are approximate: spread evenly over the video)" : ""}`,
+    `## Beats${!timed && transcript ? " (words are approximate: spread evenly over the video)" : ""}`,
     "| # | time | words | layout | effects |",
     "| - | - | - | - | - |",
     ...bs.map((b) => `| ${b.n} | ${fmt(b.start)}-${fmt(b.end)} | ${b.words.replace(/\|/g, "/") || ""} | ${b.layout} | ${b.effects.join(", ")} |`),
@@ -21752,7 +21774,7 @@ async function breakdownReel(input) {
     ""
   ].join("\n");
   writeFileSync(join2(dir, "breakdown.md"), md);
-  const out = { folder: dir, report: join2(dir, "breakdown.md"), hook, measure: m, look: s, beats: bs, transcript, meta: meta2, next: "Get the 'breakdown_writeup' method with get_method and follow it." };
+  const out = { folder: dir, report: join2(dir, "breakdown.md"), hook, measure: m, look: s, beats: bs, words_timing: timed ? "measured" : transcript ? "approximate" : "none", transcript, meta: meta2, next: "Get the 'breakdown_writeup' method with get_method and follow it." };
   writeFileSync(join2(dir, "breakdown.json"), JSON.stringify(out, null, 2));
   return out;
 }
@@ -21773,7 +21795,7 @@ async function teardownOne(handle, limit) {
       const { frames, interval } = sampleFrames(file, join2(dir, "frames", r.shortCode), m.duration, 2, 20);
       const [match, tr] = await Promise.all([call("match", { frames: frames.map(({ t, jpg_base64 }) => ({ t, jpg_base64 })), interval }), call("transcript", { url: r.url }).catch(() => ({ transcript: null }))]);
       const top = (o) => Object.keys(o)[0] ?? null;
-      rows.push({ code: r.shortCode, url: r.url, posted: String(r.timestamp ?? "").slice(0, 10), plays: r.videoPlayCount ?? null, duration_s: Math.round(m.duration * 10) / 10, cuts_per_min: m.cuts_per_min, layout: top(match.summary.layout_share), caption: top(match.summary.caption_share), effects: match.summary.effects.filter((e) => e.share >= 0.1 || e.frames >= 2).map((e) => e.title), hook: tr.transcript ? String(tr.transcript).split(/(?<=[.!?])\s/)[0] : null, cta: ctaKeyword(r.caption) });
+      rows.push({ code: r.shortCode, url: r.url, posted: String(r.timestamp ?? "").slice(0, 10), plays: r.videoPlayCount ?? null, duration_s: Math.round(m.duration * 10) / 10, cuts_per_min: m.cuts_per_min, layout: top(match.summary.layout_share), caption: top(match.summary.caption_share), effects: match.summary.effects.filter((e) => e.share >= 0.1 || e.frames >= 2).map((e) => e.title), off_menu: match.summary.effects.filter((e) => e.in_menu === false).map((e) => e.title), hook: tr.transcript ? String(tr.transcript).split(/(?<=[.!?])\s/)[0] : null, cta: ctaKeyword(r.caption) });
     } catch (e) {
       rows.push({ code: r.shortCode, url: r.url, posted: String(r.timestamp ?? "").slice(0, 10), plays: r.videoPlayCount ?? null, error: e.message, effects: [] });
     }
@@ -21786,6 +21808,8 @@ function rollup(rows) {
   const topSet = new Set(byPlays.slice(0, Math.max(1, Math.round(byPlays.length / 4))).map((r) => r.code));
   const rest = ok.filter((r) => !topSet.has(r.code));
   const names = [...new Set(ok.flatMap((r) => r.effects))];
+  const off = new Set(ok.flatMap((r) => r.off_menu ?? []));
+  const p2 = (n) => Math.round(n * 100) / 100;
   const count = (k) => {
     const c = {};
     for (const r of ok) if (r[k]) c[r[k]] = (c[r[k]] ?? 0) + 1;
@@ -21801,7 +21825,7 @@ function rollup(rows) {
     layouts: count("layout"),
     captions: count("caption"),
     ctas: count("cta"),
-    effects: names.map((n) => ({ effect: n, share: ok.filter((r) => r.effects.includes(n)).length / Math.max(ok.length, 1), top_share: ok.filter((r) => topSet.has(r.code) && r.effects.includes(n)).length / Math.max(topSet.size, 1), rest_share: rest.filter((r) => r.effects.includes(n)).length / Math.max(rest.length, 1) })).sort((a, b) => b.share - a.share)
+    effects: names.map((n) => ({ effect: n, in_menu: !off.has(n), share: p2(ok.filter((r) => r.effects.includes(n)).length / Math.max(ok.length, 1)), top_share: p2(ok.filter((r) => topSet.has(r.code) && r.effects.includes(n)).length / Math.max(topSet.size, 1)), rest_share: p2(rest.filter((r) => r.effects.includes(n)).length / Math.max(rest.length, 1)) })).sort((a, b) => b.share - a.share)
   };
 }
 async function creatorTeardown(input) {
@@ -21815,7 +21839,7 @@ async function creatorTeardown(input) {
     const rb = rollup(b.rows);
     const mine = Object.fromEntries(rb.effects.map((e) => [e.effect, e.share]));
     const regular = r.effects.filter((e) => e.share >= 0.25);
-    cmp = { handle: input.compare_to.replace(/^@/, ""), rollup: rb, missing: regular.filter((e) => !(e.effect in mine)).map((e) => e.effect), underused: regular.filter((e) => e.effect in mine && mine[e.effect] < e.share / 2).map((e) => ({ effect: e.effect, theirs: e.share, yours: mine[e.effect] })) };
+    cmp = { handle: input.compare_to.replace(/^@/, ""), rollup: rb, missing: regular.filter((e) => !(e.effect in mine)).map((e) => ({ effect: e.effect, in_menu: e.in_menu })), underused: regular.filter((e) => e.effect in mine && mine[e.effect] < e.share / 2).map((e) => ({ effect: e.effect, in_menu: e.in_menu, theirs: e.share, yours: mine[e.effect] })) };
   }
   const md = [
     `# Creator teardown: @${handle}`,
@@ -21832,7 +21856,7 @@ async function creatorTeardown(input) {
     "| effect | share of reels | top quarter by plays | the rest |",
     "| - | - | - | - |",
     ...r.effects.map((e) => `| ${e.effect} | ${pct(e.share)} | ${pct(e.top_share)} | ${pct(e.rest_share)} |`),
-    ...cmp ? ["", `## Gap vs @${cmp.handle}`, ...cmp.missing.length ? [`Never used by @${cmp.handle}:`, ...cmp.missing.map((x) => `- ${x}`)] : ["Nothing they use regularly is entirely missing."], ...cmp.underused.length ? ["Used at under half their rate:", ...cmp.underused.map((u) => `- ${u.effect}: ${pct(u.theirs)} of their reels vs ${pct(u.yours)} of yours`)] : []] : [],
+    ...cmp ? ["", `## Gap vs @${cmp.handle}`, ...cmp.missing.length ? [`Never used by @${cmp.handle}:`, ...cmp.missing.map((x) => `- ${x.effect}${x.in_menu ? " (in your menu)" : ""}`)] : ["Nothing they use regularly is entirely missing."], ...cmp.underused.length ? ["Used at under half their rate:", ...cmp.underused.map((u) => `- ${u.effect}${u.in_menu ? " (in your menu)" : ""}: ${pct(u.theirs)} of their reels vs ${pct(u.yours)} of yours`)] : []] : [],
     "",
     "## Reels",
     "| posted | plays | s | cuts/min | layout | effects | hook |",
@@ -21857,7 +21881,7 @@ var resolveProject = (p) => {
   const folder = resolve2(p.replace(/^~/, homedir2()));
   const file = existsSync2(projectFile(folder)) ? projectFile(folder) : existsSync2(join3(HOME(), "renders", p, ".cutroom", "project.json")) ? join3(HOME(), "renders", p, ".cutroom", "project.json") : null;
   if (!file) throw new Error(`No prepared footage at ${p}. Run prepare_footage first.`);
-  return JSON.parse(readFileSync2(file, "utf8"));
+  return JSON.parse(readFileSync3(file, "utf8"));
 };
 function cutAndNormalize(src, out, segments) {
   const parts = segments.map(([s, e], i) => `[0:v]trim=${s}:${e},setpts=PTS-STARTPTS[v${i}];[0:a]atrim=${s}:${e},asetpts=PTS-STARTPTS[a${i}];`).join("");
@@ -21892,7 +21916,7 @@ async function prepareFootage(input) {
   })();
   if (t.status !== 0 || !meta2.ok) throw new Error(`Transcription failed. Run cutroom_doctor.
 ${meta2.error ?? tail(t.stderr)}`);
-  const raw = JSON.parse(readFileSync2(meta2.transcriptPath ?? join3(work, "transcript.json"), "utf8"));
+  const raw = JSON.parse(readFileSync3(meta2.transcriptPath ?? join3(work, "transcript.json"), "utf8"));
   const words = raw.map((w) => ({ t: Math.round(w.start * 100) / 100, e: Math.round(w.end * 100) / 100, w: w.text.trim() })).filter((w) => w.w);
   const project = { name, folder, source, footage, duration: Math.round(duration3 * 100) / 100, words, removed_s: Math.round((p.duration - duration3) * 10) / 10, segments };
   writeFileSync2(projectFile(folder), JSON.stringify(project, null, 2));
@@ -21913,7 +21937,7 @@ async function ensureFonts(work) {
     for (const [f, b64] of Object.entries(fonts)) writeFileSync2(join3(cache, basename(f)), Buffer.from(b64, "base64"));
   }
   mkdirSync3(join3(work, "fonts"), { recursive: true });
-  for (const f of need) writeFileSync2(join3(work, "fonts", f), readFileSync2(join3(cache, f)));
+  for (const f of need) writeFileSync2(join3(work, "fonts", f), readFileSync3(join3(cache, f)));
 }
 function applyFixes(words, fixes = []) {
   return words.map((w) => {
@@ -21924,7 +21948,7 @@ function applyFixes(words, fixes = []) {
 var brandFile = () => join3(HOME(), "brand.json");
 function getBrand() {
   try {
-    return JSON.parse(readFileSync2(brandFile(), "utf8"));
+    return JSON.parse(readFileSync3(brandFile(), "utf8"));
   } catch {
     return null;
   }
@@ -21941,11 +21965,93 @@ async function setBrand(input) {
   writeFileSync2(brandFile(), JSON.stringify(next, null, 2));
   return { brand: next, saved: brandFile(), next: "Every render now uses these. Render a draft to see them." };
 }
+var PICTURE = /\.(jpe?g|png|webp)$/i;
+function safeAssetName(file, i) {
+  const m = basename(file).match(PICTURE);
+  if (!m) throw new Error(`Pictures must be jpg, png or webp: ${file}`);
+  const ext = m[1].toLowerCase() === "jpeg" ? "jpg" : m[1].toLowerCase();
+  return `${i + 1}-${slug2(basename(file, extname(file)))}.${ext}`;
+}
+function localImages(work, layoutImages, effects) {
+  const names = /* @__PURE__ */ new Map();
+  const dir = join3(work, "assets");
+  const swap = (v) => {
+    const raw = String(v ?? "").trim();
+    if (/^assets\/[\w.-]+$/.test(raw) && existsSync2(join3(work, raw))) return raw;
+    const file = resolve2(raw.replace(/^~(?=$|\/)/, homedir2()));
+    if (!names.has(file)) {
+      if (!existsSync2(file) || !statSync(file).isFile()) throw new Error(`Can't find the picture ${raw}. Use the full path of a jpg, png or webp file on this computer.`);
+      if (names.size >= 8) throw new Error("8 pictures at most per reel.");
+      const name = safeAssetName(file, names.size);
+      mkdirSync3(dir, { recursive: true });
+      copyFileSync(file, join3(dir, name));
+      names.set(file, `assets/${name}`);
+    }
+    return names.get(file);
+  };
+  const images = layoutImages?.length ? layoutImages.map(swap) : void 0;
+  const fx = effects.map((f) => ({
+    ...f,
+    ...f.image !== void 0 ? { image: swap(f.image) } : {},
+    ...Array.isArray(f.images) ? { images: f.images.map(swap) } : {}
+  }));
+  return { images, effects: fx, count: names.size };
+}
+async function wantsCutout(layout, effects) {
+  const styles = await call("styles");
+  const slugs = new Set(effects.map((f) => String(f.slug)));
+  return [...styles.layouts.filter((l) => l.slug === (layout ?? "full-frame")), ...styles.effects.filter((e) => slugs.has(e.slug))].some((x) => x.needs?.includes("cutout"));
+}
+function headTop(work, duration3) {
+  const tops = [];
+  for (const at of [0.2, 0.5, 0.8].map((f) => f * duration3)) {
+    const r = spawnSync3("ffmpeg", ["-nostdin", "-v", "error", "-c:v", "libvpx-vp9", "-ss", at.toFixed(2), "-i", "cut.webm", "-frames:v", "1", "-vf", "alphaextract,scale=108:192", "-f", "rawvideo", "-pix_fmt", "gray", "-"], { cwd: work, maxBuffer: 1 << 20 });
+    const px = r.stdout;
+    if (r.status !== 0 || !px || px.length < 108 * 192) continue;
+    for (let y = 0; y < 192; y++) {
+      let n = 0;
+      for (let x = 32; x < 76; x++) if (px[y * 108 + x] > 128) n++;
+      if (n >= 3) {
+        tops.push(y * 10);
+        break;
+      }
+    }
+  }
+  tops.sort((a, b) => a - b);
+  return tops.length ? tops[Math.floor(tops.length / 2)] : void 0;
+}
+function ensureCutout(work, duration3) {
+  const footage = join3(work, "footage.mp4"), cut = join3(work, "cut.webm"), stamp = join3(work, "cut.json"), still = join3(work, "assets", "still.jpg");
+  const st = statSync(footage);
+  const key = { size: st.size, mtime: Math.round(st.mtimeMs) };
+  let cached2 = null;
+  try {
+    cached2 = JSON.parse(readFileSync3(stamp, "utf8"));
+  } catch {
+  }
+  let made_s = 0;
+  if (!(cached2 && cached2.size === key.size && cached2.mtime === key.mtime && existsSync2(cut))) {
+    const started = Date.now();
+    const r = sh("npx", ["--yes", HF, "remove-background", "footage.mp4", "-o", "cut.webm", "--json"], work);
+    if (r.status !== 0 || !existsSync2(cut)) throw new Error(`Couldn't cut you out of the background. Run cutroom_doctor.
+${tail(r.stderr) || tail(r.stdout)}`);
+    made_s = Math.round((Date.now() - started) / 100) / 10;
+    cached2 = { ...key, head: headTop(work, duration3), made_s };
+    writeFileSync2(stamp, JSON.stringify(cached2));
+  }
+  if (!existsSync2(still)) {
+    mkdirSync3(join3(work, "assets"), { recursive: true });
+    sh("ffmpeg", ["-nostdin", "-v", "error", "-y", "-ss", (duration3 / 3).toFixed(2), "-i", "footage.mp4", "-frames:v", "1", "-q:v", "3", still], work);
+  }
+  return { head: cached2.head, made_s };
+}
 async function renderReel(input) {
   const pj = resolveProject(input.project);
   const work = join3(pj.folder, ".cutroom");
   const words = applyFixes(pj.words, input.fixes);
-  const { html } = await call("compose", { duration: pj.duration, words, layout: input.layout, caption: input.caption, effects: input.effects ?? [], emphasis: input.emphasis, brand: getBrand() ?? void 0 });
+  const local = localImages(work, input.images, input.effects ?? []);
+  const cutout = await wantsCutout(input.layout, local.effects) ? ensureCutout(work, pj.duration) : null;
+  const { html } = await call("compose", { duration: pj.duration, words, layout: input.layout, caption: input.caption, effects: local.effects, images: local.images, emphasis: input.emphasis, brand: getBrand() ?? void 0, ...cutout ? { cutout: true, head: cutout.head } : {} });
   await ensureFonts(work);
   const out = join3(pj.folder, `${pj.name}${input.draft ? "-draft" : ""}.mp4`);
   const tmp = join3(work, "render.mp4");
@@ -21963,7 +22069,7 @@ ${tail(r.stderr) || tail(r.stdout)}`);
   renameSync(tmp, out);
   const render_s = Math.round((Date.now() - started) / 100) / 10;
   const qa = await qaVideo({ video: out, write_report: true, layout: input.layout });
-  return { video: out, render_s, qa, next: qa.passed ? "Watch it once, then it's ready to post." : "Fix the issues listed (usually: move an effect, fix a word, or re-record a bit), then render_reel again." };
+  return { video: out, render_s, ...cutout?.made_s ? { cutout_s: cutout.made_s } : {}, qa, next: qa.passed ? "Watch it once, then it's ready to post." : "Fix the issues listed (usually: move an effect, fix a word, or re-record a bit), then render_reel again." };
 }
 async function qaVideo(input) {
   const file = resolve2(input.video.replace(/^~/, homedir2()));
@@ -22027,16 +22133,16 @@ Tear down a creator: call creator_teardown (compare_to = the user's own handle i
 Finish a video (raw talking-head file: edit it, add captions or effects, make it a reel):
 1. prepare_footage with the file path.
 2. From the timed transcript, list words that look misheard (names, brands) and confirm spellings with the user.
-3. list_styles, then propose one layout, one caption style and 2 to 4 effects tied to moments in the transcript (a number gets number-pop, steps get checklist, the CTA line gets comment-dm or follow-tap). Effect text uses only the user's own words and numbers. Show the plan with times and get a yes.
+3. list_styles (share its gallery link so the user can see each style moving), then propose one layout, one caption style and 2 to 4 effects tied to moments in the transcript (a number gets number-pop, steps get checklist, the CTA line gets comment-dm or follow-tap). Effect text uses only the user's own words and numbers. Show the plan with times and get a yes. Effects and layouts marked needs "cutout" (text behind you, orbit, card wall, cut-out layouts) first cut the speaker out of the background on this computer: about 6 seconds of work per second of video, once per video; say so before you start. Ones marked needs "images" take the user's own pictures as file paths; ask for them, or use the fallback the effect describes.
 4. render_reel with draft:true; tell them where the file is and what QA found.
 5. After they approve (or after changes), render_reel without draft for the final.
-6. Explain any QA issue in plain words with its time, and offer the fix.
+6. QA "look" lines are spots to check, not failures: busy edits often get flagged on purpose (cards running off the edge, a card over a board). For each flagged time, grab that frame with ffmpeg and look at it yourself, then tell the user which ones are real problems (with the fix) and which are the design. Technical issues (frozen picture, loudness, black frames) are real; say if a freeze is a deliberate hold.
 
 Brand: before a user's first render, call show_brand; if none is set, offer to set it with set_brand. If they give a website or logo instead of colors, pick 3 colors from it (background, accent, highlight), show them, and save on a yes.
 
 Results are saved in ~/Cutroom. Study only for other creators' reels: never reuse their words, footage or branding.`;
 await serveStdio(() => {
-  const server = new McpServer({ name: "cutroom", version: "0.5.0" }, { instructions: INSTRUCTIONS });
+  const server = new McpServer({ name: "cutroom", version: "0.5.1" }, { instructions: INSTRUCTIONS });
   server.registerTool("cutroom_doctor", {
     description: "Check Cutroom is ready: ffmpeg on this computer and an active membership key. Returns each check with the exact fix. Run it first, and whenever a tool fails.",
     inputSchema: object({})
@@ -22099,12 +22205,13 @@ ${m.text}`;
     })
   }, async (input) => safe(() => prepareFootage(input)));
   server.registerTool("render_reel", {
-    description: "Step 2: render the prepared footage in a Cutroom layout with a caption style and effects, on this computer, then QA it (technical checks plus every sampled frame judged). Saves <name>.mp4 and <name>.qa.md in the project folder. Use draft:true for a fast preview. Effect times are seconds in the prepared (trimmed) video.",
+    description: "Step 2: render the prepared footage in a Cutroom layout with a caption style and effects, on this computer, then QA it (technical checks plus every sampled frame judged). Saves <name>.mp4 and <name>.qa.md in the project folder. Use draft:true for a fast preview. Effect times are seconds in the prepared (trimmed) video. Layouts and effects that cut the speaker out of the background (see needs in list_styles) run a one-time cut-out first: about 5 to 6 seconds per second of footage, reused for later renders of the same project.",
     inputSchema: object({
       project: string2().min(1).describe("The project folder returned by prepare_footage."),
       layout: string2().default("full-frame"),
       caption: string2().default("two-tier"),
-      effects: array(object({ slug: string2(), start: number2().min(0), dur: number2().min(1.2).max(5).optional() }).passthrough()).max(12).default([]).describe("e.g. [{slug:'number-pop', start:3.2, number:'24', label:'hours later'}]. Params per effect are in list_styles."),
+      effects: array(object({ slug: string2(), start: number2().min(0), dur: number2().min(1.2).max(5).optional() }).passthrough()).max(12).default([]).describe("e.g. [{slug:'number-pop', start:3.2, number:'24', label:'hours later'}]. Params per effect are in list_styles. Effect params image / images are picture files on this computer (full paths, jpg/png/webp); they are copied into the render folder, only the file name goes to Cutroom."),
+      images: array(string2()).max(8).optional().describe("Pictures for the layout (image-cluster: 3 to 5, cutout-grid: 1 to 8, cutout-backdrop: optional): full paths of jpg, png or webp files on this computer. 8 pictures at most per reel, layout and effects together."),
       emphasis: array(string2()).optional().describe("Words to highlight in captions (otherwise numbers, then the longest word of each phrase)."),
       fixes: array(object({ from: string2(), to: string2() })).optional().describe("Transcript corrections; to:'' drops the word."),
       draft: boolean2().default(false)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keepylabs/cutroom",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Cutroom for Claude Code: hooks and scripts with scoring, reel breakdowns, creator teardowns, and finishing your own videos with QA. Needs a Keepy Labs membership key.",
   "type": "module",
   "bin": {