kasaframe 0.0.0-stage → 0.1.3

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

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { addToLibrary, byMood, genMusic, listLibrary, MOOD_PROMPT, MOOD_TAGS, musicDir, musicProviders } from "@kasaframe/gen";
+import { type Command, num, parseFlags } from "../command.ts";
+
+const cmd: Command = {
+  summary: "곡 모음 — 분위기 태그로 보기·넣기, 음악 생성(Lyria·Eleven Music)",
+  usage: `kf music list [--mood deep]
+kf music add <곡 파일> --mood deep,ambient --source <원본 주소> --license "<라이선스>" [--title 이름] [--genre 장르] [--bpm 70]
+kf music gen --mood deep --dur 45 [--provider lyria-3.5|elevenlabs-music|lyria-3-clip-preview] [--out 폴더] [--add]
+
+  곡 모음은 ${"KF_MUSIC_DIR"}(없으면 레포 music/). 곡마다 분위기·원본·라이선스는 그 폴더 tags.json, 사람용 표는 README.md.
+  분위기: ${Object.keys(MOOD_PROMPT).join(" · ")} — 틀(template.json mood)이 고른다. 원본·라이선스를 모르는 곡은 넣지 않는다.
+  gen 은 분위기·길이 칸(30·45·60·90·120…초)이 같으면 캐시에서 같은 곡을 0원으로 꺼낸다. --add 면 곡 모음에 태그와 함께 넣는다.`,
+  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" || !sub) {
+      const tracks = str("mood") ? byMood(str("mood")!) : listLibrary();
+      console.log(`곡 모음 ${musicDir()}${str("mood") ? ` — 분위기 ${str("mood")}` : ""}`);
+      for (const t of tracks) console.log(`  ${t.file.padEnd(34)} ${(t.mood.join("·") || "태그 없음").padEnd(32)} ${t.license ? t.license.slice(0, 60) : "라이선스 모름 — 고르는 데서 빠진다"}`);
+      if (!tracks.length) console.log("  (없음)");
+      console.log(`\n생성: ${musicProviders().map((p) => `${p.id}(${p.ready() ? "키 있음" : "키 없음"})`).join(" · ")}`);
+      return 0;
+    }
+
+    if (sub === "add") {
+      const src = args[0] ? resolve(args[0]) : undefined;
+      if (!src || !existsSync(src) || !str("mood") || !str("source") || !str("license")) {
+        console.error("kf music add: <곡 파일> --mood --source --license 가 필요하다");
+        return 2;
+      }
+      const t = addToLibrary(src, {
+        title: str("title") ?? basename(src).replace(/\.[^.]+$/, ""),
+        mood: str("mood")!.split(",").map((m) => m.trim()).filter(Boolean),
+        ...(str("genre") ? { genre: str("genre") } : {}),
+        ...(str("bpm") ? { bpm: num(opts.bpm, 0) } : {}),
+        source: str("source")!,
+        license: str("license")!,
+      });
+      readmeRow(t.file, t.title, t.mood, t.source, t.license);
+      console.log(t.path);
+      return 0;
+    }
+
+    if (sub === "gen") {
+      const mood = str("mood") ?? "deep";
+      const dur = num(opts.dur, 45);
+      const outDir = resolve(str("out") ?? ".");
+      const m = await genMusic(`${mood}-${dur}`, { mood, duration: dur }, { outDir, log: (l) => console.error(l) }, str("provider"));
+      console.error(`${m.provider} · ${m.seconds}초 · ${m.cached ? "캐시(0)" : `$${m.costUsd.toFixed(3)}`} · ${m.license}`);
+      if (opts.add) {
+        const file = `${mood}-${m.provider}-${Math.round(m.seconds)}s.${m.path.split(".").pop()}`;
+        const t = addToLibrary(m.path, { title: `${mood} ${Math.round(m.seconds)}초 (${m.provider} 생성)`, mood: [...new Set([mood, ...(MOOD_TAGS[mood] ?? []).slice(0, 3)])], source: `${m.provider} 생성(MOOD_PROMPT.${mood}, ${new Date().toISOString().slice(0, 10)})`, license: m.license }, musicDir(), file);
+        readmeRow(t.file, t.title, t.mood, t.source, t.license);
+        console.log(t.path);
+      } else console.log(m.path);
+      return 0;
+    }
+
+    console.error(this.usage);
+    return 2;
+  },
+};
+export default cmd;
+
+// README 표에 한 줄 — 같은 파일 줄이 있으면 두지 않는다. 표 끝(마지막 표 줄 다음)에 끼운다
+function readmeRow(file: string, title: string, mood: string[], source: string, license: string): void {
+  const readme = join(musicDir(), "README.md");
+  if (!existsSync(readme)) return;
+  const lines = readFileSync(readme, "utf8").split("\n");
+  if (lines.some((l) => l.startsWith(`| \`${file}\` |`))) return;
+  const last = lines.map((l, i) => (l.startsWith("| `") ? i : -1)).filter((i) => i >= 0).at(-1) ?? lines.length - 1;
+  lines.splice(last + 1, 0, `| \`${file}\` | ${title} | ${mood.join("·")} | ${source} · ${license} |`);
+  writeFileSync(readme, lines.join("\n"));
+}

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

@@ -0,0 +1,238 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cutVoice, DEFAULT_STYLE, genMusic, howToGet, layVoices, parseVoice, pickTts, speak, ttsProviders, type Speech } from "@kasaframe/gen";
+import { loadTemplate, parseDuration, type Template } from "@kasaframe/plan";
+import { type Command, parseFlags } from "../command.ts";
+import { jobLimit, pool } from "../pool.ts";
+
+const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+// 한 장면에 문장이 둘 넘으면 그 사이 숨
+const GAP = 0.35;
+const MIN_SCENE = 0.75;
+// 박이 이보다 멀면 붙이지 않는다(느린 곡의 마디 사이에서 장면이 늘어지지 않게)
+const SNAP_REACH = 0.8;
+
+const NARRATION_DEFAULT: NonNullable<Template["narration"]> = { on: true, lang: "ko", style: DEFAULT_STYLE, voice: "elevenlabs:George", voices: {}, lead: 0.25, tail: 0.5 };
+
+interface Line {
+  scene: string;
+  text: string;
+  from?: number;
+  to?: number;
+  words?: { text: string; from: number; to: number }[];
+}
+
+const cmd: Command = {
+  summary: "내레이션 먼저 — 장면별 문장을 읽혀 장면 길이를 목소리에 맞추고(곡이 있으면 박에), 자막 시각을 목소리 시각으로",
+  usage: `kf narrate <폴더> [--voice <엔진>:<목소리>|none] [--music <곡 파일>|gen:<공급자>|none]
+kf narrate --voices                       키가 있는 목소리 엔진·목소리 목록
+kf narrate --say "<글>" --voice gemini:Charon [--out x.wav]   한 문장만 읽혀 본다
+
+  captions.json([{"scene": "<장면 id>", "text": "그 장면에서 들릴 말"}])을 장면마다 읽힌다 → 장면 길이 = 앞 숨 + 말 + 뒤 숨(틀 narration.lead·tail).
+  곡을 주면(또는 plan.json 답) 곡을 깔고 kf beats 로 재서 장면 경계를 다음 박에 붙인다. gen:<공급자> 면 틀 분위기(mood)로 영상 길이에 맞춘 곡을 만든다.
+  요청 글에 길이(「45초」)가 있으면 목소리 빠르기를 0.9–1.1 안에서만 맞추고 남는 시간은 장면 뒤 숨으로 편다. 그 밖엔 빠르기를 건드리지 않는다.
+  결과: assets/voice/<장면>-<n>.wav · assets/voice/narration.wav(영상 길이 한 줄) · captions.json 의 낱말 시각 · kf.json 의 장면 시각·narration·audio(섞기 값).
+  kf render 가 narration·곡을 섞는다 — 곡은 말할 때 덕킹, 끝 페이드, 틀의 LUFS 로 정규화.
+  --voice·--music 을 안 주면 plan.json 의 voice·music(또는 answers)을, 그것도 없으면 틀이 엔진마다 박은 목소리를 쓴다.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+    if (opts.voices) return voices();
+    if (str("say")) return say(str("say")!, str("voice") ?? "gemini", str("out"));
+    const dir = args[0] ? resolve(args[0]) : undefined;
+    if (!dir || !existsSync(join(dir, "kf.json"))) {
+      console.error("kf narrate: kf.json 이 있는 프로젝트 폴더가 필요하다 — kf narrate --help");
+      return 2;
+    }
+    try {
+      return await narrate(dir, { voice: str("voice"), music: str("music") });
+    } catch (e) {
+      console.error(`kf narrate: ${e instanceof Error ? e.message : e}`);
+      return 1;
+    }
+  },
+};
+export default cmd;
+
+function voices(): number {
+  for (const p of ttsProviders()) {
+    const state = p.ready() ? "쓸 수 있음" : "키 없음";
+    console.log(`${p.id.padEnd(11)} ${p.label} · ${p.model} · ${state}${p.verified ? "" : " · 실호출 미검증"}${p.timestamps ? " · 낱말 시각 정확" : ""}`);
+    for (const v of p.voices) console.log(`  --voice ${`${p.id}:${v.id}`.padEnd(26)} ${v.label}`);
+  }
+  return 0;
+}
+
+async function say(text: string, voice: string, out?: string): Promise<number> {
+  const v = parseVoice(voice);
+  if (!v) return 2;
+  const dst = resolve(out ?? "say.wav");
+  const s = await speak("say", { text, voice: v.voice, lang: "ko", style: DEFAULT_STYLE }, { outDir: join(dst, ".."), log: (l) => console.error(l) }, v.engine);
+  await cutVoice(s.path, dst, { from: s.voiced.from, to: s.voiced.to });
+  console.error(`${s.engine} ${s.voice} · ${(s.voiced.to - s.voiced.from).toFixed(2)}초 · ${s.cached ? "캐시(0)" : `$${s.costUsd.toFixed(4)}`}`);
+  console.log(dst);
+  return 0;
+}
+
+const readJson = (p: string) => JSON.parse(readFileSync(p, "utf8"));
+const writeJson = (p: string, v: unknown) => writeFileSync(p, `${JSON.stringify(v, null, 2)}\n`);
+
+// 답 고르는 순서: 명령 줄 > plan.json 의 voice·answers > 묻기의 권장과 같은 것(로컬 Qwen3 주소가 있으면 그 목소리, 없으면 틀이 못 박은 목소리).
+// 다른 엔진·「자막만」으로 조용히 넘어가지 않는다
+function pickVoice(given: string | undefined, plan: Record<string, any>, n: Template["narration"]): string {
+  const v = given ?? plan.voice ?? plan.answers?.voice;
+  if (v) return v;
+  if (!n?.on) return "none";
+  return pickTts("local").ready() ? `local:${n.voices.local ?? pickTts("local").defaultVoice}` : n.voice;
+}
+
+export async function narrate(dir: string, o: { voice?: string; music?: string } = {}): Promise<number> {
+  const kfPath = join(dir, "kf.json");
+  const planPath = join(dir, "plan.json");
+  const kf = readJson(kfPath);
+  const plan = existsSync(planPath) ? readJson(planPath) : {};
+  const tpl = loadTemplate(kf.template);
+  const n = { ...NARRATION_DEFAULT, ...tpl.narration };
+  const fps: number = kf.fps;
+  const f = (x: number) => Math.round(x * fps) / fps;
+  const log = (l: string) => console.error(l);
+
+  // 1. 목소리 — 장면마다 문장을 읽힌다
+  const voice = pickVoice(o.voice, plan, tpl.narration);
+  const v = parseVoice(voice);
+  if (v && !pickTts(v.engine).ready()) {
+    console.error(`kf narrate: 목소리 ${voice} 의 엔진 ${v.engine} 을 이 기계에서 못 쓴다 — 고르고 다시:\n  키 넣기 — ${howToGet(pickTts(v.engine).keyName)}\n  다른 엔진: ${ttsProviders().filter((p) => p.ready()).map((p) => `--voice ${p.id}:${n.voices[p.id] ?? p.defaultVoice}`).join(" · ") || "(쓸 수 있는 엔진 없음)"}\n  목소리 빼기: --voice none(자막만)`);
+    return 3;
+  }
+  const capPath = join(dir, "captions.json");
+  const lines: Line[] = existsSync(capPath) ? readJson(capPath) : [];
+  if (v && !lines.length) throw new Error("captions.json 에 장면별 문장이 없다 — [{\"scene\": \"hook\", \"text\": \"...\"}] 로 먼저 쓴다");
+  const spoken = new Map<string, { line: Line; s: Speech }[]>();
+  let costUsd = 0;
+  if (v) {
+    mkdirSync(join(dir, "assets", "voice", "raw"), { recursive: true });
+    const count: Record<string, number> = {};
+    const todo = lines.filter((line) => line.text?.trim() && kf.scenes.some((s: { id: string }) => s.id === line.scene)).map((line) => ({ line, k: (count[line.scene] = (count[line.scene] ?? 0) + 1) }));
+    // 줄마다 따로 읽힌다 — 동시에 부르고 장면 차례대로 모은다
+    const said = await pool(todo, jobLimit(4), ({ line, k }) => speak(`${line.scene}-${k}`, { text: line.text.trim(), voice: v.voice, lang: n.lang, style: n.style }, { outDir: join(dir, "assets", "voice", "raw"), log }, v.engine));
+    for (const [i, { line }] of todo.entries()) {
+      const s = said[i];
+      if (!s.cached) costUsd += s.costUsd;
+      spoken.set(line.scene, [...(spoken.get(line.scene) ?? []), { line, s }]);
+    }
+  }
+  const talk = (id: string) => (spoken.get(id) ?? []).reduce((a, x, i) => a + (x.s.voiced.to - x.s.voiced.from) + (i ? GAP : 0), 0);
+  const leadOf = (s: { role: string }) => (s.role === "hook" ? Math.min(0.1, n.lead) : n.lead);
+
+  // 2. 빠르기 — 요청이 길이를 말했으면 그 길이에, 아니면 틀 상한을 넘을 때만. 늘 0.9–1.1 안
+  const voiceSec = kf.scenes.reduce((a: number, s: { id: string }) => a + talk(s.id), 0);
+  const restSec = kf.scenes.reduce((a: number, s: { id: string; role: string; dur: number }) => a + (spoken.has(s.id) ? leadOf(s) + n.tail : s.dur), 0);
+  const target = parseDuration(plan.request ?? "");
+  const clamp = (x: number) => Math.min(1.1, Math.max(0.9, x));
+  let tempo = 1;
+  if (voiceSec > 0) {
+    if (target !== undefined && target > restSec) tempo = clamp(voiceSec / (target - restSec));
+    else if (voiceSec + restSec > tpl.duration.max) tempo = clamp(voiceSec / Math.max(1, tpl.duration.max - restSec));
+    if (Math.abs(tempo - 1) < 0.02) tempo = 1;
+  }
+  const need = kf.scenes.map((s: { id: string; role: string; dur: number }) => (spoken.has(s.id) ? Math.max(MIN_SCENE, leadOf(s) + talk(s.id) / tempo + n.tail) : s.dur));
+  // 남는 시간은 말한 장면 뒤 숨으로 고르게(요청 길이가 있을 때만)
+  const short = target !== undefined ? target - need.reduce((a: number, b: number) => a + b, 0) : 0;
+  const voiced = kf.scenes.filter((s: { id: string }) => spoken.has(s.id)).length;
+  if (short > 0 && voiced) kf.scenes.forEach((s: { id: string }, i: number) => spoken.has(s.id) && (need[i] += short / voiced));
+  let total = need.reduce((a: number, b: number) => a + b, 0);
+
+  // 3. 곡 — 곡 모음 파일·생성·없음. 바뀌었으면 kf beats 로 다시 잰다
+  const music = o.music ?? plan.answers?.music ?? undefined;
+  if (music === "none") {
+    kf.music = null;
+    kf.beats = null;
+  } else if (music?.startsWith("gen:")) {
+    // 시리즈 묶음의 분위기가 틀 분위기를 덮는다
+    const m = await genMusic("score", { mood: plan.mood ?? tpl.mood ?? "deep", duration: total }, { outDir: join(dir, "assets", "music"), log }, music.slice(4));
+    if (!m.cached) costUsd += m.costUsd;
+    kf.music = `assets/music/${basename(m.path)}`;
+    log(`곡 ${m.provider} ${m.seconds}초 ${m.cached ? "캐시(0)" : `$${m.costUsd.toFixed(3)}`} — ${m.license}`);
+  } else if (music) {
+    const src = resolve(music);
+    if (!existsSync(src)) throw new Error(`곡이 없다: ${src}`);
+    mkdirSync(join(dir, "assets", "music"), { recursive: true });
+    const rel = `assets/music/${basename(src)}`;
+    if (resolve(dir, rel) !== src) copyFileSync(src, join(dir, rel));
+    kf.music = rel;
+  }
+  if (kf.music && (music !== undefined || !kf.beats || !existsSync(join(dir, kf.beats)))) {
+    const r = spawnSync(process.execPath, [kfBin, "beats", join(dir, kf.music), "--out", join(dir, "beats.json")], { stdio: ["ignore", "ignore", "inherit"] });
+    if (r.status !== 0) throw new Error("곡 분석(kf beats)이 실패했다");
+    kf.beats = "beats.json";
+  }
+
+  // 4. 경계 — 말이 끝난 뒤 다음 박에(곡이 있으면), 그다음 프레임에
+  const beats: number[] = kf.beats && existsSync(join(dir, kf.beats)) ? (readJson(join(dir, kf.beats)).beats ?? []) : [];
+  let t = 0;
+  for (const [i, s] of kf.scenes.entries()) {
+    s.from = +f(t).toFixed(4);
+    let end = t + need[i];
+    if (i < kf.scenes.length - 1) {
+      const next = beats.find((b) => b >= end - 0.02);
+      if (next !== undefined && next - end <= SNAP_REACH) end = next;
+    }
+    end = f(end);
+    s.dur = +(end - s.from).toFixed(4);
+    t = end;
+  }
+  total = f(t);
+  kf.duration = +total.toFixed(4);
+
+  // 5. 목소리 한 줄 — 조각을 장면 시각에 깔고, 자막에 낱말 시각을 영상 기준으로 적는다
+  const clips: { file: string; at: number }[] = [];
+  const outLines: Line[] = [];
+  for (const s of kf.scenes) {
+    let at = s.from + leadOf(s);
+    for (const [k, { line, s: sp }] of (spoken.get(s.id) ?? []).entries()) {
+      const file = join(dir, "assets", "voice", `${s.id}-${k + 1}.wav`);
+      await cutVoice(sp.path, file, { from: sp.voiced.from, to: sp.voiced.to, tempo });
+      clips.push({ file, at });
+      const words = sp.words.map((w) => ({ text: w.text, from: +(at + (w.from - sp.voiced.from) / tempo).toFixed(3), to: +(at + (w.to - sp.voiced.from) / tempo).toFixed(3) }));
+      const len = (sp.voiced.to - sp.voiced.from) / tempo;
+      outLines.push({ scene: s.id, text: line.text, from: +at.toFixed(3), to: +(at + len).toFixed(3), words });
+      at += len + GAP;
+    }
+  }
+  if (v) {
+    await layVoices(clips, total, join(dir, "assets", "voice", "narration.wav"));
+    // 목소리를 안 읽힌 줄(장면 id 가 없던 줄)도 버리지 않는다
+    for (const l of lines) if (!outLines.some((x) => x.scene === l.scene && x.text === l.text)) outLines.push({ scene: l.scene, text: l.text });
+    writeJson(capPath, outLines);
+    writeJson(join(dir, "assets", "voice", "narration.json"), {
+      voice,
+      engine: v.engine,
+      model: pickTts(v.engine).model,
+      license: pickTts(v.engine).license,
+      tempo,
+      clips: clips.map((c, i) => ({ file: basename(c.file), at: +c.at.toFixed(3), text: outLines[i]?.text })),
+    });
+  }
+  kf.narration = v ? "assets/voice/narration.wav" : null;
+  kf.voice = voice;
+  if (tpl.audio) kf.audio = tpl.audio;
+  writeJson(kfPath, kf);
+  if (existsSync(planPath)) {
+    plan.voice = voice;
+    plan.music = kf.music;
+    plan.duration = kf.duration;
+    for (const s of plan.scenes ?? []) {
+      const k = kf.scenes.find((x: { id: string }) => x.id === s.id);
+      if (k) Object.assign(s, { from: k.from, dur: k.dur });
+    }
+    writeJson(planPath, plan);
+  }
+
+  console.log(`${dir} — 목소리 ${voice}${tempo !== 1 ? ` · 빠르기 ${tempo.toFixed(3)}` : ""} · 곡 ${kf.music ?? "없음"}${beats.length ? "(박에 붙임)" : ""} · ${kf.duration}초 · 이번에 쓴 돈 $${costUsd.toFixed(4)}`);
+  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)} ${spoken.has(s.id) ? `말 ${(talk(s.id) / tempo).toFixed(2)}초` : "말 없음"}`);
+  if (target !== undefined && Math.abs(kf.duration - target) > 2) console.log(`  · 요청 ${target}초와 ${(kf.duration - target).toFixed(1)}초 차이 — 빠르기는 0.9–1.1 까지만 바꾼다. 대본을 ${kf.duration > target ? "줄이면" : "늘리면"} 맞는다`);
+  else if (target === undefined && kf.duration > tpl.duration.max) console.log(`  · 틀 상한 ${tpl.duration.max}초를 넘는다 — 대본을 줄인다`);
+  return 0;
+}

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

@@ -0,0 +1,185 @@
+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 { bundleFor, dressSeed, NO_DRESS, pickDress } from "@kasaframe/motion/menu";
+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 후보 셋 중 첫째) · none(프리셋만) — 고르면 그 테마 style 을 쓴다
+  --series   시리즈 묶음 id · none. 안 주면 요청 글이 짚은 시리즈
+  --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"),
+          series: str("series"),
+        });
+    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 dress = tpl.moves ? pickDress(dressSeed(plan.request || plan.title, plan.purpose, plan.theme ?? plan.style), plan.scenes, bundleFor(tpl.moves, plan.theme ?? undefined)) : plan.scenes.map(() => ({ ...NO_DRESS }));
+
+    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,
+      ...(tpl.render ? { render: tpl.render } : {}),
+      safeArea,
+      text: tpl.text,
+      scenes: plan.scenes.map((s, i) => ({ id: s.id, from: s.from, dur: s.dur, file: `scenes/${s.id}.ts`, role: s.role, idea: s.idea, assets: s.assets, ...(s.role === "seam" || !tpl.moves ? {} : { dress: dress[i] }) })),
+    };
+
+    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", ...dress[i] }));
+    }
+
+    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" && !plan.theme) 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}${s.dress ? ` [${s.dress.bg}·${s.dress.text}${s.dress.wipeOut !== "none" ? `→${s.dress.wipeOut}` : ""}]` : ""}`);
+    if (tpl.render?.motionBlur) console.log(`  굽기: 모션 블러 ${tpl.render.motionBlur}장·셔터 ${tpl.render.shutter ?? 180}° (kf.json render — 끄려면 kf render --motion-blur 0)`);
+    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;