kasaframe 0.0.0-stage → 0.1.1

package/packages/cli/src/commands/new.ts

@@ -0,0 +1,176 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { themeStyle } from "@kasaframe/themes";
+import { type Aspect, type BeatsLike, type Plan, type Purpose, listTemplates, loadTemplate, makePlan, parseTitle, PURPOSES, sceneSkeleton, templatesDir } from "@kasaframe/plan";
+import { type Command, num, parseFlags } from "../command.ts";
+
+const repo = fileURLToPath(new URL("../../../../", import.meta.url));
+const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+
+const cmd: Command = {
+  summary: "용도 틀에서 프로젝트 뼈대 — 곡 분석·박에 맞춘 장면 시간표·장면 파일",
+  usage: `kf new <폴더> --template <용도>(또는 --purpose) [--music 곡.mp3] [--style 프리셋] [--duration 초] [--aspect 9:16] [--title 이름] [--line 끝 카드 한 줄]
+kf new <폴더> --request "요청 글" [--music 곡.mp3]   용도를 요청 글로 고른다
+kf new <폴더> --plan plan.json                        kf make 가 세운 계획 그대로
+
+  용도: ${PURPOSES.join(" · ")}
+  --theme    테마 id(themes/<id>, approved·review) 또는 auto(내용에 맞는 approved 후보 셋 중 첫째) — 고르면 그 테마 style 을 쓴다
+  --force    비어 있지 않은 폴더에도 쓴다(있는 장면 파일은 그대로 둔다)
+  --preview  다 만들고 kf preview 를 띄운다
+
+만든 뒤: scenes/<id>.ts 를 kf.json 의 idea 대로 채운다 → kf preview <폴더> → kf render <폴더> → kf check <폴더>`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const dir = args[0] ? resolve(args[0]) : undefined;
+    if (!dir) {
+      console.error("kf new: 폴더가 필요하다. kf new --help");
+      return 2;
+    }
+    if (existsSync(dir) && readdirSync(dir).length > 0 && !opts.force) {
+      console.error(`kf new: ${dir} 가 비어 있지 않다. 덮어쓰려면 --force`);
+      return 2;
+    }
+    const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+    // --purpose 는 kf make 와 같은 이름 — 둘 다 받는다
+    const template = str("template") ?? str("purpose");
+    if (template && !PURPOSES.includes(template as Purpose)) {
+      console.error(`kf new: 모르는 용도 "${template}". 있는 용도: ${listTemplates().map((t) => `${t.id}(${t.label})`).join(" ")}`);
+      return 2;
+    }
+    const planFile = str("plan");
+    const request = str("request");
+    if (!template && !planFile && !request) {
+      console.error(`kf new: --template · --request · --plan 중 하나가 필요하다. 용도: ${PURPOSES.join(" · ")}`);
+      return 2;
+    }
+
+    mkdirSync(join(dir, "scenes"), { recursive: true });
+    mkdirSync(join(dir, "assets", "gen"), { recursive: true });
+    mkdirSync(join(dir, "out"), { recursive: true });
+
+    const given: Plan | null = planFile ? JSON.parse(readFileSync(resolve(planFile), "utf8")) : null;
+    const musicSrc = str("music") ?? (given?.music && planFile ? resolve(planFile, "..", given.music) : undefined);
+    let music: string | null = null;
+    let beats: BeatsLike | null = null;
+    if (musicSrc) {
+      if (!existsSync(musicSrc)) {
+        console.error(`kf new: 곡이 없다: ${musicSrc}`);
+        return 2;
+      }
+      music = `assets/music/${basename(musicSrc)}`;
+      mkdirSync(join(dir, "assets", "music"), { recursive: true });
+      if (resolve(musicSrc) !== join(dir, music)) copyFileSync(musicSrc, join(dir, music));
+      const r = spawnSync(process.execPath, [kfBin, "beats", join(dir, music), "--out", join(dir, "beats.json")], { stdio: ["ignore", "inherit", "inherit"] });
+      if (r.status !== 0) {
+        console.error("kf new: 곡 분석(kf beats)이 실패했다 — 위 메시지를 보고 고친 뒤 다시");
+        return r.status ?? 1;
+      }
+      beats = JSON.parse(readFileSync(join(dir, "beats.json"), "utf8"));
+    }
+
+    const plan: Plan = given
+      ? { ...given, music }
+      : makePlan({
+          request: request ?? "",
+          purpose: template as Purpose | undefined,
+          music,
+          beats,
+          duration: opts.duration !== undefined ? num(opts.duration, 0) : undefined,
+          aspect: str("aspect") as Aspect | undefined,
+          style: str("style"),
+          title: str("title") ?? parseTitle(request ?? "") ?? basename(dir),
+          theme: str("theme"),
+        });
+    const purposeQ = plan.questions?.find((q) => q.id === "purpose");
+    if (purposeQ && !template) {
+      console.error(`kf new: 용도를 못 정했다(확신 ${plan.confidence}). --template 으로 골라 다시:\n  ${purposeQ.choices.join("\n  ")}`);
+      return 3;
+    }
+    if (!music && plan.questions?.some((q) => q.id === "music")) console.error(`kf new: 주의 — ${plan.questions.find((q) => q.id === "music")!.ask} (--music 으로 주면 박에 맞춘다)`);
+
+    const tpl = loadTemplate(plan.purpose);
+    let style;
+    if (plan.theme) style = themeStyle(plan.theme);
+    else {
+      let preset = join(repo, "presets", `${plan.style}.json`);
+      // 틀·요청 낱말이 고른 프리셋이 이 설치에 없을 수 있다(npm 패키지는 개인 프리셋을 안 싣는다) — 사람이 고른 게 아니면 기본으로
+      if (!existsSync(preset) && !str("style")) {
+        console.error(`kf new: 프리셋 "${plan.style}" 가 없어 neutral-dark 로`);
+        plan.style = "neutral-dark";
+        preset = join(repo, "presets", "neutral-dark.json");
+      }
+      if (!existsSync(preset)) {
+        const have = readdirSync(join(repo, "presets")).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5));
+        console.error(`kf new: 프리셋 "${plan.style}" 가 없다. 있는 프리셋: ${have.join(" ")}`);
+        return 2;
+      }
+      style = JSON.parse(readFileSync(preset, "utf8"));
+    }
+    // 틀의 움직임 규칙이 프리셋을 이긴다 — 쇼츠에 박 펄스가 켜진 프리셋을 골라도 쇼츠 규칙대로
+    style.motion = { ...style.motion, ...tpl.motion };
+
+    const frame = { width: plan.width, height: plan.height };
+    const safeArea = plan.aspect === tpl.aspect ? tpl.safeArea : (tpl.variants?.[plan.aspect]?.safeArea ?? tpl.safeArea);
+    const kf = {
+      template: plan.purpose,
+      title: plan.title,
+      ...(plan.theme ? { theme: plan.theme } : {}),
+      fps: plan.fps,
+      ...frame,
+      duration: plan.duration,
+      mode: "seek",
+      style: "style.json",
+      music,
+      beats: beats ? "beats.json" : null,
+      captions: plan.captions,
+      safeArea,
+      text: tpl.text,
+      scenes: plan.scenes.map((s) => ({ id: s.id, from: s.from, dur: s.dur, file: `scenes/${s.id}.ts`, role: s.role, idea: s.idea, assets: s.assets })),
+    };
+
+    const write = (rel: string, body: string) => writeFileSync(join(dir, rel), body);
+    write("kf.json", `${JSON.stringify(kf, null, 2)}\n`);
+    write("plan.json", `${JSON.stringify(plan, null, 2)}\n`);
+    write("style.json", `${JSON.stringify(style, null, 2)}\n`);
+    const fill = (src: string, vars: Record<string, string>) => src.replace(/\{\{(\w+)\}\}/g, (_, k) => (vars[k] ?? "").replace(/["\\]/g, "\\$&"));
+    const shared = join(templatesDir, "_shared", "project");
+    for (const f of ["index.html", "main.ts"]) write(f, fill(readFileSync(join(shared, f), "utf8"), { title: plan.title }));
+    // 뼈대가 같이 쓰는 무대(화면 채움·흐르는 바탕·이유 있을 때만 움직이는 카메라) — 장면 파일이 ../lib/ 로 가져간다
+    mkdirSync(join(dir, "lib"), { recursive: true });
+    for (const f of readdirSync(join(shared, "lib"))) if (!existsSync(join(dir, "lib", f))) copyFileSync(join(shared, "lib", f), join(dir, "lib", f));
+
+    const kept: string[] = [];
+    // 이어지는 장면이 같은 등장을 쓰지 않게 순번으로 돌린다(style.json repeatSameMove)
+    const MOVES = ["rise", "pop", "blurIn", "scaleIn", "maskWipe", "drop"];
+    for (const [i, s] of plan.scenes.entries()) {
+      const rel = `scenes/${s.id}.ts`;
+      if (existsSync(join(dir, rel))) {
+        kept.push(rel);
+        continue;
+      }
+      const step = plan.scenes.slice(0, i + 1).filter((x) => x.role === "step").length;
+      const word = s.role === "end" || s.role === "hook" || s.role === "brand" ? plan.title : s.role === "step" ? `${step}단계` : s.id.replace(/\d+$/, "").toUpperCase();
+      write(rel, fill(sceneSkeleton(plan.purpose, s.id, s.role), { word, title: plan.title, line: str("line") ?? "", move: MOVES[i % MOVES.length], transition: tpl.scenes.find((x) => x.id === s.id)?.transition ?? "dive" }));
+    }
+
+    const near = relative(process.cwd(), dir);
+    const rel = !near ? "." : near.startsWith("..") ? dir : near;
+    console.log(`${rel}/ — ${tpl.label}(${plan.purpose}) ${plan.aspect} ${plan.width}×${plan.height} · ${+plan.duration.toFixed(3)}초 · ${plan.theme ? `테마 ${plan.theme}` : `스타일 ${plan.style}`}${music ? ` · 곡 ${music}` : ""}`);
+    if (plan.themeCandidates?.length) console.log(`  테마 후보: ${plan.themeCandidates.map((c) => c.id).join(" · ")}`);
+    else if (str("theme") === "auto") console.log("  맞는 approved 테마가 없어 프리셋으로 간다");
+    for (const s of kf.scenes) console.log(`  ${s.from.toFixed(2).padStart(6)}–${(s.from + s.dur).toFixed(2).padEnd(6)} ${s.id.padEnd(9)} ${s.idea}`);
+    for (const r of plan.reasons.filter((x) => !x.startsWith('"'))) console.log(`  · ${r}`);
+    if (kept.length) console.log(`  있던 장면 파일은 그대로 뒀다: ${kept.join(" ")}`);
+    if (plan.gen?.length) console.log(`  만들 수 있는 자산(아직 안 만듦, 돈이 든다): ${plan.gen.map((g) => `gen:${g.kind}:${g.id}`).join(" ")} — 구체적인 프롬프트로 kf gen img --id <id> --project ${rel}`);
+    console.log(`\n다음: scenes/*.ts 를 kf.json 의 idea 대로 채운다 → kf preview ${rel} → kf render ${rel} → kf check ${rel}`);
+
+    if (opts.preview) {
+      const r = spawnSync(process.execPath, [kfBin, "preview", dir], { stdio: "inherit" });
+      return r.status ?? 0;
+    }
+    return 0;
+  },
+};
+export default cmd;

package/packages/cli/src/commands/preview.ts

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { studioPlugin } from "@kasaframe/studio";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+import { openProject } from "../serve.ts";
+
+const cmd: Command = {
+  summary: "미리보기 — 곡이 기준 시계, 타임라인·장면/박/드롭·프레임 이동, 저장하면 반영",
+  usage: `kf preview <폴더> [--port 5120] [--t 초] [--captions on|off]
+
+  주소 / 가 미리보기, /index.html 이 프로젝트 페이지 그대로다. ?t=12.3 으로 그 시각에서 연다.
+  scenes/*.ts 를 저장하면 프로젝트 페이지만 새로 고치고 보던 시각으로 돌아간다(kf.json·beats.json·style.json 도).
+  --captions 화면 자막을 켜고(끄고) 연다 — kf.json 은 그대로. 미리보기 단추(C)로도 바꾼다
+  조작: Space 재생 · ←→ 한 프레임 · Shift+←→ 1초 · Alt+←→ 박 · ↑↓ 장면·구간·드롭 경계 · L 반복
+        타임라인 끌기(Shift 누르면 박·마커에 붙음) · 세로 휠 확대 · 가로 휠 이동 · 두 번 눌러 전체
+  창은 띄우지 않는다. 끝내려면 Ctrl+C.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const dir = args[0];
+    if (!dir) {
+      console.error("kf preview: 폴더를 줘라 — kf preview <폴더>");
+      return 2;
+    }
+    if (!existsSync(join(resolve(dir), "index.html"))) {
+      console.error(`kf preview: ${resolve(dir)} 에 index.html 이 없다 — kf new 로 만든 프로젝트 폴더를 줘라`);
+      return 2;
+    }
+    const p = await openProject(dir, { port: num(opts.port, 5120), hmr: true, plugins: [studioPlugin(dir)] });
+    const q = new URLSearchParams();
+    if (opts.t !== undefined) q.set("t", String(num(opts.t, 0)));
+    if (opts.captions === "on" || opts.captions === "off" || opts.captions === "fit") q.set("captions", opts.captions);
+    const at = q.size ? `?${q}` : "";
+    console.log(`미리보기: ${p.url}${at}`);
+    await new Promise<void>((done) => {
+      const stop = () => void p.close().then(done, done);
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    });
+    return 0;
+  },
+};
+export default cmd;

package/packages/cli/src/commands/render.ts

@@ -0,0 +1,216 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+import { openSession, type Tab } from "../browser.ts";
+import { concat, encoder, type VideoFormat } from "../ffmpeg.ts";
+import { acquireRenderLock } from "../lock.ts";
+import { blurOpts, captureBlurred, rgbaToPng } from "../blur.ts";
+import { outPath } from "../out.ts";
+
+const MAX_TABS = 3;
+
+interface Chunk {
+  index: number;
+  start: number;
+  end: number;
+}
+
+function split(start: number, end: number, n: number): Chunk[] {
+  const total = end - start;
+  const out: Chunk[] = [];
+  for (let i = 0; i < n; i++) {
+    const a = start + Math.floor((total * i) / n);
+    const b = start + Math.floor((total * (i + 1)) / n);
+    if (b > a) out.push({ index: i, start: a, end: b });
+  }
+  return out;
+}
+
+function findMusic(dir: string, given: string | boolean | undefined, metaMusic?: string): string | undefined {
+  if (given === false || given === "none") return undefined;
+  if (typeof given === "string") return resolve(given);
+  if (metaMusic) {
+    const p = resolve(dir, metaMusic);
+    if (existsSync(p)) return p;
+    console.error(`곡을 못 찾았다: ${p} — 소리 없이 굽는다`);
+  }
+  return undefined;
+}
+
+// beats.json 의 from = 곡에서 잘라 쓴 시작. 영상 0초가 곡의 from 초라서, 곡을 얹을 때 그만큼 더 건너뛴다.
+function musicFrom(dir: string): number {
+  try {
+    const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) as { beats?: string };
+    if (!kf.beats) return 0;
+    const beats = JSON.parse(readFileSync(resolve(dir, kf.beats), "utf8")) as { from?: number };
+    return Number(beats.from) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+interface MotionEvent {
+  t: number;
+  kind: string;
+  source: string;
+  scene?: string;
+}
+
+// 움직임 부품이 쌓은 기록을 탭마다 모아 하나로 — step 모드는 pre-roll 구간이 겹쳐 같은 줄이 여러 탭에 있다.
+async function collectEvents(tabs: Tab[]): Promise<MotionEvent[]> {
+  const seen = new Set<string>();
+  const out: MotionEvent[] = [];
+  for (const tab of tabs) {
+    const rows = await tab.page.evaluate(() => (window.__kf?.events ?? []) as unknown[]).catch(() => []);
+    for (const r of rows as MotionEvent[]) {
+      const key = `${r.t}|${r.kind}|${r.source}|${r.scene ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(r);
+    }
+  }
+  return out.sort((a, b) => a.t - b.t);
+}
+
+// x.mp4 → x-자막.mp4 · frames → frames-자막
+function withSuffix(p: string, suffix: string): string {
+  if (!suffix) return p;
+  const ext = extname(p);
+  return ext ? `${p.slice(0, -ext.length)}${suffix}${ext}` : `${p}${suffix}`;
+}
+
+const cmd: Command = {
+  summary: "MP4(또는 ProRes·PNG 묶음)로 굽기 — 탭 병렬, 곡 얹기, 잠금",
+  usage: `kf render <폴더> [--out x.mp4] [--from 초 --to 초] [--tabs 3] [--prores | --png] [--music 곡 | --no-music] [--captions on|off|fit [--suffix]]
+  --out       기본 <폴더>/out/render.mp4 (--prores 면 .mov, --png 면 폴더)
+  --from/--to 구간만 굽는다. 곡도 그 구간만 잘라 얹는다
+  --tabs      크롬 탭 수(최대 ${MAX_TABS}). seek 모드는 구간을 나눠 찍고, step 모드는 탭마다 구간 앞까지 빨리 돌린 뒤 찍는다
+  --music     기본은 페이지 meta.music(kf.json 의 music). 곡은 beats.json 의 from 초부터 얹는다
+  --music-from 곡에서 시작할 초를 직접 준다(--music 으로 다른 곡을 줄 때)
+  --crf       H.264 화질(기본 16, 낮을수록 좋다)
+  --motion-blur N  한 프레임을 하위 프레임 N 장(예 8)으로 찍어 평균 — 빠른 것만 번진다. 3D 전환은 같은 평균으로 피사계 심도도. seek 모드만, N 배 느리다
+  --shutter   모션 블러 셔터 각도(기본 180 — 프레임 간격의 절반). 360 이면 다음 프레임까지 이어 번진다
+  --captions on|off|fit  화면 자막을 이 판만 켜거나 끈다(kf.json 의 captions 는 그대로). on 이면 captions.json 을 화면 아래 판에 얹고
+              안전 영역 아래쪽 자막 띠를 비운다(무대가 그 위로 배치) · fit 은 장면을 띠 위로 줄여 올린다(픽셀을 박아 둔 장면용)
+  --suffix [글] 결과 이름 뒤에 붙인다 — 값 없이 주면 --captions 에 따라 -자막 · -자막없음. 원본을 덮지 않고 둘 다 남길 때
+  --lock-wait 다른 렌더가 잠금을 쥐고 있을 때 기다릴 초(기본 900)
+  --no-lock   잠금 없이(시험용 짧은 구간)
+끝나면 같은 이름의 .json(png 는 폴더 안 render.json)에 meta·구간·걸린 시간·markers·움직임 events 를 남긴다.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const dir = args[0];
+    if (!dir) {
+      console.error("kf render: 폴더를 줘라 — kf render <폴더> --out x.mp4");
+      return 2;
+    }
+    const format: VideoFormat | "png" = opts.png ? "png" : opts.prores ? "prores" : "h264";
+    const ext = format === "prores" ? ".mov" : format === "png" ? "" : ".mp4";
+    const captions = opts.captions === undefined ? undefined : String(opts.captions);
+    if (captions !== undefined && captions !== "on" && captions !== "off" && captions !== "fit") throw new Error(`--captions 는 on·off·fit: ${captions}`);
+    const suffix = typeof opts.suffix === "string" ? opts.suffix : opts.suffix ? (captions === "off" ? "-자막없음" : "-자막") : "";
+    const out = withSuffix(outPath(dir, opts.out, format === "png" ? "frames/x" : `render${ext}`).replace(/\/x$/, ""), suffix);
+    if (format !== "png" && extname(out) === "") throw new Error(`--out 에 확장자가 없다: ${out}`);
+
+    const release = opts["no-lock"] ? () => {} : await acquireRenderLock(resolve(dir), num(opts["lock-wait"], 900));
+    const started = Date.now();
+    const s = await openSession(dir, { query: captions ? `captions=${captions}` : undefined });
+    const tmp = join(resolve(dir), "out", `.kf-render-${process.pid}`);
+    try {
+      const { meta, mode } = s.info;
+      const { fps } = meta;
+      const total = Math.round(meta.duration * fps);
+      const startF = Math.max(0, Math.floor(num(opts.from, 0) * fps + 1e-6));
+      const endF = Math.min(total, Math.ceil(num(opts.to, meta.duration) * fps - 1e-6));
+      if (endF <= startF) throw new Error(`굽을 프레임이 없다 (${startF}..${endF})`);
+      const frames = endF - startF;
+      const tabs = Math.max(1, Math.min(MAX_TABS, num(opts.tabs, MAX_TABS), Math.ceil(frames / fps)));
+      const chunks = split(startF, endF, tabs);
+      const music = format === "png" ? undefined : findMusic(dir, opts["no-music"] ? false : opts.music, meta.music);
+      let blur = blurOpts(opts);
+      if (blur && mode === "step") {
+        console.error("모션 블러는 seek 모드만 — step 모드는 뒤로 못 가서 끈다");
+        blur = null;
+      }
+      const songFrom = opts["music-from"] !== undefined ? num(opts["music-from"], 0) : opts.music ? 0 : musicFrom(resolve(dir));
+
+      console.error(
+        `${meta.width}x${meta.height} ${fps}fps ${mode} 모드 · 프레임 ${startF}..${endF - 1} (${frames}장) · 탭 ${chunks.length}` +
+          (music ? ` · 곡 ${music}${songFrom ? ` (${songFrom}초부터)` : ""}` : "") +
+          (blur ? ` · 모션 블러 ${blur.count}장·셔터 ${blur.shutter}°` : ""),
+      );
+      mkdirSync(tmp, { recursive: true });
+      if (format === "png") mkdirSync(out, { recursive: true });
+
+      let done = 0;
+      const progress = setInterval(() => {
+        const sec = (Date.now() - started) / 1000;
+        console.error(`  ${done}/${frames} (${((done / frames) * 100).toFixed(0)}%) ${(done / sec).toFixed(1)} 장/초`);
+      }, 5000);
+
+      const segFiles: string[] = [];
+      const usedTabs: Tab[] = [];
+      try {
+        await Promise.all(
+          chunks.map(async (c) => {
+            const tab: Tab = c.index === 0 ? s.first : await s.tab();
+            usedTabs.push(tab);
+            const seg = join(tmp, `seg-${String(c.index).padStart(2, "0")}${ext}`);
+            segFiles[c.index] = seg;
+            const raw = blur ? { width: meta.width, height: meta.height } : undefined;
+            const enc = format === "png" ? null : encoder(seg, fps, format, opts.crf ? num(opts.crf, 16) : undefined, raw);
+            for (let f = c.start; f < c.end; f++) {
+              let frame: Buffer;
+              if (blur) {
+                const img = await captureBlurred(tab, s.info, f / fps, blur);
+                frame = enc ? img.data : rgbaToPng(img);
+              } else {
+                await tab.seek(f / fps);
+                frame = await tab.capture();
+              }
+              if (enc) await enc.write(frame);
+              else writeFileSync(join(out, `${String(f).padStart(6, "0")}.png`), frame);
+              done++;
+            }
+            await enc?.end();
+          }),
+        );
+      } finally {
+        clearInterval(progress);
+      }
+
+      if (format !== "png") {
+        const list = join(tmp, "list.txt");
+        writeFileSync(list, segFiles.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+        await concat({ list, out, format, music, from: songFrom + startF / fps, dur: frames / fps });
+      }
+      const sec = (Date.now() - started) / 1000;
+      const report = {
+        out,
+        meta,
+        mode,
+        from: startF / fps,
+        to: endF / fps,
+        frames,
+        tabs: chunks.length,
+        format,
+        motionBlur: blur,
+        captions: captions ?? null,
+        music: music ?? null,
+        seconds: Math.round(sec * 10) / 10,
+        markers: s.info.markers,
+        events: await collectEvents(usedTabs),
+      };
+      const reportFile = format === "png" ? join(out, "render.json") : out.replace(/\.[^.]+$/, ".json");
+      writeFileSync(reportFile, JSON.stringify(report, null, 1));
+      console.error(`${frames}장 ${sec.toFixed(1)}초 (${(frames / sec).toFixed(1)} 장/초) · 보고서 ${reportFile}`);
+      console.log(out);
+      return 0;
+    } finally {
+      await s.close();
+      if (existsSync(tmp) && !opts["keep-tmp"]) rmSync(tmp, { recursive: true, force: true });
+      release();
+    }
+  },
+};
+export default cmd;

package/packages/cli/src/commands/setup.ts

@@ -0,0 +1,63 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { fileURLToPath } from "node:url";
+import { beatsVenv, checks, playwrightCli, report, requirements, venvPython } from "../deps.ts";
+import { type Command, parseFlags } from "../command.ts";
+import { setupLyrics } from "./lyrics.ts";
+
+function step(label: string, cmd: string, args: string[]): boolean {
+  console.log(`\n${label}: ${cmd} ${args.join(" ")}`);
+  const r = spawnSync(cmd, args, { stdio: "inherit" });
+  if (r.status === 0) return true;
+  console.error(`${label} 실패(${r.error?.message ?? `종료 ${r.status}`})`);
+  return false;
+}
+
+function chrome(): boolean {
+  // 리눅스 root 면 크롬이 쓰는 시스템 라이브러리까지 — 아니면 sudo 가 필요해 명령만 알린다
+  const withDeps = platform() === "linux" && process.getuid?.() === 0;
+  const ok = step("크롬", process.execPath, [playwrightCli(), "install", ...(withDeps ? ["--with-deps"] : []), "chromium"]);
+  if (platform() === "linux" && !withDeps) console.log(`  라이브러리가 없어 크롬이 안 뜨면: sudo ${process.execPath} ${playwrightCli()} install-deps chromium`);
+  return ok;
+}
+
+function beats(): boolean {
+  if (process.env.KF_PYTHON) return step("librosa", process.env.KF_PYTHON, ["-m", "pip", "install", "-r", requirements]);
+  if (!existsSync(beatsVenv) && !step("파이썬 venv", "python3", ["-m", "venv", beatsVenv])) return false;
+  return step("librosa", venvPython(beatsVenv), ["-m", "pip", "install", "-r", requirements]);
+}
+
+// 고정 커밋을 받아 묶고 한글 글꼴을 받는다(비동기라 따로 돌린다). 일본어 가사는 node packages/jizura/src/install.ts --lang ko,ja
+const jizura = () => step("JIZURA", process.execPath, [fileURLToPath(import.meta.resolve("@kasaframe/jizura/install")), "--lang", "ko"]);
+
+// 이름 하나 = 깔 것 하나. 이름 없이 부르면 DEFAULT 만
+const STEPS: Record<string, { what: string; run: () => boolean }> = {
+  chrome: { what: "Playwright 크롬(chromium) — 렌더·검사", run: chrome },
+  beats: { what: `librosa(${beatsVenv}) — 곡 분석 kf beats`, run: beats },
+  jizura: { what: "JIZURA 가사 층 엔진(고정 커밋)·한글 글꼴 60MB(~/.cache/kasaframe/jizura) — 뮤비 가사 키네틱", run: jizura },
+  lyrics: { what: "demucs·stable-ts(~/.cache/kasaframe/py/lyrics, 2GB 안팎) — kf lyrics align", run: setupLyrics },
+};
+const DEFAULT = ["chrome", "beats"];
+
+const cmd: Command = {
+  summary: "바깥 도구 깔기 — Playwright 크롬·librosa. ffmpeg 는 시스템 패키지라 깔 명령만 알린다",
+  usage: `kf setup [이름…]   이름 없이: ${DEFAULT.join(" ")}
+${Object.entries(STEPS).map(([k, s]) => `  ${k.padEnd(8)} ${s.what}`).join("\n")}
+  kf beats 는 KF_PYTHON 이 없으면 위 venv 를 먼저 쓴다. 끝에 kf doctor 와 같은 표를 찍는다`,
+  async run(argv) {
+    const { args } = parseFlags(argv);
+    const names = args.length ? args : DEFAULT;
+    const unknown = names.filter((n) => !STEPS[n]);
+    if (unknown.length) {
+      console.error(`kf setup: 모르는 이름 ${unknown.join(" ")} — 있는 것: ${Object.keys(STEPS).join(" ")}`);
+      return 2;
+    }
+    const failed = names.filter((n) => !STEPS[n].run());
+    console.log("");
+    const list = await checks();
+    report(list);
+    return failed.length || list.some((c) => c.required && !c.ok) ? 1 : 0;
+  },
+};
+export default cmd;

package/packages/cli/src/commands/sheet.ts

@@ -0,0 +1,114 @@
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+import { openSession, type PageInfo } from "../browser.ts";
+import { fmtTime, outPath } from "../out.ts";
+import { acquireRenderLock } from "../lock.ts";
+
+interface Shot {
+  t: number;
+  label: string;
+}
+
+function scenesOf(info: PageInfo): { label: string; from: number; to: number }[] {
+  const starts = info.markers.filter((m) => m.kind === "scene").sort((a, b) => a.t - b.t);
+  return starts.map((m, i) => ({ label: m.label, from: m.t, to: starts[i + 1]?.t ?? info.meta.duration }));
+}
+
+function pickTimes(info: PageInfo, opts: Record<string, string | boolean | undefined>): Shot[] {
+  const { duration, fps } = info.meta;
+  const last = (Math.round(duration * fps) - 1) / fps;
+  const scenes = scenesOf(info);
+  const sceneAt = (t: number) => scenes.findLast((s) => s.from <= t)?.label ?? "";
+  if (typeof opts.at === "string") {
+    return opts.at.split(",").map((x) => {
+      const t = Math.min(last, Number(x));
+      return { t, label: sceneAt(t) };
+    });
+  }
+  const per = num(opts["per-scene"], 1);
+  if (scenes.length && opts.count === undefined) {
+    return scenes.flatMap((s) =>
+      Array.from({ length: per }, (_, i) => {
+        const t = Math.min(last, s.from + ((s.to - s.from) * (i + 1)) / (per + 1));
+        return { t: Math.round(t * fps) / fps, label: s.label };
+      }),
+    );
+  }
+  const n = num(opts.count, 12);
+  return Array.from({ length: n }, (_, i) => {
+    const t = Math.round(((last * (i + 0.5)) / n) * fps) / fps;
+    return { t, label: sceneAt(t) };
+  });
+}
+
+function sheetHtml(shots: { png: Buffer; t: number; label: string }[], cols: number, w: number, h: number): string {
+  const cells = shots
+    .map(
+      (s) =>
+        `<figure><img src="data:image/png;base64,${s.png.toString("base64")}"><figcaption><b>${fmtTime(s.t)}s</b>${s.label ? ` · ${s.label}` : ""}</figcaption></figure>`,
+    )
+    .join("");
+  return `<!doctype html><meta charset="utf-8"><style>
+    body { margin: 0; padding: 16px; background: #111; font: 15px/1.3 -apple-system, "Apple SD Gothic Neo", sans-serif; color: #ddd; }
+    main { display: grid; grid-template-columns: repeat(${cols}, ${w}px); gap: 12px; }
+    figure { margin: 0; }
+    img { display: block; width: ${w}px; height: ${h}px; outline: 1px solid #333; }
+    figcaption { padding: 4px 2px 0; }
+  </style><main>${cells}</main>`;
+}
+
+const cmd: Command = {
+  summary: "장면 모음 한 장(PNG) — 그림 보는 모델에 넘길 것",
+  usage: `kf sheet <폴더> [--out 파일.png] [--per-scene 1] [--count N | --at 1,5.5,12] [--cols 4] [--width 480]
+  기본은 장면마다 가운데 한 장. 장면 표시가 없으면 고르게 12 장.
+  --per-scene  장면마다 몇 장(장면을 n+1 등분한 자리)
+  --count      장면과 상관없이 고르게 N 장
+  --at         찍을 시각(초)을 쉼표로
+  --lock-wait  다른 렌더가 잠금을 쥐고 있을 때 기다릴 초(기본 900)
+  --no-lock    잠금 없이(한두 장 시험용)`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const dir = args[0];
+    if (!dir) {
+      console.error("kf sheet: 폴더를 줘라 — kf sheet <폴더>");
+      return 2;
+    }
+    // 여러 장 찍는 무거운 일이라 render·check 와 같이 레포 전체에서 하나씩
+    const release = opts["no-lock"] ? () => {} : await acquireRenderLock(resolve(dir), num(opts["lock-wait"], 900));
+    try {
+      return await shoot(dir, opts);
+    } finally {
+      release();
+    }
+  },
+};
+export default cmd;
+
+async function shoot(dir: string, opts: Record<string, string | boolean | undefined>): Promise<number> {
+  const s = await openSession(dir);
+  try {
+    const shots = pickTimes(s.info, opts);
+    // step 모드는 뒤로 못 가므로 시각 순서로 찍는다.
+    const order = [...shots].sort((a, b) => a.t - b.t);
+    const taken: { png: Buffer; t: number; label: string }[] = [];
+    for (const shot of order) {
+      await s.first.seek(shot.t);
+      taken.push({ ...shot, png: await s.first.capture() });
+    }
+    const { width, height } = s.info.meta;
+    const w = num(opts.width, height > width ? 270 : 480);
+    const h = Math.round((w * height) / width);
+    const cols = num(opts.cols, height > width ? 6 : 4);
+    const page = await s.context.newPage();
+    await page.setViewportSize({ width: 32 + cols * w + (cols - 1) * 12, height: 400 });
+    await page.setContent(sheetHtml(taken, cols, w, h), { waitUntil: "load" });
+    const file = outPath(dir, opts.out, "sheet.png");
+    writeFileSync(file, await page.screenshot({ fullPage: true, type: "png" }));
+    console.log(file);
+    return 0;
+  } finally {
+    await s.close();
+  }
+}

package/packages/cli/src/commands/skill.ts

@@ -0,0 +1,43 @@
+import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type Command, parseFlags } from "../command.ts";
+
+const source = fileURLToPath(new URL("../../../../skills/kasaframe", import.meta.url));
+
+const cmd: Command = {
+  summary: "Claude Code 스킬 — 말로 「영상 만들어」 하면 kasaframe 으로 가게 ~/.claude/skills/kasaframe 에 링크",
+  usage: `kf skill install [--to <스킬 폴더>]   ~/.claude/skills/kasaframe → 레포 skills/kasaframe 링크(이미 있으면 덮지 않고 알린다)
+kf skill path                          스킬 원본 자리`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    if (args[0] === "path") {
+      console.log(source);
+      return 0;
+    }
+    if (args[0] !== "install") {
+      console.error("kf skill install | path — kf skill --help");
+      return 2;
+    }
+    const to = typeof opts.to === "string" ? opts.to : join(homedir(), ".claude", "skills", "kasaframe");
+    if (existsSync(to) || isLink(to)) {
+      const what = isLink(to) ? `링크(${readlinkSync(to)})` : "폴더";
+      console.error(`${to} 가 이미 있다 — ${what}. 덮지 않는다. 바꾸려면 지우고 다시 kf skill install`);
+      return isLink(to) && readlinkSync(to) === source ? 0 : 1;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    symlinkSync(source, to);
+    console.log(`${to} → ${source}\n새 Claude Code 세션부터 「영상 만들어」 같은 말에 kasaframe 스킬이 뜬다.`);
+    return 0;
+  },
+};
+
+function isLink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+export default cmd;