kasaframe 0.0.0-stage → 0.1.3

package/packages/cli/src/mix.ts

@@ -0,0 +1,131 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { audioDuration, findSilences } from "@kasaframe/gen";
+
+// 내레이션 + 곡 섞기 — kf.json 에 audio(섞기 값)가 있는 프로젝트만. 없으면 렌더는 예전처럼 곡만 얹는다
+export interface AudioMix {
+  musicDb: number; // 말하는 동안 곡이 목소리보다 이만큼 아래(덕킹 포함)
+  duck: boolean;
+  lufs: number;
+  truePeak: number;
+  fadeOut: number;
+}
+
+// 목소리를 먼저 이 크기로 맞춘다 — 덕킹 문턱이 목소리 크기에 묶여 있어서 공급자마다 다른 크기를 한 자리로
+const VOICE_LUFS = -18;
+// 덕킹 두 입력의 프레임 크기를 맞춘다 — 목소리 wav(1024)·곡 mp3(1152) 프레임이 도착 차례에 따라 sidechaincompress 결과가
+// 실행마다 달라졌다(같은 요청이면 바이트까지 같은 영상이어야 한다). 두 갈래를 같은 크기로 잘라 넣으면 늘 같은 값이 나온다
+const FRAMES = "asetnsamples=n=1024:p=0";
+const SIDECHAIN = "sidechaincompress=threshold=0.025:ratio=3:attack=20:release=400:knee=4";
+
+function ffmpeg(args: string[]): Promise<string> {
+  return new Promise((done, fail) => {
+    const p = spawn("ffmpeg", ["-hide_banner", "-nostats", "-y", ...args]);
+    let err = "";
+    p.stderr.on("data", (b: Buffer) => (err += b));
+    p.on("error", fail);
+    p.on("close", (code) => (code === 0 ? done(err) : fail(new Error(`ffmpeg 섞기 실패(${code}): ${err.trim().split("\n").slice(-3).join(" / ")}`))));
+  });
+}
+
+// 통합 크기(LUFS) — 무음은 게이트가 빼서 말·곡이 실제로 울리는 곳만 잰다
+async function loudness(input: string[], filter = ""): Promise<number> {
+  const err = await ffmpeg([...input, "-af", `${filter ? `${filter},` : ""}ebur128=framelog=quiet`, "-f", "null", "-"]);
+  const m = err.match(/I:\s+(-?[\d.]+|-inf) LUFS/g)?.at(-1)?.match(/(-?[\d.]+|-inf)/);
+  const v = m ? Number(m[1]) : NaN;
+  return Number.isFinite(v) ? v : -70;
+}
+
+// 말하는 구간만 고르는 aselect 식 — 목소리 한 줄에서 0.3초 넘는 숨을 뺀 자리
+async function speechSelect(voice: string): Promise<string | null> {
+  const total = await audioDuration(voice);
+  const spans: [number, number][] = [];
+  let t = 0;
+  for (const s of await findSilences(voice, { db: -40, min: 0.3 })) {
+    if (s.from > t + 0.2) spans.push([t, s.from]);
+    t = Math.min(s.to, total);
+  }
+  if (total > t + 0.2) spans.push([t, total]);
+  return spans.length ? spans.map(([a, b]) => `between(t,${a.toFixed(3)},${b.toFixed(3)})`).join("+") : null;
+}
+
+interface Sources {
+  voice?: string;
+  music?: string;
+  musicFrom: number; // 곡 시각 = musicFrom + 영상 시각
+}
+
+export function mixSettings(dir: string): { audio: AudioMix; voice?: string } | null {
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+  if (!kf.audio) return null;
+  const voice = kf.narration ? resolve(dir, kf.narration) : undefined;
+  return { audio: kf.audio, voice: voice && existsSync(voice) ? voice : undefined };
+}
+
+// 영상 [from, from+dur) 의 소리를 out(wav)으로. total 은 영상 전체 길이 — 끝 페이드는 영상 끝에 걸린다
+export async function mixAudio(src: Sources, o: { audio: AudioMix; from: number; dur: number; total: number; out: string }): Promise<string> {
+  const { audio } = o;
+  const seg = (path: string, at: number) => ["-ss", at.toFixed(6), "-t", o.dur.toFixed(6), "-i", path];
+  const inputs: string[] = [];
+  const chains: string[] = [];
+  let k = 0;
+  let voiceLabel = "";
+  let musicLabel = "";
+  // 끝 페이드는 영상 끝 몇 초에만 — 구간만 굽을 때도 같은 자리
+  const fadeAt = o.total - audio.fadeOut - o.from;
+  const fade = audio.fadeOut > 0 && fadeAt < o.dur ? `,afade=t=out:st=${Math.max(0, fadeAt).toFixed(4)}:d=${audio.fadeOut.toFixed(4)}` : "";
+  let voiceGain = 0;
+  if (src.voice) {
+    // 크기는 영상 전체로 잰다 — 구간만 재면 구간마다 목소리 크기가 달라진다
+    voiceGain = VOICE_LUFS - (await loudness(["-i", src.voice]));
+    inputs.push(...seg(src.voice, o.from));
+    chains.push(`[${k}]aresample=48000,volume=${voiceGain.toFixed(2)}dB,pan=stereo|c0=c0|c1=c0,${FRAMES},asplit=2[v][vsc]`);
+    voiceLabel = "[v]";
+    k++;
+  }
+  if (src.music) {
+    // 말이 있으면 말하는 동안 곡이 목소리보다 |musicDb| 아래, 없으면 곡이 주인공이라 그대로 두고 정규화만
+    const gain = src.voice ? await musicGain(src as Required<Sources>, voiceGain, audio, o.total) : 0;
+    inputs.push("-stream_loop", "-1", ...seg(src.music, src.musicFrom + o.from));
+    chains.push(`[${k}]aresample=48000,aformat=channel_layouts=stereo,volume=${gain.toFixed(2)}dB${fade},${FRAMES}[m0]`);
+    musicLabel = "[m0]";
+    if (src.voice && audio.duck) {
+      chains.push(`[m0][vsc]${SIDECHAIN}[m1]`);
+      musicLabel = "[m1]";
+    }
+    k++;
+  }
+  if (!voiceLabel && !musicLabel) throw new Error("섞을 소리가 없다");
+  if (voiceLabel && !musicLabel) chains.push("[vsc]anullsink");
+  const parts = [voiceLabel, musicLabel].filter(Boolean);
+  chains.push(parts.length === 2 ? `${parts.join("")}amix=inputs=2:normalize=0:duration=longest,apad,atrim=0:${o.dur.toFixed(6)}[pre]` : `${parts[0]}apad,atrim=0:${o.dur.toFixed(6)}[pre]`);
+  const pre = o.out.replace(/\.wav$/, ".pre.wav");
+  await ffmpeg([...inputs, "-filter_complex", chains.join(";"), "-map", "[pre]", "-c:a", "pcm_s24le", "-ar", "48000", pre]);
+  // 두 번 잰다 — 한 번에 loudnorm 을 걸면 동적 모드로 들어가 덕킹 모양이 뭉개진다. 잰 값을 주고 linear 로 한 번에 올린다
+  const err = await ffmpeg(["-i", pre, "-af", `loudnorm=I=${audio.lufs}:TP=${audio.truePeak}:LRA=11:print_format=json`, "-f", "null", "-"]);
+  const j = JSON.parse(err.slice(err.lastIndexOf("{"), err.lastIndexOf("}") + 1));
+  const ln = `loudnorm=I=${audio.lufs}:TP=${audio.truePeak}:LRA=11:measured_I=${j.input_i}:measured_TP=${j.input_tp}:measured_LRA=${j.input_lra}:measured_thresh=${j.input_thresh}:offset=${j.target_offset}:linear=true`;
+  await ffmpeg(["-i", pre, "-af", `${ln},aresample=48000`, "-c:a", "pcm_s16le", o.out]);
+  return o.out;
+}
+
+// 곡 셈여림(조용한 도입·부푸는 가운데)과 덕킹 깊이(5–10dB)가 곡마다 달라 상수로는 안 맞는다 — 영상 전체에서 말하는 구간만 골라
+// 목소리와 덕킹된 곡을 한 번 재고 그 차만큼 곡을 옮긴다. 덕킹은 목소리로만 걸려 곡 크기와 무관하니 한 번이면 된다
+export async function musicGain(src: Required<Sources>, voiceGain: number, audio: AudioMix, total: number): Promise<number> {
+  const music = ["-stream_loop", "-1", "-ss", src.musicFrom.toFixed(6), "-t", total.toFixed(6), "-i", src.music];
+  const g0 = VOICE_LUFS + audio.musicDb - (await loudness(music));
+  const sel = await speechSelect(src.voice);
+  if (!sel) return g0;
+  const pick = `aselect='${sel}',asetpts=N/SR/TB`;
+  const voiceSpeech = await loudness(["-i", src.voice], `volume=${voiceGain.toFixed(2)}dB,${pick}`);
+  const duck = audio.duck ? `;[m0][vsc]${SIDECHAIN}[m1]` : "";
+  const err = await ffmpeg([
+    "-i", src.voice, ...music,
+    "-filter_complex", `[0]aresample=48000,volume=${voiceGain.toFixed(2)}dB,pan=stereo|c0=c0|c1=c0,${FRAMES}[vsc];[1]aresample=48000,aformat=channel_layouts=stereo,volume=${g0.toFixed(2)}dB,${FRAMES}[m0]${duck};[${audio.duck ? "m1" : "m0"}]${pick},ebur128=framelog=quiet[out]${audio.duck ? "" : ";[vsc]anullsink"}`,
+    "-map", "[out]", "-f", "null", "-",
+  ]);
+  const m = err.match(/I:\s+(-?[\d.]+|-inf) LUFS/g)?.at(-1)?.match(/(-?[\d.]+|-inf)/);
+  const musicSpeech = m ? Number(m[1]) : NaN;
+  return Number.isFinite(musicSpeech) ? g0 + (voiceSpeech + audio.musicDb - musicSpeech) : g0;
+}

package/packages/cli/src/out.ts

@@ -0,0 +1,13 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+// 결과물은 기본으로 프로젝트의 out/ 에 둔다.
+export function outPath(dir: string, given: string | boolean | undefined, fallback: string): string {
+  const p = typeof given === "string" ? resolve(given) : join(resolve(dir), "out", fallback);
+  mkdirSync(dirname(p), { recursive: true });
+  return p;
+}
+
+export function fmtTime(t: number): string {
+  return t.toFixed(3).replace(/\.?0+$/, "") || "0";
+}

package/packages/cli/src/pool.ts

@@ -0,0 +1,34 @@
+// 장면별 일(장면 쓰기·그림·목소리)을 동시에 — 모델·공급자 호출이 대부분 기다림이라 겹치면 장면 수만큼 빨라진다.
+// 동시 수는 KF_JOBS 로 누른다(요금 한도·속도 제한이 빡빡한 키). 돈 드는 호출의 묻기·예산은 부르는 쪽 그대로다
+
+export const jobLimit = (fallback: number): number => Math.max(1, Math.floor(Number(process.env.KF_JOBS) || fallback));
+
+/** n 개까지 동시에. 결과는 넣은 순서대로 */
+export async function pool<T, R>(items: readonly T[], n: number, fn: (item: T, i: number) => Promise<R>): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(n, items.length) }, async () => {
+      for (let i = next++; i < items.length; i = next++) out[i] = await fn(items[i], i);
+    }),
+  );
+  return out;
+}
+
+/** 한 번에 n 개만 지나가는 문 — 크롬을 띄우는 일처럼 기계가 감당할 만큼만 */
+export function gate(n: number): <R>(fn: () => Promise<R>) => Promise<R> {
+  let busy = 0;
+  const wait: (() => void)[] = [];
+  return async (fn) => {
+    // 자리를 기다리던 쪽에 바로 넘긴다 — 풀었다 다시 잡는 사이에 새로 온 쪽이 끼어들면 n 을 넘는다
+    if (busy < n) busy++;
+    else await new Promise<void>((r) => wait.push(r));
+    try {
+      return await fn();
+    } finally {
+      const w = wait.shift();
+      if (w) w();
+      else busy--;
+    }
+  };
+}

package/packages/cli/src/segments.ts

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import type { ViteDevServer } from "vite";
+import type { Session, Tab } from "./browser.ts";
+import { type BlurOpts, captureBlurred } from "./blur.ts";
+import { concat, encoder, type VideoFormat } from "./ffmpeg.ts";
+import { repoRoot } from "./serve.ts";
+
+// 장면 조각 렌더 — 장면마다 out/segments/<장면>-<해시>.mp4 를 두고, 해시가 같으면 다시 찍지 않는다.
+// 해시는 그 장면이 실제로 불러온 모듈(Vite 모듈 그래프 — 장면 파일·lib·@kasaframe 소스·테마·glob 로 읽은 json)·
+// kf.json 의 그 장면 칸·자산·자막 줄·굽기 설정이다. seek 모드는 프레임이 시각의 순수 함수라 조각을 이어도 통짜로 구운 것과 프레임이 같다.
+
+// 조각 꼴(인코딩·해시 재료)이 바뀌면 올린다 — 옛 조각을 다시 쓰지 않게
+const VERSION = "seg-1";
+// 화면을 안 바꾸는 kf.json 칸 — 소리·굽기 기본값·검사 예외. 굽기 값(모션 블러)은 KeyOpts 로 따로 들어간다
+const NOT_FRAMES = new Set(["scenes", "music", "audio", "voice", "narration", "render", "check"]);
+const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
+
+export interface SceneEntry {
+  id: string;
+  from: number;
+  dur: number;
+  role?: string;
+  file?: string;
+  [k: string]: unknown;
+}
+
+export interface SceneSpan {
+  id: string;
+  role?: string;
+  /** 프레임 [start, end) */
+  start: number;
+  end: number;
+}
+
+/** 프레임 f 의 장면 — 페이지(mountProject)와 같은 판정 from ≤ f/fps. 조각들이 0..total 을 빈틈·겹침 없이 한 번씩 덮는다 */
+export function sceneSpans(scenes: Pick<SceneEntry, "id" | "from" | "role">[], fps: number, total: number): SceneSpan[] {
+  const firstFrame = (from: number) => {
+    let f = Math.max(0, Math.round(from * fps) - 2);
+    while (f / fps < from) f++;
+    return Math.min(total, f);
+  };
+  return scenes
+    .map((s, i) => ({ id: s.id, role: s.role, start: i === 0 ? 0 : firstFrame(s.from), end: i === scenes.length - 1 ? total : firstFrame(scenes[i + 1].from) }))
+    .filter((s) => s.end > s.start);
+}
+
+export interface KeyOpts {
+  width: number;
+  height: number;
+  fps: number;
+  format: VideoFormat;
+  crf?: number;
+  blur: BlurOpts | null;
+  captions?: string;
+  /** 크롬 판 — 래스터가 판마다 다를 수 있다 */
+  browser: string;
+}
+
+/** 굽기 설정 묶음 하나 — 자막 켠 판·끈 판처럼 같은 장면을 다른 설정으로 구운 조각을 따로 센다 */
+export const variantOf = (o: KeyOpts): string => sha(JSON.stringify([VERSION, o])).slice(0, 10);
+
+const sha = (...parts: (string | Buffer)[]) => {
+  const h = createHash("sha256");
+  for (const p of parts) h.update(p).update("\0");
+  return h.digest("hex");
+};
+
+const omit = (o: Record<string, unknown>, keys: Set<string>) => Object.fromEntries(Object.entries(o).filter(([k]) => !keys.has(k)));
+
+function listFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? listFiles(join(dir, e.name)) : [join(dir, e.name)]));
+}
+
+interface Line {
+  scene?: string;
+  from?: number;
+  to?: number;
+}
+
+export interface SceneKey {
+  key: string;
+  /** 해시 재료 이름 → 그 해시. 조각 기록에 남겨 다음에 「무엇이 바뀌어 다시 찍나」를 짚는다 */
+  inputs: Record<string, string>;
+}
+
+/**
+ * 장면마다 조각 해시. 장면이 다른 장면 모듈을 불러오면(이음매 — 앞 장면 끝·뒤 장면 처음을 살아 있는 화면으로 잇는다) 그 장면들의 해시도 묻는다.
+ * 이음매는 앞뒤 둘만 쓰므로(transition3d live) 이웃 둘로 좁힌다 — 멀리 있는 장면을 고쳐도 이음매는 그대로.
+ */
+export function sceneKeys(server: ViteDevServer, root: string, o: KeyOpts): Map<string, SceneKey> {
+  const kf = JSON.parse(readFileSync(join(root, "kf.json"), "utf8")) as { scenes: SceneEntry[]; [k: string]: unknown };
+  const graph = server.environments.client.moduleGraph;
+  const kfFile = join(root, "kf.json");
+  const capFile = join(root, "captions.json");
+  const sceneFile = new Map(kf.scenes.map((s) => [join(root, s.file ?? `scenes/${s.id}.ts`), s.id]));
+  const memo = new Map<string, string>();
+  const fileHash = (f: string) => {
+    let h = memo.get(f);
+    if (h === undefined) {
+      h = existsSync(f) && statSync(f).isFile() ? sha(readFileSync(f)) : "-";
+      memo.set(f, h);
+    }
+    return h;
+  };
+  // 레포 소스와 프로젝트 파일만 — node_modules(외부 꾸러미·미리 묶은 의존)는 판이 바뀔 일이 드물고 수가 많다
+  const label = (f: string): string | null => {
+    for (const [base, tag] of [[root, ""], [repoRoot, "kf:"]] as const) {
+      const rel = relative(base, f);
+      if (rel.startsWith("..") || rel.split(sep).includes("node_modules")) continue;
+      if (tag === "" && rel.split(sep)[0] === "out") return null;
+      return `${tag}${rel}`;
+    }
+    return null;
+  };
+
+  function walk(start: string): { files: Map<string, string>; scenes: Set<string> } {
+    const files = new Map<string, string>();
+    const scenes = new Set<string>();
+    const stack = [...(graph.getModulesByFile(start) ?? [])];
+    const seen = new Set<unknown>();
+    while (stack.length) {
+      const m = stack.pop()!;
+      if (seen.has(m)) continue;
+      seen.add(m);
+      const f = m.file;
+      if (f && f !== start && sceneFile.has(f)) {
+        scenes.add(sceneFile.get(f)!);
+        continue;
+      }
+      const name = f ? label(f) : null;
+      if (f && !name) continue;
+      if (f && name && f !== kfFile && f !== capFile) files.set(name, fileHash(f));
+      stack.push(...m.importedModules);
+    }
+    if (!files.size && existsSync(start)) files.set(label(start) ?? start, fileHash(start));
+    return { files, scenes };
+  }
+  const listed = (m: Map<string, string>) => JSON.stringify([...m].sort((a, b) => (a[0] < b[0] ? -1 : 1)));
+
+  const base = walk(join(root, "main.ts")).files;
+  base.set("index.html", fileHash(join(root, "index.html")));
+  base.set("kf.json 화면 칸", sha(JSON.stringify(omit(kf, NOT_FRAMES))));
+  base.set("굽기 설정", sha(JSON.stringify([VERSION, o])));
+  const common = sha(listed(base));
+  const lines: Line[] = existsSync(capFile) ? JSON.parse(readFileSync(capFile, "utf8")) : [];
+  const assets = listFiles(join(root, "assets")).filter((f) => !AUDIO.test(f)).map((f) => ({ f, rel: relative(join(root, "assets"), f).split(sep).join("/") }));
+
+  const own = new Map<string, string>();
+  const inputs = new Map<string, Record<string, string>>();
+  const deps = new Map<string, Set<string>>();
+  for (const [i, s] of kf.scenes.entries()) {
+    const file = join(root, s.file ?? `scenes/${s.id}.ts`);
+    const w = walk(file);
+    // 자산은 장면이 글자로 적은 경로(프로젝트 안 소스) + 장면 id 로 시작하는 파일(gen/<id>.png·blender/<id>.mp4·seam/<id>-from.png)
+    const text = [...w.files.keys()].filter((n) => !n.startsWith("kf:")).map((n) => (existsSync(join(root, n)) ? readFileSync(join(root, n), "utf8") : "")).join("\n");
+    const used = assets
+      .filter(({ f, rel }) => text.includes(rel) || new RegExp(`^${s.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([.\\-_]|$)`).test(f.split(sep).pop()!))
+      .map(({ f, rel }) => [rel, fileHash(f)]);
+    const cap = lines.filter((l) => l.scene === s.id || (l.scene === undefined && l.from !== undefined && l.from < s.from + s.dur && (l.to ?? l.from) >= s.from));
+    own.set(s.id, sha(common, listed(w.files), JSON.stringify(omit(s, new Set(["idea"]))), JSON.stringify(cap), JSON.stringify(used)));
+    inputs.set(s.id, {
+      ...Object.fromEntries(base),
+      ...Object.fromEntries(w.files),
+      "kf.json 장면 칸": sha(JSON.stringify(omit(s, new Set(["idea"])))),
+      "자막 줄": sha(JSON.stringify(cap)),
+      ...Object.fromEntries(used.map(([rel, h]) => [`assets/${rel}`, h])),
+    });
+    const d = new Set(s.role === "seam" ? [kf.scenes[i - 1]?.id, kf.scenes[i + 1]?.id].filter((x): x is string => !!x) : w.scenes);
+    deps.set(s.id, d);
+  }
+  // 경계 프레임에서 앞 장면이 아직 켜져 있으면(from+dur 이 다음 from 보다 끝자리만큼 큰 경우) 그 프레임은 두 장면이 겹쳐 그린다
+  const spans = sceneSpans(kf.scenes, o.fps, Math.round(Number(kf.duration) * o.fps));
+  for (const [i, sp] of spans.entries()) {
+    const prev = kf.scenes.find((s) => s.id === spans[i - 1]?.id);
+    if (prev && sp.start / o.fps < prev.from + prev.dur) deps.get(sp.id)!.add(prev.id);
+  }
+  return new Map(
+    kf.scenes.map((s) => {
+      const ds = [...deps.get(s.id)!].sort();
+      const key = sha(own.get(s.id)!, ...ds.map((d) => own.get(d) ?? d)).slice(0, 12);
+      return [s.id, { key, inputs: { ...inputs.get(s.id)!, ...Object.fromEntries(ds.map((d) => [`장면 ${d}`, own.get(d) ?? d])) } }];
+    }),
+  );
+}
+
+// 그 장면의 가장 최근 조각 기록(해시가 달라도) — 바뀐 재료와 장당 걸린 시간을 여기서 읽는다
+function lastRecord(root: string, id: string): Partial<SegmentReport> & { tabSeconds?: number } | null {
+  const dir = segmentDir(root);
+  if (!existsSync(dir)) return null;
+  const prev = readdirSync(dir)
+    .filter((f) => f.startsWith(`${id}-`) && f.endsWith(".json") && /^[0-9a-f]{12}$/.test(f.slice(id.length + 1, -5)))
+    .map((f) => join(dir, f))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+  if (!prev) return null;
+  try {
+    return JSON.parse(readFileSync(prev, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 같은 장면의 지난 조각 기록과 견줘 바뀐 재료 이름 — 「왜 다시 찍나」 */
+export function changedInputs(root: string, id: string, now: Record<string, string>): string[] | null {
+  const old = lastRecord(root, id)?.inputs;
+  if (!old) return null;
+  return [...new Set([...Object.keys(old), ...Object.keys(now)])].filter((k) => old[k] !== now[k]).sort();
+}
+
+export interface SegmentReport {
+  id: string;
+  key: string;
+  file: string;
+  frames: number;
+  seconds: number;
+  events: MotionEvent[];
+  inputs?: Record<string, string>;
+  /** 탭들이 이 장면을 찍는 데 쓴 초의 합 — 다음 굽기가 장면 무게를 어림한다 */
+  tabSeconds?: number;
+}
+
+export interface MotionEvent {
+  t: number;
+  kind: string;
+  source: string;
+  scene?: string;
+}
+
+export const segmentDir = (root: string) => join(root, "out", "segments");
+export const segmentFile = (root: string, id: string, key: string, ext: string) => join(segmentDir(root), `${id}-${key}${ext}`);
+
+/** 이미 구운 조각 — 영상과 기록(.json) 둘 다 있어야 다시 쓴다 */
+export function cachedSegment(root: string, id: string, key: string, ext: string): SegmentReport | null {
+  const file = segmentFile(root, id, key, ext);
+  const meta = segmentFile(root, id, key, ".json");
+  if (!existsSync(file) || !existsSync(meta)) return null;
+  try {
+    return { ...JSON.parse(readFileSync(meta, "utf8")), file };
+  } catch {
+    return null;
+  }
+}
+
+function split(start: number, end: number, n: number): [number, number][] {
+  const out: [number, number][] = [];
+  for (let i = 0; i < n; i++) {
+    const a = start + Math.floor(((end - start) * i) / n);
+    const b = start + Math.floor(((end - start) * (i + 1)) / n);
+    if (b > a) out.push([a, b]);
+  }
+  return out;
+}
+
+export interface SegmentWork {
+  span: SceneSpan;
+  key: string;
+  inputs?: Record<string, string>;
+}
+
+/**
+ * 고른 장면 조각을 탭 여러 개로 굽는다. 장면 하나가 길면 탭 몫으로 쪼개 찍고 그 장면 조각 하나로 잇는다(탭이 놀지 않게).
+ * 장면마다 「장면 <id>: 렌더」「장면 <id>: 구움」 줄을 찍는다 — 작업실이 타임라인 상태로 읽는다
+ */
+export async function renderSegments(o: {
+  session: Session;
+  root: string;
+  work: SegmentWork[];
+  tabs: number;
+  format: VideoFormat;
+  ext: string;
+  crf?: number;
+  blur: BlurOpts | null;
+  tmp: string;
+  onFrame?: () => void;
+}): Promise<SegmentReport[]> {
+  const { session: s, root } = o;
+  const { fps, width, height } = s.info.meta;
+  mkdirSync(segmentDir(root), { recursive: true });
+  mkdirSync(o.tmp, { recursive: true });
+  // 장면마다 장당 무게가 다르다(3D 이음매는 글 장면의 두 배 넘게) — 지난 기록으로 어림해 탭마다 두 몫쯤 되게 쪼개고
+  // 무거운 몫부터 나눠 준다. 기록이 없으면 장 수로 어림한다
+  const perFrame = new Map(o.work.map((w) => {
+    const r = lastRecord(root, w.span.id);
+    return [w.span.id, r?.frames ? (r.tabSeconds ?? r.seconds ?? 0) / r.frames : 0];
+  }));
+  const known = [...perFrame.values()].filter((x) => x > 0);
+  const guess = known.length ? known.reduce((a, b) => a + b, 0) / known.length : 1;
+  const cost = (w: SegmentWork) => (w.span.end - w.span.start) * (perFrame.get(w.span.id) || guess);
+  const unit = o.work.reduce((n, w) => n + cost(w), 0) / Math.max(1, o.tabs * 2);
+  const minFrames = Math.ceil(fps / 2);
+  const parts = o.work
+    .flatMap((w) => {
+      const frames = w.span.end - w.span.start;
+      const n = Math.max(1, Math.min(Math.round(cost(w) / unit), Math.floor(frames / minFrames)));
+      return split(w.span.start, w.span.end, n).map(([a, b], k) => ({ w, k, a, b, cost: (cost(w) * (b - a)) / frames }));
+    })
+    .sort((x, y) => y.cost - x.cost);
+  const busy = new Map<string, number>();
+  const left = new Map(o.work.map((w) => [w.span.id, parts.filter((p) => p.w === w).length]));
+  const started = new Map<string, number>();
+  const finished: Promise<void>[] = [];
+  const queue = [...parts];
+  const tabs: Tab[] = [];
+  const workers = Math.min(o.tabs, parts.length);
+
+  async function join1(w: SegmentWork): Promise<void> {
+    const n = parts.filter((p) => p.w === w).length;
+    const list = join(o.tmp, `${w.span.id}.txt`);
+    writeFileSync(list, Array.from({ length: n }, (_, k) => `file '${join(o.tmp, `${w.span.id}-${k}${o.ext}`).replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+    const tmpOut = join(o.tmp, `${w.span.id}${o.ext}`);
+    await concat({ list, out: tmpOut, format: o.format, from: 0, dur: (w.span.end - w.span.start) / fps });
+    renameSync(tmpOut, segmentFile(root, w.span.id, w.key, o.ext));
+    console.error(`장면 ${w.span.id}: 구움 — ${w.span.end - w.span.start}장 ${((Date.now() - started.get(w.span.id)!) / 1000).toFixed(1)}초`);
+  }
+
+  await Promise.all(
+    Array.from({ length: workers }, async (_, i) => {
+      const tab = i === 0 ? s.first : await s.tab();
+      tabs.push(tab);
+      for (let p = queue.shift(); p; p = queue.shift()) {
+        if (!started.has(p.w.span.id)) {
+          started.set(p.w.span.id, Date.now());
+          const why = p.w.inputs && changedInputs(root, p.w.span.id, p.w.inputs);
+          console.error(`장면 ${p.w.span.id}: 렌더${why?.length ? ` — 바뀜: ${why.slice(0, 3).join(", ")}${why.length > 3 ? ` 외 ${why.length - 3}` : ""}` : ""}`);
+        }
+        const raw = o.blur ? { width, height } : undefined;
+        const t0 = Date.now();
+        const enc = encoder(join(o.tmp, `${p.w.span.id}-${p.k}${o.ext}`), fps, o.format, o.crf, raw);
+        for (let f = p.a; f < p.b; f++) {
+          if (o.blur) await enc.write((await captureBlurred(tab, s.info, f / fps, o.blur)).data);
+          else {
+            await tab.seek(f / fps);
+            await enc.write(await tab.capture());
+          }
+          o.onFrame?.();
+        }
+        await enc.end();
+        busy.set(p.w.span.id, (busy.get(p.w.span.id) ?? 0) + (Date.now() - t0) / 1000);
+        const rest = left.get(p.w.span.id)! - 1;
+        left.set(p.w.span.id, rest);
+        if (rest === 0) finished.push(join1(p.w));
+      }
+    }),
+  );
+  await Promise.all(finished);
+
+  // 움직임 기록은 탭에 쌓인다 — 장면 시각으로 갈라 조각마다 남긴다(검사가 영상 옆 .json 으로 센다)
+  const events = await collectEvents(tabs);
+  return o.work.map((w) => {
+    const from = w.span.start / fps;
+    const to = w.span.end / fps;
+    const rep: SegmentReport = {
+      id: w.span.id,
+      key: w.key,
+      file: segmentFile(root, w.span.id, w.key, o.ext),
+      frames: w.span.end - w.span.start,
+      seconds: Math.round((Date.now() - started.get(w.span.id)!) / 100) / 10,
+      events: events.filter((e) => e.t >= from - 1e-9 && e.t < to - 1e-9),
+      tabSeconds: Math.round((busy.get(w.span.id) ?? 0) * 10) / 10,
+      ...(w.inputs ? { inputs: w.inputs } : {}),
+    };
+    const { file: _f, ...meta } = rep;
+    writeFileSync(segmentFile(root, w.span.id, w.key, ".json"), JSON.stringify(meta));
+    return rep;
+  });
+}
+
+export 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);
+}
+
+/** 굽기 설정마다 지금 쓰는 조각을 적고, 어느 설정에서도 안 쓰는 옛 조각은 지운다(최근 설정 넷까지 둔다) */
+export function pruneSegments(root: string, variant: string, current: Record<string, string>): void {
+  const dir = segmentDir(root);
+  const indexFile = join(dir, "index.json");
+  let index: Record<string, { at: number; scenes: Record<string, string> }> = {};
+  try {
+    index = JSON.parse(readFileSync(indexFile, "utf8"));
+  } catch {}
+  index[variant] = { at: Date.now(), scenes: current };
+  const keep = Object.entries(index).sort((a, b) => b[1].at - a[1].at).slice(0, 4);
+  index = Object.fromEntries(keep);
+  writeFileSync(indexFile, JSON.stringify(index, null, 1));
+  const used = new Set(keep.flatMap(([, v]) => Object.entries(v.scenes).map(([id, key]) => `${id}-${key}`)));
+  for (const f of readdirSync(dir)) {
+    if (f === "index.json") continue;
+    if (!used.has(f.replace(/\.[^.]+$/, ""))) rmSync(join(dir, f), { force: true });
+  }
+}