@keepylabs/cutroom 0.5.1 → 0.5.3

package/README.md

@@ -5,7 +5,7 @@ Write hooks and scripts with scoring. Break down any reel. Tear down a creator's
 ## Install (one command)
 In your terminal, with your key from the welcome email:
 
-    claude mcp add cutroom -s user -e CUTROOM_KEY=ck_yourkey -- npx -y @keepylabs/cutroom
+    claude mcp add cutroom -s user -e CUTROOM_KEY=ck_yourkey -- npx -y @keepylabs/cutroom@latest
 
 Restart Claude Code and say "check Cutroom is ready". It checks ffmpeg and Node and installs them with your OK.
 

package/cutroom.mjs

@@ -21531,9 +21531,12 @@ function toError(value) {
   return value instanceof Error ? value : new Error(String(value));
 }
 
+// src/community/local/server.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+
 // src/community/local/render.ts
 import { spawnSync as spawnSync3 } from "node:child_process";
-import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, readdirSync, 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";
 
@@ -22045,7 +22048,8 @@ ${tail(r.stderr) || tail(r.stdout)}`);
   }
   return { head: cached2.head, made_s };
 }
-async function renderReel(input) {
+var planFile = (folder) => join3(folder, ".cutroom", "plan.json");
+async function composition(input) {
   const pj = resolveProject(input.project);
   const work = join3(pj.folder, ".cutroom");
   const words = applyFixes(pj.words, input.fixes);
@@ -22053,10 +22057,77 @@ async function renderReel(input) {
   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);
+  writeFileSync2(join3(work, "meta.json"), JSON.stringify({ id: pj.name, name: pj.name }));
+  return { pj, work, html, cutout, words };
+}
+var fmtT = (t) => `${t.toFixed(1)}s`;
+var SHOWN = ["word", "text", "title", "number", "label", "eyebrow", "keyword", "items", "lines", "labels", "steps", "message", "before", "after", "note"];
+var fxLine = (f) => SHOWN.filter((k) => f[k] !== void 0 && f[k] !== "").map((k) => k === "keyword" ? `comment "${f[k]}"` : Array.isArray(f[k]) ? f[k].join(" / ") : String(f[k])).join(" \xB7 ");
+async function planReel(input) {
+  const { pj, work, html, cutout, words } = await composition(input);
+  const effects = [...input.effects ?? []].sort((a, b) => Number(a.start) - Number(b.start));
+  const peak = (f) => {
+    const d = Math.min(Math.max(Number(f.dur) || 2.5, 1.2), 5);
+    return Math.min(pj.duration - 0.1, Number(f.start) + Math.max(d * 0.5, d - (f.slug === "comment-dm" ? 0.32 : 0.55)));
+  };
+  const plainAt = effects.length && Number(effects[0].start) > 2 ? 1.2 : null;
+  const styles = await call("styles");
+  const title = (list, slug3) => (list.find((x) => x.slug === slug3)?.title ?? String(slug3)).replace(/\s*\(.*\)$/, "");
+  const said = (from, to) => words.filter((w) => w.t >= from - 0.05 && w.t < to).map((w) => w.w).join(" ");
+  const ends = effects.map((f, k) => Math.min(effects[k + 1] ? Number(effects[k + 1].start) : pj.duration, Number(f.start) + Math.min(Math.max(Number(f.dur) || 2.5, 1.2), 5)));
+  const moments = [
+    ...plainAt !== null ? [{ t: plainAt, end: Number(effects[0].start), what: "just you and the captions", tag: "you + captions", at: plainAt }] : [],
+    ...effects.map((f, k) => {
+      const name = title(styles.effects, f.slug);
+      return { t: Number(f.start), end: ends[k], what: `${name}${fxLine(f) ? `: ${fxLine(f)}` : ""}`, tag: name, at: peak(f) };
+    })
+  ];
+  const shots = join3(work, "storyboard");
+  rmSync(shots, { recursive: true, force: true });
+  writeFileSync2(join3(work, "index.html"), html);
+  let r;
+  try {
+    r = sh("npx", ["--yes", HF, "snapshot", "--at", moments.map((m) => m.at.toFixed(2)).join(","), "--no-end", "--describe", "false", "-o", "storyboard", "."], work);
+  } finally {
+    rmSync(join3(work, "index.html"), { force: true });
+  }
+  const pngs = existsSync2(shots) ? readdirSync(shots).filter((f) => f.endsWith(".png")).sort() : [];
+  if (r.status !== 0 || pngs.length < moments.length) throw new Error(`Couldn't make the storyboard. Run cutroom_doctor.
+${tail(r.stderr) || tail(r.stdout)}`);
+  const board = join3(pj.folder, `${pj.name}-storyboard.jpg`);
+  const cols = Math.min(4, moments.length);
+  const label = (s) => s.replace(/[\\':%,]/g, " ").slice(0, 42);
+  const inputs = pngs.slice(0, moments.length).flatMap((f) => ["-i", join3(shots, f)]);
+  const cells = moments.map((m, k) => `[${k}:v]scale=270:480,pad=270:540:0:0:#0A0A0A,drawtext=text='${label(`${fmtT(m.t)}  ${m.tag}`)}':x=10:y=496:fontsize=18:fontcolor=#F7F3E8[c${k}]`).join(";");
+  const layoutXY = moments.map((_, k) => `${k % cols * 270}_${Math.floor(k / cols) * 540}`).join("|");
+  const stack = moments.length === 1 ? `[c0]copy[out]` : `${moments.map((_, k) => `[c${k}]`).join("")}xstack=inputs=${moments.length}:layout=${layoutXY}:fill=#0A0A0A[out]`;
+  const t = sh("ffmpeg", ["-nostdin", "-v", "error", "-y", ...inputs, "-filter_complex", `${cells};${stack}`, "-map", "[out]", "-frames:v", "1", "-q:v", "3", board]);
+  if (t.status !== 0) throw new Error(`Couldn't tile the storyboard.
+${tail(t.stderr)}`);
+  rmSync(shots, { recursive: true, force: true });
+  const plan = { layout: input.layout ?? "full-frame", caption: input.caption ?? "two-tier", effects, images: input.images, emphasis: input.emphasis, fixes: input.fixes };
+  writeFileSync2(planFile(pj.folder), JSON.stringify(plan, null, 2));
+  const text = [
+    `Plan for ${pj.name} (${pj.duration.toFixed(1)}s). Layout: ${title(styles.layouts, plan.layout)}. Captions: ${title(styles.captions, plan.caption)}.${cutout ? " You are cut out of the background for this one (done)." : ""}`,
+    "",
+    "| Time | What you say | What shows on screen |",
+    "| - | - | - |",
+    ...moments.map((m) => `| ${m.t.toFixed(1)} to ${m.end.toFixed(1)}s | ${said(m.t, m.end).replace(/\|/g, "/") || "(pause)"} | ${m.what.replace(/\|/g, "/")} |`),
+    "",
+    `Storyboard: ${board}`
+  ].join("\n");
+  return { text, storyboard: board, plan, words_used: words.length, next: "Show this table as it is (plain words, no effect codes) and the storyboard. On changes, plan_reel again with the new choice. On a go, render_reel with plan:true and draft:true." };
+}
+async function renderReel(input) {
+  if (input.plan) {
+    const folder = resolveProject(input.project).folder;
+    if (!existsSync2(planFile(folder))) throw new Error("No plan yet for this project. Make one with plan_reel first.");
+    input = { ...JSON.parse(readFileSync3(planFile(folder), "utf8")), project: input.project, draft: input.draft };
+  }
+  const { pj, work, html, cutout } = await composition(input);
   const out = join3(pj.folder, `${pj.name}${input.draft ? "-draft" : ""}.mp4`);
   const tmp = join3(work, "render.mp4");
   writeFileSync2(join3(work, "index.html"), html);
-  writeFileSync2(join3(work, "meta.json"), JSON.stringify({ id: pj.name, name: pj.name }));
   const started = Date.now();
   let r;
   try {
@@ -22069,7 +22140,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, ...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." };
+  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." : qa.technical?.length ? "Fix the technical issues listed, then render again." : "Look at each flagged spot yourself (grab the frame) and tell the user which are real problems, with the fix, and which are the design." };
 }
 async function qaVideo(input) {
   const file = resolve2(input.video.replace(/^~/, homedir2()));
@@ -22133,16 +22204,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 (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.
+3. Plan: list_styles (share its gallery link so the user can see each style moving), then get_method('edit_plan') and follow it: every scene of the transcript gets a visual, shown as a plain table (Time | What you say | What shows on screen), never effect codes. Call plan_reel with that choice and show the user its table and the storyboard (one frame per scene). They change anything ("move the checklist to 30s", "swap orbit for card wall"): plan_reel again. Nothing renders until they say go. No B-roll unless they ask for it. 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. On a go: render_reel with plan:true and draft:true; tell them where the file is and what QA found.
+5. After they approve the draft: render_reel with plan:true (no draft) for the final. After changes: plan_reel, then render again.
 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.1" }, { instructions: INSTRUCTIONS });
+  const server = new McpServer({ name: "cutroom", version: "0.5.3" }, { 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({})
@@ -22204,17 +22275,39 @@ ${m.text}`;
       cut_pauses: boolean2().default(true).describe("Cut pauses longer than about half a second.")
     })
   }, async (input) => safe(() => prepareFootage(input)));
+  server.registerTool("plan_reel", {
+    description: "Step 2: the plan before anything renders. Takes the same choice as render_reel (layout, caption, effects with times, images) and returns the plan as lines plus a storyboard image: one real frame of the user's video per moment, with the effect on it, in their brand. About 10 to 20 seconds (plus the one-time cut-out if the choice needs it). Saves the plan so render_reel with plan:true renders exactly this. Show the storyboard and get a go before rendering.",
+    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(24).default([]).describe("Same as render_reel: e.g. [{slug:'number-pop', start:3.2, number:'24', label:'hours later'}]."),
+      images: array(string2()).max(8).optional().describe("Pictures for the layout, full paths on this computer."),
+      emphasis: array(string2()).optional(),
+      fixes: array(object({ from: string2(), to: string2() })).optional().describe("Transcript corrections; to:'' drops the word.")
+    })
+  }, async (input) => {
+    try {
+      const r = await planReel(input);
+      return { content: [{ type: "text", text: `${r.text}
+
+${r.next}` }, { type: "image", data: readFileSync4(r.storyboard).toString("base64"), mimeType: "image/jpeg" }] };
+    } catch (e) {
+      return failure2(e);
+    }
+  });
   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. 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.",
+    description: "Step 3: 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. 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."),
+      effects: array(object({ slug: string2(), start: number2().min(0), dur: number2().min(1.2).max(5).optional() }).passthrough()).max(24).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)
+      draft: boolean2().default(false),
+      plan: boolean2().default(false).describe("Render the plan saved by the last plan_reel for this project (ignores layout, caption, effects and images given here).")
     })
   }, async (input) => safe(() => renderReel(input)));
   server.registerTool("qa_video", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keepylabs/cutroom",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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": {