kasaframe 0.1.1 → 0.1.3

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

@@ -1,5 +1,8 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+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";
@@ -28,25 +31,61 @@ function beats(): boolean {
   return step("librosa", venvPython(beatsVenv), ["-m", "pip", "install", "-r", requirements]);
 }
 
-// 고정 커밋을 받아 묶고 한글 글꼴을 받는다(비동기라 따로 돌린다). 일본어 가사는 node packages/jizura/src/install.ts --lang ko,ja
+// 엔진·자주 쓰는 한글 글꼴은 패키지에 실려 있어 받을 것은 나머지 얼굴뿐이다(처음 쓸 때도 받는다 — 오프라인으로 구울 기계면 미리). 일본어 가사는 node packages/jizura/src/install.ts --lang ko,ja
 const jizura = () => step("JIZURA", process.execPath, [fileURLToPath(import.meta.resolve("@kasaframe/jizura/install")), "--lang", "ko"]);
 
 // 이름 하나 = 깔 것 하나. 이름 없이 부르면 DEFAULT 만
 const STEPS: Record<string, { what: string; run: () => boolean }> = {
   chrome: { what: "Playwright 크롬(chromium) — 렌더·검사", run: chrome },
   beats: { what: `librosa(${beatsVenv}) — 곡 분석 kf beats`, run: beats },
-  jizura: { what: "JIZURA 가사 층 엔진(고정 커밋)·한글 글꼴 60MB(~/.cache/kasaframe/jizura) — 뮤비 가사 키네틱", run: jizura },
+  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) {

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

@@ -1,7 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { join } from "node:path";
-import { listThemes, themesDir } from "@kasaframe/themes";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { listThemes, sheetDir, type Theme, themeDims, themesDir } from "@kasaframe/themes";
 import { briefs, review, scaffold, sessionPrompt, setStatus, staticCheck } from "@kasaframe/themes/factory";
+import { launch } from "../browser.ts";
 import { type Command, num, parseFlags } from "../command.ts";
 
 const kfBin = new URL("../kf.ts", import.meta.url).pathname;
@@ -13,6 +16,9 @@ kf theme new <id> --ref <그림·영상·폴더·URL> [--ref …] [--name 이름
 kf theme check <id> [--no-page]     계약·빈칸 검사 + kf check sample
 kf theme review <id> [--tabs 2]     굽기 → mp4 검사 → 장면 모음·대표 장면 → 공유 폴더 → status review
 kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
+kf theme sheet [--out 파일.png]     approved 테마마다 같은 문장 한 장면(쇼츠 9:16)을 감독 모드로 짓고 검사를 거쳐, 장면 끝 프레임을
+                                    격자 한 장으로 — 이름·2D/3D 딱지, 안전 영역 점선. 기본 themes/_sheet/sheet.png, 칸은 그 옆 <id>.png
+                                    (kf make 의 테마 질문 보기가 이 칸을 견본으로 짚는다). 검사 오류가 남은 칸은 표시하고 종료 1
 
   new 는 themes/<id>/ 에 계약 파일 뼈대·refs/·브리프대로 자른 곡과 박·장면 넷 뼈대·THEME-MAKE.md(지시서)를 짓고,
   그 지시서를 받을 세션을 여는 명령을 알려 준다. 테마는 그 세션이 만든다.`,
@@ -20,6 +26,7 @@ kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
     const [sub, ...rest] = argv;
     const { args, opts } = parseFlags(rest);
     const id = args[0];
+    if (sub === "sheet") return sheet(resolve(typeof opts.out === "string" ? opts.out : join(sheetDir, "sheet.png")));
     if (sub === "list" || !sub) {
       const all = listThemes();
       if (!all.length) console.log("(테마 없음)");
@@ -83,3 +90,83 @@ kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
 };
 
 export default cmd;
+
+// 견본 시트 — 테마끼리 견주려면 내용이 같아야 한다. 감독 모드가 실제로 짓는 장면(쇼츠 첫 장면 hook-number)을 테마만 바꿔,
+// 검사를 거쳐(떨어진 패턴은 감독이 다음 후보로 다시 짓는다) 사람이 실제로 받을 화면을 장면 끝 프레임에서 찍는다 — 움직임이 다 앉은 자리
+const SAMPLE = {
+  title: "kasaframe",
+  request: "테마 견본 — 같은 문장을 테마마다",
+  scenes: [{ id: "hook", type: "hook-number", value: 57, unit: "×", label: "KV 캐시가 이만큼 작아진다", source: "DeepSeek-V2 기술 보고서", dur: 4 }],
+};
+
+async function sheet(out: string): Promise<number> {
+  const themes = listThemes({ status: "approved" });
+  if (!themes.length) {
+    console.error("kf theme sheet: approved 테마가 없다");
+    return 1;
+  }
+  mkdirSync(dirname(out), { recursive: true });
+  const tmp = mkdtempSync(join(tmpdir(), "kf-theme-sheet-"));
+  const cells: { t: Theme; png: string; failed: boolean }[] = [];
+  let frame = { width: 1080, height: 1920, safe: { top: 0, bottom: 0, left: 0, right: 0 }, at: 0 };
+  try {
+    for (const t of themes) {
+      const dir = join(tmp, t.id);
+      const png = join(dirname(out), `${t.id}.png`);
+      const kf = (...a: string[]) => spawnSync(process.execPath, [kfBin, ...a], { encoding: "utf8" });
+      let r = kf("new", dir, "--template", "shorts", "--theme", t.id, "--title", SAMPLE.title, "--series", "none");
+      if (r.status === 0) {
+        writeFileSync(join(dir, "content.json"), `${JSON.stringify(SAMPLE, null, 2)}\n`);
+        r = kf("direct", dir, "--no-narrate", "--no-lock");
+      }
+      // 1 은 다시 지어도 검사 오류가 남았다는 뜻 — 찍되 칸에 표시한다
+      const failed = r.status === 1;
+      if (r.status === 0 || failed) {
+        const p = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+        const scene = p.scenes.find((x: { id: string }) => x.id === SAMPLE.scenes[0].id);
+        frame = { width: p.width, height: p.height, safe: p.safeArea, at: +(scene.from + scene.dur - 1 / p.fps).toFixed(4) };
+        r = kf("still", dir, "--t", String(frame.at), "--out", png);
+      }
+      if (r.status !== 0) {
+        console.error(`테마 ${t.id}: 못 찍음 — ${`${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").slice(-3).join(" / ")}`);
+        continue;
+      }
+      console.error(`테마 ${t.id}: ${png}${failed ? " — 검사 오류가 남았다(out/check.json)" : ""}`);
+      cells.push({ t, png, failed });
+    }
+    if (!cells.length) return 1;
+    const w = 360;
+    const h = Math.round((w * frame.height) / frame.width);
+    const k = w / frame.width;
+    const html = `<!doctype html><meta charset="utf-8"><style>
+      body { margin: 0; padding: 24px; background: #111; font: 16px/1.35 -apple-system, "Apple SD Gothic Neo", sans-serif; color: #ddd; }
+      h1 { margin: 0 0 16px; font-size: 18px; font-weight: 600; color: #fff; }
+      main { display: grid; grid-template-columns: repeat(${cells.length}, ${w}px); gap: 16px; }
+      figure { margin: 0; position: relative; }
+      .safe { position: absolute; left: 0; width: ${w}px; border-top: 2px dashed #ff4d4d; }
+      img { display: block; width: ${w}px; height: ${h}px; outline: 1px solid #333; }
+      figcaption { padding: 8px 2px 0; }
+      b { color: #fff; }
+      .d { display: inline-block; margin-left: 6px; padding: 0 6px; border: 1px solid #666; border-radius: 4px; font-size: 13px; }
+      small { display: block; color: #999; font-size: 13px; }
+      .bad { color: #ff6b6b; }
+    </style><h1>같은 문장 한 장면 — 「${SAMPLE.scenes[0].value}${SAMPLE.scenes[0].unit} ${SAMPLE.scenes[0].label}」 · 쇼츠 9:16 · 장면 끝 프레임(${frame.at}초) · 빨간 점선 밖은 플랫폼 UI 자리라 비운다</h1><main>${cells
+      .map(
+        ({ t, png, failed }) =>
+          `<figure><img src="data:image/png;base64,${readFileSync(png).toString("base64")}"><div class="safe" style="top:${Math.round(frame.safe.top * k)}px"></div><div class="safe" style="top:${Math.round((frame.height - frame.safe.bottom) * k)}px"></div><figcaption><b>${t.name}</b><span class="d">${themeDims(t)}</span><small>${t.id}${failed ? ' · <span class="bad">검사 오류 남음</span>' : ""}</small></figcaption></figure>`,
+      )
+      .join("")}</main>`;
+    const browser = await launch();
+    try {
+      const page = await browser.newPage({ viewport: { width: 48 + cells.length * w + (cells.length - 1) * 16, height: 400 } });
+      await page.setContent(html, { waitUntil: "load" });
+      writeFileSync(out, await page.screenshot({ fullPage: true, type: "png" }));
+    } finally {
+      await browser.close();
+    }
+    console.log(out);
+    return cells.length === themes.length && !cells.some((c) => c.failed) ? 0 : 1;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/packages/cli/src/deps.ts

@@ -43,8 +43,8 @@ function installHint(pkg: { brew: string; apt: string; url: string }): string {
 
 function node(): Check {
   const [major, minor] = process.versions.node.split(".").map(Number);
-  const ok = major > 22 || (major === 22 && minor >= 18);
-  return { name: "Node 22.18 이상", ok, required: true, detail: process.version, fix: ok ? undefined : "https://nodejs.org 에서 22 LTS 이상" };
+  const ok = major > 22 || (major === 22 && minor >= 15);
+  return { name: "Node 22.15 이상", ok, required: true, detail: process.version, fix: ok ? undefined : "https://nodejs.org 에서 22 LTS 이상" };
 }
 
 function ffmpeg(): Check {
@@ -56,7 +56,7 @@ function ffmpeg(): Check {
     ok,
     required: true,
     detail: ok ? (/version (\S+)/.exec(r.stdout)?.[1] ?? "있음") : "없음 — MP4 로 굽기·검사에 쓴다",
-    fix: ok ? undefined : installHint({ brew: "ffmpeg", apt: "ffmpeg", url: "https://ffmpeg.org/download.html" }),
+    fix: ok ? undefined : `${installHint({ brew: "ffmpeg", apt: "ffmpeg", url: "https://ffmpeg.org/download.html" })} — PATH 밖 정적 빌드면 KF_FFMPEG=<ffmpeg 경로> KF_FFPROBE=<ffprobe 경로>`,
   };
 }
 
@@ -72,7 +72,7 @@ async function chrome(): Promise<Check> {
   }
 }
 
-function librosa(): Check {
+export function librosa(): Check {
   const py = python();
   const r = run(py, ["-c", "import librosa; print(librosa.__version__)"]);
   const ok = r.status === 0;
@@ -110,8 +110,8 @@ export async function checks(): Promise<Check[]> {
 }
 
 // 한글은 터미널에서 두 칸을 먹는다 — padEnd 로는 열이 어긋난다
-const cols = (s: string) => [...s].reduce((n, ch) => n + (/[\u1100-\u11ff\u3000-\u9fff\uac00-\ud7af]/.test(ch) ? 2 : 1), 0);
-const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - cols(s)));
+export const cols = (s: string) => [...s].reduce((n, ch) => n + (/[\u1100-\u11ff\u3000-\u9fff\uac00-\ud7af]/.test(ch) ? 2 : 1), 0);
+export const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - cols(s)));
 
 export function report(list: Check[]): void {
   const w = Math.max(...list.map((c) => cols(c.name))) + 2;

package/packages/cli/src/kf.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { fontsMissing } from "@kasaframe/jizura/install";
 import type { Command } from "./command.ts";
 
 const commandsDir = fileURLToPath(new URL("./commands/", import.meta.url));
@@ -44,10 +45,20 @@ async function main(argv: string[]): Promise<number> {
   return (await cmd.run(rest)) ?? 0;
 }
 
+// 가사 층 글꼴을 처음 쓰다 못 받았으면(서버가 받는다 — jizura/vite.ts) 다른 글꼴로 구운 결과 대신 고를 길을 찍는다.
+// 명령이 실패했으면 종료 3, 그 글꼴을 쓰는 프레임 없이 끝났으면 그대로
+async function finish(code: number): Promise<number> {
+  const miss = fontsMissing();
+  if (!miss.length) return code;
+  const [{ fontsQuestion }, { questionsText }] = await Promise.all([import("./commands/lyrics.ts"), import("@kasaframe/gen")]);
+  console.error(`\n${code ? "" : "이번 구간은 그 글꼴 없이 끝났다 — 그 플랜이 나오는 구간을 구우려면 먼저 고른다\n"}${questionsText([fontsQuestion(miss)])}`);
+  return code ? 3 : code;
+}
+
 main(process.argv.slice(2)).then(
-  (code) => process.exit(code),
-  (err) => {
+  async (code) => process.exit(await finish(code)),
+  async (err) => {
     console.error(err instanceof Error ? (err.stack ?? err.message) : err);
-    process.exit(1);
+    process.exit(await finish(1));
   },
 );

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/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--;
+    }
+  };
+}