kasaframe 0.0.0-stage → 0.1.3

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

@@ -0,0 +1,250 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, 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, projectBlur, rgbaToPng } from "../blur.ts";
+import { outPath } from "../out.ts";
+import { cachedSegment, collectEvents, type KeyOpts, type MotionEvent, pruneSegments, renderSegments, sceneKeys, sceneSpans, type SegmentReport, type SegmentWork, variantOf } from "../segments.ts";
+import { mixAudio, mixSettings } from "../mix.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;
+  }
+}
+
+// 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] [--scenes a,b] [--from 초 --to 초] [--tabs 3] [--prores | --png] [--music 곡 | --no-music] [--captions on|off|fit [--suffix]]
+  --out       기본 <폴더>/out/render.mp4 (--prores 면 .mov, --png 면 폴더)
+  seek 모드는 장면 조각으로 굽는다 — 장면마다 out/segments/<장면>-<해시>.mp4(해시: 그 장면이 실제로 불러온 모듈·kf.json 그 장면 칸·
+              자산·자막 줄·굽기 설정, 이음매는 앞뒤 장면까지). 해시가 같은 조각은 다시 찍지 않고 이어 붙인 뒤 곡·목소리를 전체로 얹는다
+  --scenes a,b  그 장면 조각만 굽고 잇지 않는다(조각 경로를 찍는다). 다음 kf render 가 그 조각을 그대로 쓴다
+  --fresh     조각 캐시를 안 보고 다시 찍는다 · --no-segments 조각 없이 탭 몫으로 나눠 한 번에(예전 길)
+  --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 배 느리다.
+              안 주면 kf.json 의 render.motionBlur(쇼츠·홍보 틀은 켜 둔다), 0 이면 끈다
+  --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, projectBlur(resolve(dir)));
+      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));
+
+      // seek 모드 통짜 굽기는 장면 조각으로 — 바뀐 장면만 다시 찍고 잇는다. --no-segments 면 예전처럼 탭 몫으로 나눠 한 번에
+      const segmented = !opts["no-segments"] && mode === "seek" && format !== "png" && opts.from === undefined && opts.to === undefined;
+      const only = typeof opts.scenes === "string" ? opts.scenes.split(",").map((x) => x.trim()).filter(Boolean) : null;
+      if (only && !segmented) throw new Error("--scenes 는 seek 모드 영상 굽기에서만 — --from/--to·--png·--no-segments·step 모드와 같이 못 쓴다");
+      const crf = opts.crf ? num(opts.crf, 16) : undefined;
+
+      console.error(
+        `${meta.width}x${meta.height} ${fps}fps ${mode} 모드 · 프레임 ${startF}..${endF - 1} (${frames}장) · 탭 ${segmented ? tabs : 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;
+      let todo = frames;
+      const progress = setInterval(() => {
+        const sec = (Date.now() - started) / 1000;
+        console.error(`  ${done}/${todo} (${((done / Math.max(1, todo)) * 100).toFixed(0)}%) ${(done / sec).toFixed(1)} 장/초`);
+      }, 5000);
+
+      let segFiles: string[] = [];
+      let events: MotionEvent[] = [];
+      let segments: { rendered: string[]; reused: string[] } | undefined;
+      try {
+        if (segmented) {
+          const root = s.project.dir;
+          const keyOpts: KeyOpts = { width: meta.width, height: meta.height, fps, format, crf, blur, captions, browser: s.browser.version() };
+          const keys = sceneKeys(s.project.server, root, keyOpts);
+          const spans = sceneSpans(JSON.parse(readFileSync(join(root, "kf.json"), "utf8")).scenes, fps, total);
+          const missing = only?.filter((id) => !spans.some((sp) => sp.id === id)) ?? [];
+          if (missing.length) throw new Error(`kf.json 에 없는 장면: ${missing.join(", ")}`);
+          const reused = new Map<string, SegmentReport>();
+          const work: SegmentWork[] = [];
+          for (const span of only ? spans.filter((sp) => only.includes(sp.id)) : spans) {
+            const { key, inputs } = keys.get(span.id)!;
+            const hit = opts.fresh ? null : cachedSegment(root, span.id, key, ext);
+            if (!hit) work.push({ span, key, inputs });
+            else {
+              reused.set(span.id, hit);
+              console.error(`장면 ${span.id}: 그대로 — ${basename(hit.file)}`);
+            }
+          }
+          todo = work.reduce((n, w) => n + w.span.end - w.span.start, 0);
+          console.error(`조각 ${work.length + reused.size} — 다시 찍기 ${work.length}(${todo}장) · 그대로 ${reused.size}`);
+          const made = work.length ? await renderSegments({ session: s, root, work, tabs, format, ext, crf, blur, tmp, onFrame: () => done++ }) : [];
+          const all = new Map<string, SegmentReport>([...reused, ...made.map((m) => [m.id, m] as const)]);
+          if (only) {
+            for (const id of only) console.log(all.get(id)!.file);
+            console.error(`조각만 ${((Date.now() - started) / 1000).toFixed(1)}초 — 잇기는 kf render ${dir}`);
+            return 0;
+          }
+          segFiles = spans.map((sp) => all.get(sp.id)!.file);
+          events = spans.flatMap((sp) => all.get(sp.id)!.events);
+          segments = { rendered: made.map((m) => m.id), reused: [...reused.keys()] };
+          pruneSegments(root, variantOf(keyOpts), Object.fromEntries(spans.map((sp) => [sp.id, keys.get(sp.id)!.key])));
+        } else {
+          const usedTabs: Tab[] = [];
+          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, crf, 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();
+            }),
+          );
+          events = await collectEvents(usedTabs);
+        }
+      } finally {
+        clearInterval(progress);
+      }
+
+      if (format !== "png") {
+        const list = join(tmp, "list.txt");
+        writeFileSync(list, segFiles.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+        // kf.json 에 audio(섞기 값)가 있으면 내레이션·곡을 섞은 소리를 얹는다(덕킹·끝 페이드·LUFS) — 없으면 곡만
+        const mix = opts["no-music"] ? null : mixSettings(resolve(dir));
+        const mixed = mix && (mix.voice || music)
+          ? await mixAudio({ voice: mix.voice, music, musicFrom: songFrom }, { audio: mix.audio, from: startF / fps, dur: frames / fps, total: meta.duration, out: join(tmp, "mix.wav") })
+          : undefined;
+        await concat({ list, out, format, music: mixed ?? music, from: mixed ? 0 : songFrom + startF / fps, dur: frames / fps });
+        if (mixed) console.error(`소리: ${mix!.voice ? "내레이션" : ""}${mix!.voice && music ? " + " : ""}${music ? "곡" : ""} → ${mix!.audio.lufs} LUFS`);
+      }
+      const sec = (Date.now() - started) / 1000;
+      const report = {
+        out,
+        meta,
+        mode,
+        from: startF / fps,
+        to: endF / fps,
+        frames,
+        tabs: segmented ? tabs : chunks.length,
+        format,
+        motionBlur: blur,
+        captions: captions ?? null,
+        music: music ?? null,
+        seconds: Math.round(sec * 10) / 10,
+        ...(segments ? { segments } : {}),
+        markers: s.info.markers,
+        events,
+      };
+      const reportFile = format === "png" ? join(out, "render.json") : out.replace(/\.[^.]+$/, ".json");
+      writeFileSync(reportFile, JSON.stringify(report, null, 1));
+      console.error(`${todo}장 ${sec.toFixed(1)}초 (${(todo / sec).toFixed(1)} 장/초)${segments ? ` · 조각 다시 ${segments.rendered.length}·그대로 ${segments.reused.length}` : ""} · 보고서 ${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/series.ts

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { listSeries, loadSeries, type Purpose, type Series, seriesDir, writeSeries } from "@kasaframe/plan";
+import { loadTheme } from "@kasaframe/themes";
+import type { Command } from "../command.ts";
+import { parseFlags } from "../command.ts";
+
+const USAGE = `kf series list
+kf series show <id>
+kf series new <id> --label "OG 쇼츠" --match "OG 쇼츠,OG shorts" --purpose shorts [--theme og-measure] [--voice gemini:Charon]
+              [--mood deep | --music music/x.mp3] [--captions on|off|none] [--duration 45-60] [--end-title 이름] [--end-line 한 줄]
+              [--answers image=og-gpt-image-2.5-sunburst,video=none] [--from <잘 나온 프로젝트 폴더>] [--force]
+
+시리즈 묶음(series/<id>.json, KF_SERIES_DIR 로 바꿈) — 요청이 match 의 말을 짚으면 kf make 가 묻지 않고 이 묶음대로 간다:
+용도·테마·목소리·곡(파일이면 늘 그 곡, 분위기면 곡 모음의 같은 곡)·자막·길이·끝 카드·생성 질문 답. 용도 규칙은 그 용도 틀이 정한다.
+--from 은 그 프로젝트의 plan.json·kf.json(용도·테마·목소리·곡·자막·길이·이름·고른 답)을 묶음으로 옮긴다 — 플래그가 이긴다.`;
+
+function range(v: string): { min: number; max: number; default: number } {
+  const m = /^(\d+(?:\.\d+)?)(?:-(\d+(?:\.\d+)?))?$/.exec(v);
+  if (!m) throw new Error(`--duration 은 45 또는 45-60 — ${v}`);
+  const min = Number(m[1]);
+  const max = Number(m[2] ?? m[1]);
+  return { min, max, default: min };
+}
+
+function fromProject(dir: string): Partial<Series> {
+  const plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const kf = existsSync(join(dir, "kf.json")) ? JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) : {};
+  const answers: Record<string, string> = Object.fromEntries(Object.entries(plan.answers ?? {}).filter(([k, v]) => k !== "voice" && k !== "music" && typeof v === "string") as [string, string][]);
+  return {
+    purpose: plan.purpose,
+    ...(plan.theme ? { theme: plan.theme } : { style: plan.style }),
+    ...(plan.voice ? { voice: plan.voice } : {}),
+    ...(plan.mood ? { music: { mood: plan.mood } } : {}),
+    captions: kf.captions ?? plan.captions,
+    duration: { min: plan.duration, max: plan.duration, default: plan.duration },
+    end: { title: plan.title },
+    ...(Object.keys(answers).length ? { answers } : {}),
+  };
+}
+
+function show(s: Series): string {
+  const warn: string[] = [];
+  if (s.theme) {
+    try {
+      const t = loadTheme(s.theme);
+      if (t.status !== "approved") warn.push(`테마 ${s.theme} 는 ${t.status} — 승인 전`);
+      if (!t.purposes.includes(s.purpose)) warn.push(`테마 ${s.theme} 의 용도에 ${s.purpose} 가 없다`);
+    } catch (e) {
+      warn.push(`테마 ${s.theme}: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  return [JSON.stringify(s, null, 2), ...warn.map((w) => `주의: ${w}`)].join("\n");
+}
+
+const cmd: Command = {
+  summary: "시리즈 묶음 — 짚으면 묻지 않고 매번 같은 용도·테마·목소리·곡·자막·길이·끝 카드",
+  usage: USAGE,
+  async run(argv) {
+    const [sub, ...rest] = argv;
+    const { args, opts } = parseFlags(rest);
+    const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+    if (sub === "list") {
+      const all = listSeries();
+      if (!all.length) console.log(`시리즈 없음 — kf series new 로 (${seriesDir()})`);
+      for (const s of all) console.log(`${s.id.padEnd(16)} ${s.label} · ${s.purpose}${s.theme ? ` · 테마 ${s.theme}` : ""}${s.voice ? ` · ${s.voice}` : ""} — 「${s.match.join("」「")}」`);
+      return 0;
+    }
+    if (sub === "show" && args[0]) {
+      console.log(show(loadSeries(args[0])));
+      return 0;
+    }
+    if (sub === "new" && args[0]) {
+      const id = args[0];
+      if (existsSync(join(seriesDir(), `${id}.json`)) && !opts.force) {
+        console.error(`kf series new: ${id} 가 이미 있다 — 덮으려면 --force`);
+        return 2;
+      }
+      const base: Partial<Series> = str("from") ? fromProject(resolve(str("from")!)) : {};
+      const answers = str("answers") ? Object.fromEntries(str("answers")!.split(",").map((kv) => kv.split("=").map((x) => x.trim()) as [string, string])) : undefined;
+      const s: Series = {
+        ...base,
+        id,
+        label: str("label") ?? base.label ?? id,
+        match: str("match") ? str("match")!.split(",").map((x) => x.trim()).filter(Boolean) : (base.match ?? []),
+        purpose: (str("purpose") ?? base.purpose) as Purpose,
+        ...(str("theme") ? { theme: str("theme") } : {}),
+        ...(str("voice") ? { voice: str("voice") } : {}),
+        ...(str("music") ? { music: { file: str("music") } } : str("mood") ? { music: { mood: str("mood") } } : {}),
+        ...(str("captions") ? { captions: str("captions") as Series["captions"] } : {}),
+        ...(str("duration") ? { duration: range(str("duration")!) } : {}),
+        ...(str("end-title") || str("end-line") ? { end: { ...base.end, ...(str("end-title") ? { title: str("end-title") } : {}), ...(str("end-line") ? { line: str("end-line") } : {}) } } : {}),
+        ...(answers ? { answers: { ...base.answers, ...answers } } : {}),
+      };
+      try {
+        // 사람이 열어 볼 파일이라 이름·짚는 말·용도를 맨 위에
+        const { id: _, label, match, purpose, ...rest } = s;
+        const file = writeSeries({ id, label, match, purpose, ...rest });
+        console.log(`${relative(process.cwd(), file) || file}\n${show(s)}`);
+        return 0;
+      } catch (e) {
+        console.error(`kf series new: ${e instanceof Error ? e.message : e}`);
+        return 2;
+      }
+    }
+    console.error(USAGE);
+    return 2;
+  },
+};
+export default cmd;

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

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { keyFile } from "@kasaframe/gen";
+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 가사 층의 나머지 한국어 글꼴 17MB(~/.cache/kasaframe/jizura) — 엔진·자주 쓰는 글꼴은 실려 있고 이것도 처음 쓸 때 받는다, 오프라인으로 구울 기계면 미리", run: jizura },
+  lyrics: { what: "demucs·stable-ts(~/.cache/kasaframe/py/lyrics, 2GB 안팎) — kf lyrics align", run: setupLyrics },
+};
+const DEFAULT = ["chrome", "beats"];
+
+// 키는 화면·셸 기록에 남지 않게 — 터미널이면 입력을 가리고, 아니면 표준 입력 한 줄로 받는다. 값은 찍지 않는다
+function readSecret(prompt: string): Promise<string> {
+  return new Promise((done) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: !!process.stdin.isTTY });
+    if (process.stdin.isTTY) {
+      process.stderr.write(prompt);
+      (rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput = () => {};
+    }
+    rl.once("line", (line) => {
+      rl.close();
+      if (process.stdin.isTTY) process.stderr.write("\n");
+      done(line.trim());
+    });
+  });
+}
+
+async function key(name: string | undefined): Promise<number> {
+  if (!name || !/^[a-z0-9-]+$/.test(name)) {
+    console.error("kf setup key <이름> — opengateway · fal · gemini · minimax · ltx · elevenlabs · dashscope (kf doctor 「생성 능력」이 무엇이 없는지 알려 준다)");
+    return 2;
+  }
+  const value = await readSecret(`${name} 키(입력은 안 보인다): `);
+  if (!value) {
+    console.error("kf setup key: 빈 값 — 아무것도 쓰지 않았다");
+    return 2;
+  }
+  const file = keyFile(name);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${value}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+  console.log(`${file} 에 썼다(600). 확인: kf doctor`);
+  return 0;
+}
+
+const cmd: Command = {
+  summary: "바깥 도구 깔기 — Playwright 크롬·librosa. ffmpeg 는 시스템 패키지라 깔 명령만 알린다",
+  usage: `kf setup [이름…]   이름 없이: ${DEFAULT.join(" ")}
+kf setup key <이름>   생성 공급자 키를 숨겨 받아 ~/.config/kasaframe/keys/<이름>(600)에 — 값은 찍지 않는다
+${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);
+    if (args[0] === "key") return key(args[1]);
+    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;

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

@@ -0,0 +1,40 @@
+import { writeFileSync } from "node:fs";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+import { openSession } from "../browser.ts";
+import { fmtTime, outPath } from "../out.ts";
+import { blurOpts, captureBlurred, rgbaToPng } from "../blur.ts";
+
+const cmd: Command = {
+  summary: "한 시각을 PNG 한 장으로",
+  usage: `kf still <폴더> --t <초> [--out 파일.png]
+  --t       찍을 시각(초). --frame N 으로 프레임 번호를 줘도 된다
+  --out     기본 <폴더>/out/still-<t>.png
+  --motion-blur N --shutter 180  렌더와 같은 모션 블러(하위 프레임 N 장 평균)로 한 장
+step 모드 페이지는 0 초부터 그 시각까지 돌린 뒤 찍는다.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const dir = args[0];
+    if (!dir) {
+      console.error("kf still: 폴더를 줘라 — kf still <폴더> --t 12.3");
+      return 2;
+    }
+    const s = await openSession(dir);
+    try {
+      const { fps } = s.info.meta;
+      const t = opts.frame !== undefined ? num(opts.frame, 0) / fps : num(opts.t, 0);
+      const file = outPath(dir, opts.out, `still-${fmtTime(t)}.png`);
+      const blur = blurOpts(opts);
+      if (blur && s.info.mode === "seek") writeFileSync(file, rgbaToPng(await captureBlurred(s.first, s.info, t, blur)));
+      else {
+        await s.first.seek(t);
+        writeFileSync(file, await s.first.capture());
+      }
+      console.log(file);
+      return 0;
+    } finally {
+      await s.close();
+    }
+  },
+};
+export default cmd;