kasaframe 0.1.1 → 0.1.4

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

@@ -2,7 +2,8 @@ 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 { bundleFor, dressSeed, NO_DRESS, pickDress } from "@kasaframe/motion/menu";
+import { themeStyle, worldOf } 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";
 
@@ -16,7 +17,8 @@ kf new <폴더> --request "요청 글" [--music 곡.mp3]   용도를 요청 글
 kf new <폴더> --plan plan.json                        kf make 가 세운 계획 그대로
 
   용도: ${PURPOSES.join(" · ")}
-  --theme    테마 id(themes/<id>, approved·review) 또는 auto(내용에 맞는 approved 후보 셋 중 첫째) — 고르면 그 테마 style 을 쓴다
+  --theme    테마 id(themes/<id>, approved·review) · auto(내용에 맞는 approved 후보 셋 중 첫째) · none(프리셋만) — 고르면 그 테마 style 을 쓴다
+  --series   시리즈 묶음 id · none. 안 주면 요청 글이 짚은 시리즈
   --force    비어 있지 않은 폴더에도 쓴다(있는 장면 파일은 그대로 둔다)
   --preview  다 만들고 kf preview 를 띄운다
 
@@ -82,6 +84,7 @@ kf new <폴더> --plan plan.json                        kf make 가 세운 계
           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) {
@@ -111,6 +114,10 @@ kf new <폴더> --plan plan.json                        kf make 가 세운 계
     // 틀의 움직임 규칙이 프리셋을 이긴다 — 쇼츠에 박 펄스가 켜진 프리셋을 골라도 쇼츠 규칙대로
     style.motion = { ...style.motion, ...tpl.motion };
 
+    // 장면마다 연출 수(바탕·글·경계 덮기) — 용도 틀·테마 묶음에서 요청 글을 씨앗으로 고른다. 같은 요청이면 같은 수가 걸린다
+    // 틀에 묶음이 없으면(뮤비 — 가사 층이 화면을 맡는다) 무대 기본 그대로
+    const dress = tpl.moves ? pickDress(dressSeed(plan.request || plan.title, plan.purpose, worldOf(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 = {
@@ -125,9 +132,10 @@ kf new <폴더> --plan plan.json                        kf make 가 세운 계
       music,
       beats: beats ? "beats.json" : null,
       captions: plan.captions,
+      ...(tpl.render ? { render: tpl.render } : {}),
       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 })),
+      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);
@@ -152,15 +160,16 @@ kf new <폴더> --plan plan.json                        kf make 가 세운 계
       }
       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" }));
+      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") 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}`);
+    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}`);

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

@@ -1,12 +1,14 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { extname, join, resolve } from "node:path";
+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, rgbaToPng } from "../blur.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;
 
@@ -50,29 +52,6 @@ function musicFrom(dir: string): number {
   }
 }
 
-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;
@@ -82,14 +61,19 @@ function withSuffix(p: string, suffix: string): string {
 
 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]]
+  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 면 폴더)
-  --from/--to 구간만 굽는다. 곡도 그 구간만 잘라 얹는다
+  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 배 느리다
+  --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 은 장면을 띠 위로 줄여 올린다(픽셀을 박아 둔 장면용)
@@ -127,15 +111,21 @@ const cmd: Command = {
       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);
+      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}장) · 탭 ${chunks.length}` +
+        `${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}°` : ""),
       );
@@ -143,38 +133,75 @@ const cmd: Command = {
       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}/${frames} (${((done / frames) * 100).toFixed(0)}%) ${(done / sec).toFixed(1)} 장/초`);
+        console.error(`  ${done}/${todo} (${((done / Math.max(1, todo)) * 100).toFixed(0)}%) ${(done / sec).toFixed(1)} 장/초`);
       }, 5000);
 
-      const segFiles: string[] = [];
-      const usedTabs: Tab[] = [];
+      let segFiles: string[] = [];
+      let events: MotionEvent[] = [];
+      let segments: { rendered: string[]; reused: string[] } | undefined;
       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++;
+        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)}`);
             }
-            await enc?.end();
-          }),
-        );
+          }
+          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);
       }
@@ -182,7 +209,13 @@ const cmd: Command = {
       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 });
+        // 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 = {
@@ -192,18 +225,19 @@ const cmd: Command = {
         from: startF / fps,
         to: endF / fps,
         frames,
-        tabs: chunks.length,
+        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: await collectEvents(usedTabs),
+        events,
       };
       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.error(`${todo}장 ${sec.toFixed(1)}초 (${(todo / sec).toFixed(1)} 장/초)${segments ? ` · 조각 다시 ${segments.rendered.length}·그대로 ${segments.reused.length}` : ""} · 보고서 ${reportFile}`);
       console.log(out);
       return 0;
     } finally {