kasaframe 0.1.4 → 0.1.6

package/packages/cli/src/fonts.ts

@@ -0,0 +1,405 @@
+// kf fonts — 글꼴 짝을 받아 재고(주소·판·라이선스 글·한글 덮음·굵기) 크롬으로 견본을 찍어 글이 실제로 서는지 본다.
+// 받은 파일은 <캐시>/fonts/files 에 두고, 크롬에는 그 파일을 같은 주소로 내준다 — 두 번째부터는 주소가 살았는지만 묻는다.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { BrowserContext, Page } from "playwright";
+import { readFontFile } from "@kasaframe/themes/fontfile";
+import {
+  type FaceFile,
+  faceForChar,
+  FONT_SAMPLE,
+  type FontPair,
+  licenseVerdict,
+  measurePair,
+  type PairMeasure,
+  pairProblems,
+  type SampleLine,
+  stackFamilies,
+  stackUses,
+} from "@kasaframe/themes/fonts";
+import { launch } from "./browser.ts";
+import { pool } from "./pool.ts";
+
+export const fontCacheDir = (): string => join(process.env.KF_CACHE_DIR ?? join(homedir(), ".cache", "kasaframe"), "fonts");
+export const cachedFontFile = (url: string) => join(fontCacheDir(), "files", `${createHash("sha1").update(url).digest("hex").slice(0, 20)}${/\.\w+$/.exec(new URL(url).pathname)?.[0] ?? ""}`);
+
+interface Fetched {
+  /** HTTP 상태, 못 닿으면 까닭 */
+  status: number | string;
+  text?: string;
+}
+
+async function get(url: string, how: "head" | "file" | "text"): Promise<Fetched> {
+  for (let tries = 0; ; tries++) {
+    try {
+      const r = await fetch(url, { method: how === "head" ? "HEAD" : "GET", redirect: "follow", signal: AbortSignal.timeout(60_000) });
+      if (r.status >= 500 && tries < 2) continue;
+      if (!r.ok || how === "head") return { status: r.status };
+      if (how === "text") return { status: r.status, text: await r.text() };
+      const path = cachedFontFile(url);
+      mkdirSync(join(fontCacheDir(), "files"), { recursive: true });
+      writeFileSync(`${path}.tmp`, Buffer.from(await r.arrayBuffer()));
+      renameSync(`${path}.tmp`, path);
+      return { status: r.status };
+    } catch (err) {
+      if (tries < 2) continue;
+      return { status: (err as Error).message };
+    }
+  }
+}
+
+export interface RenderLine {
+  stack: string;
+  weight: number;
+  line: SampleLine;
+  fonts: { family: string; custom: boolean; glyphs: number }[];
+  ink: number;
+  tofu: string[];
+}
+
+export interface PairReport {
+  id: string;
+  group: string;
+  name: string;
+  ok: boolean;
+  hangul?: PairMeasure["hangul"];
+  syllables?: number;
+  boldest?: number;
+  licenses: string[];
+  problems: string[];
+  notes: string[];
+}
+
+export interface CheckOptions {
+  /** 주소를 묻지 않고 캐시만 — 처음 보는 파일은 문제로 남는다 */
+  offline?: boolean;
+  render?: boolean;
+  log?: (s: string) => void;
+}
+
+/** 짝들을 재고 찍어 본다 — 받기는 주소마다 한 번 */
+export async function checkFonts(list: { group: string; pair: FontPair }[], o: CheckOptions = {}): Promise<PairReport[]> {
+  const log = o.log ?? (() => {});
+  const srcs = [...new Set(list.flatMap(({ pair }) => (pair.faces ?? []).map((f) => f.src)))];
+  const sources = o.offline ? [] : [...new Set(list.flatMap(({ pair }) => (pair.faces ?? []).map((f) => f.source).filter(Boolean)))];
+  // 같은 주소가 파일로도 라이선스 글로도 쓰일 수 있어 둘을 따로 둔다
+  const net = { file: new Map<string, Fetched>(), text: new Map<string, Fetched>() };
+  let done = 0;
+  await pool([...srcs.map((u) => ({ u, kind: "file" as const })), ...sources.map((u) => ({ u, kind: "text" as const }))], 8, async ({ u, kind }) => {
+    let r: Fetched;
+    try {
+      new URL(u);
+    } catch {
+      net[kind].set(u, { status: "주소가 아니다" });
+      return;
+    }
+    const cached = kind === "file" && existsSync(cachedFontFile(u));
+    if (o.offline) r = { status: cached ? 200 : "캐시에 없다(--offline)" };
+    else r = await get(u, cached ? "head" : kind);
+    net[kind].set(u, r);
+    if (++done % 25 === 0) log(`  주소 ${done}/${srcs.length + sources.length}`);
+  });
+
+  const files = new Map<string, FaceFile>();
+  const broken = new Map<string, string>();
+  for (const u of srcs) {
+    if (!existsSync(cachedFontFile(u))) continue;
+    try {
+      const f = readFontFile(readFileSync(cachedFontFile(u)));
+      files.set(u, { cps: f.cps, weight: f.weight, wght: f.wght, names: f.families, licenseText: f.licenseText });
+    } catch (err) {
+      broken.set(u, (err as Error).message);
+    }
+  }
+
+  const reports = list.map(({ group, pair }): PairReport => {
+    const problems = pairProblems(pair);
+    const notes: string[] = [];
+    for (const f of pair.faces ?? []) {
+      const where = `${f.family}(${f.weight})`;
+      const s = net.file.get(f.src)?.status;
+      if (s !== 200) problems.push(`${where} 주소 ${s} — ${f.src}`);
+      if (broken.has(f.src)) problems.push(`${where} 파일을 못 읽는다 — ${broken.get(f.src)}`);
+      if (!f.source || o.offline) continue;
+      const lic = net.text.get(f.source);
+      if (lic?.status !== 200) {
+        problems.push(`${where} 라이선스 글 주소 ${lic?.status} — ${f.source}`);
+        continue;
+      }
+      const v = licenseVerdict(f, lic.text ?? "", files.get(f.src)?.licenseText ?? "");
+      if (v.problem) problems.push(v.problem);
+      if (v.note) notes.push(v.note);
+    }
+    const ready = (pair.faces ?? []).length > 0 && pair.faces.every((f) => files.has(f.src));
+    const m = ready ? measurePair(pair, files) : null;
+    return {
+      id: pair.id,
+      group,
+      name: pair.name,
+      ok: false,
+      ...(m ? { hangul: m.hangul, syllables: m.syllables, boldest: m.boldest } : {}),
+      licenses: [...new Set((pair.faces ?? []).map((f) => f.license))],
+      problems: [...problems, ...(m?.problems ?? [])],
+      notes: [...notes, ...(m?.notes ?? [])],
+    };
+  });
+
+  if (o.render !== false) {
+    const todo = list.filter(({ pair }) => pair.faces?.length && pair.faces.every((f) => files.has(f.src)));
+    log(`  크롬으로 견본 찍기 — 짝 ${todo.length}`);
+    const browser = await launch();
+    try {
+      const context = await browser.newContext({ deviceScaleFactor: 1 });
+      await serveCached(context);
+      const queue = [...todo];
+      let n = 0;
+      await Promise.all(
+        Array.from({ length: Math.min(4, todo.length) }, async () => {
+          const page = await context.newPage();
+          for (let x = queue.shift(); x; x = queue.shift()) {
+            const r = reports.find((y) => y.id === x.pair.id)!;
+            r.problems.push(...judgeRender(x.pair, files, await renderPair(page, x.pair)));
+            if (++n % 20 === 0) log(`  찍음 ${n}/${todo.length}`);
+          }
+        }),
+      );
+    } finally {
+      await browser.close();
+    }
+  }
+  for (const r of reports) r.ok = !r.problems.length;
+  return reports;
+}
+
+const ORIGIN = "https://kf-fonts.local/";
+const MIME: Record<string, string> = { woff2: "font/woff2", woff: "font/woff", ttf: "font/ttf", otf: "font/otf" };
+
+/** 글꼴 주소는 캐시 파일로, 견본 쪽은 빈 문서로 — 크롬이 따로 받지 않아 같은 파일을 본다 */
+async function serveCached(context: BrowserContext): Promise<void> {
+  await context.route("**/*", (route) => {
+    const url = route.request().url();
+    if (url.startsWith(ORIGIN)) return route.fulfill({ contentType: "text/html; charset=utf-8", body: "<!doctype html><meta charset=utf-8><body></body>" });
+    const path = cachedFontFile(url);
+    if (!existsSync(path)) return route.abort();
+    const ext = /\.(\w+)$/.exec(path)?.[1] ?? "woff2";
+    return route.fulfill({ body: readFileSync(path), headers: { "content-type": MIME[ext] ?? "application/octet-stream", "access-control-allow-origin": "*" } });
+  });
+}
+
+export interface Rendered {
+  loadErrors: { family: string; weight: string; error: string }[];
+  lines: RenderLine[];
+}
+
+/** 짝 하나를 빈 문서에 — face 를 하나씩 받아 실패를 그 face 에 붙이고, 줄마다 크롬이 고른 글꼴(CDP)·먹 양·두부 글자를 잰다 */
+async function renderPair(page: Page, p: FontPair): Promise<Rendered> {
+  await page.goto(ORIGIN);
+  const uses = stackUses(p);
+  const spans = uses.flatMap((u) => (Object.keys(FONT_SAMPLE) as SampleLine[]).map((line) => ({ stack: u.stack, css: u.css, weight: u.weight, line, text: FONT_SAMPLE[line] })));
+  const inPage = await page.evaluate(
+    async ({ faces, spans }) => {
+      const loadErrors: { family: string; weight: string; error: string }[] = [];
+      await Promise.all(
+        faces.map(async (f) => {
+          const ff = new FontFace(f.family, `url("${f.src}")`, { weight: f.weight ?? "100 900", display: "block" });
+          document.fonts.add(ff);
+          await ff.load().catch((e: Error) => loadErrors.push({ family: f.family, weight: f.weight ?? "", error: String(e?.message ?? e) }));
+        }),
+      );
+      const canvas = document.createElement("canvas");
+      const ctx = canvas.getContext("2d", { willReadFrequently: true })!;
+      const paint = (font: string, text: string, w: number, h: number): Uint8ClampedArray => {
+        canvas.width = w;
+        canvas.height = h;
+        ctx.font = font;
+        ctx.textBaseline = "middle";
+        ctx.fillText(text, 4, h / 2);
+        return ctx.getImageData(0, 0, w, h).data;
+      };
+      const inkOf = (d: Uint8ClampedArray) => {
+        let n = 0;
+        for (let i = 3; i < d.length; i += 4) if (d[i] > 40) n++;
+        return n;
+      };
+      const measured = spans.map((s, i) => {
+        const el = document.createElement("div");
+        el.dataset.k = String(i);
+        el.style.cssText = `font-family: ${s.css}; font-weight: ${s.weight}; font-size: 48px; white-space: pre; line-height: 1.4`;
+        el.textContent = s.text;
+        document.body.append(el);
+        const font = `${s.weight} 48px ${s.css}`;
+        const notdef = paint(font, "\u{10FFFD}", 80, 80).join(",");
+        const tofu = [...new Set([...s.text].filter((ch) => ch !== " "))].filter((ch) => {
+          const d = paint(font, ch, 80, 80);
+          return inkOf(d) > 0 && d.join(",") === notdef;
+        });
+        return { ink: inkOf(paint(font, s.text, 1600, 90)), tofu };
+      });
+      return { loadErrors, measured };
+    },
+    { faces: p.faces.map(({ family, src, weight }) => ({ family, src, weight })), spans: spans.map(({ css, weight, text }) => ({ css, weight, text })) },
+  );
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    await cdp.send("DOM.enable");
+    await cdp.send("CSS.enable");
+    const { root } = await cdp.send("DOM.getDocument");
+    const lines: RenderLine[] = [];
+    for (const [i, s] of spans.entries()) {
+      const { nodeId } = await cdp.send("DOM.querySelector", { nodeId: root.nodeId, selector: `[data-k="${i}"]` });
+      const { fonts } = await cdp.send("CSS.getPlatformFontsForNode", { nodeId });
+      lines.push({ stack: s.stack, weight: s.weight, line: s.line, fonts: fonts.map((f) => ({ family: f.familyName, custom: f.isCustomFont, glyphs: f.glyphCount })), ...inPage.measured[i] });
+    }
+    return { loadErrors: inPage.loadErrors, lines };
+  } finally {
+    await cdp.detach();
+  }
+}
+
+/** 찍은 것을 cmap 으로 예상한 것과 댄다 — 투명·두부·시스템으로 떨어짐·다른 face 로 떨어짐 */
+export function judgeRender(p: FontPair, files: Map<string, FaceFile>, r: Rendered): string[] {
+  const bad = r.loadErrors.map((e) => `${e.family}(${e.weight}) 를 크롬이 못 읽는다 — ${e.error}`);
+  if (bad.length) return bad;
+  for (const l of r.lines) {
+    const where = `${l.stack}@${l.weight} ${l.line} 줄`;
+    const text = FONT_SAMPLE[l.line];
+    const css = p[l.stack as "display"];
+    const namesOf = (ch: string) => {
+      const f = faceForChar(p, css, l.weight, ch.codePointAt(0)!, files);
+      return f ? (files.get(f.src)?.names ?? []) : [];
+    };
+    const expected = [...new Set([...text].filter((ch) => ch !== " "))].map((ch) => namesOf(ch));
+    const allowed = new Set([...expected.flat(), ...namesOf(" "), ...stackFamilies(css).slice(0, 1).flatMap((fam) => p.faces.filter((f) => f.family === fam).flatMap((f) => files.get(f.src)?.names ?? []))]);
+    if (!l.ink) bad.push(`${where} 이 투명하게 찍힌다`);
+    if (l.tofu.length) bad.push(`${where} ${l.tofu.join("")} 가 두부로 찍힌다`);
+    for (const f of l.fonts) {
+      if (!f.custom) bad.push(`${where} 이 시스템 글꼴 ${f.family} 로 떨어진다(글리프 ${f.glyphs})`);
+      else if (!allowed.has(f.family)) bad.push(`${where} 이 예상 밖 글꼴 ${f.family} 로 찍힌다(글리프 ${f.glyphs})`);
+    }
+    const used = new Set(l.fonts.filter((f) => f.custom).map((f) => f.family));
+    const missed = [...new Set(expected.filter((names) => names.length && !names.some((n) => used.has(n))).map((names) => names[0]))];
+    if (missed.length) bad.push(`${where} 에서 ${missed.join("·")} 가 안 쓰였다 — 다른 글꼴로 떨어졌다`);
+  }
+  return bad;
+}
+
+const GENERIC = new Set(["serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace", "ui-rounded", "emoji", "math", "fangsong"]);
+const esc = (s: string) => s.replace(/[&<>"]/g, (c) => `&${{ "&": "amp", "<": "lt", ">": "gt", '"': "quot" }[c]};`);
+
+/** 짝 견본 격자 한 장 — 사람이 눈으로 고르는 용. 같은 이름인데 파일이 다른 face 는 짝끼리 섞이지 않게 이름을 갈라 싣는다 */
+export async function fontSheet(list: { group: string; pair: FontPair }[], out: string, o: { log?: (s: string) => void } = {}): Promise<void> {
+  const log = o.log ?? (() => {});
+  const missing = [...new Set(list.flatMap(({ pair }) => pair.faces.map((f) => f.src)))].filter((u) => !existsSync(cachedFontFile(u)));
+  if (missing.length) {
+    log(`  글꼴 받기 ${missing.length}`);
+    await pool(missing, 8, (u) => get(u, "file"));
+  }
+  const alias = new Map<string, string>();
+  const sigs = new Map<string, string[]>();
+  const aliasOf = (p: FontPair, family: string) => {
+    const sig = p.faces.filter((f) => f.family === family).map((f) => `${f.weight}=${f.src}`).sort().join("|");
+    const seen = sigs.get(family) ?? [];
+    if (!seen.includes(sig)) sigs.set(family, [...seen, sig]);
+    const k = sigs.get(family)!.indexOf(sig);
+    const name = k ? `${family} #${k + 1}` : family;
+    for (const f of p.faces.filter((x) => x.family === family)) alias.set(`${name}\n${f.src}\n${f.weight}`, name);
+    return name;
+  };
+  const stackOf = (p: FontPair, css: string) =>
+    stackFamilies(css)
+      .map((fam) => (p.faces.some((f) => f.family === fam) ? `"${aliasOf(p, fam)}"` : GENERIC.has(fam) ? fam : `"${fam}"`))
+      .join(", ");
+  const cards = list.map(({ group, pair: p }) => {
+    const display = stackOf(p, p.monoAll ? p.mono : p.display);
+    const sans = stackOf(p, p.monoAll ? p.mono : p.sans);
+    const mono = stackOf(p, p.mono);
+    const meta = `${p.hangul ?? "?"} · ${[...new Set(p.faces.map((f) => f.license))].join(",")} · ${p.tags.join(" ")}`;
+    return `<section><header><b>${esc(p.id)}</b><span>${esc(group)}</span></header>
+<p class=t style='font-family:${display};font-weight:${p.weightDisplay};letter-spacing:${p.tracking}'>오늘의 제목 Title 2026</p>
+<p class=b style='font-family:${sans};font-weight:${p.weightBody}'>${esc(p.ko)} — Sphinx of black quartz ₩12,000 · 45% → 0123456789</p>
+<p class=m style='font-family:${mono};font-weight:${p.weightBody}'>const 값 = 42; // 결과 → 1,234</p>
+<footer>${esc(p.name)} · ${esc(meta)}</footer></section>`;
+  });
+  const faces = [...alias.entries()].map(([k, name]) => {
+    const [, src, weight] = k.split("\n");
+    return { family: name, src, weight };
+  });
+  const cols = Math.min(8, Math.max(3, Math.ceil(list.length / 40)));
+  const html = `<!doctype html><meta charset=utf-8><style>
+  body { margin: 0; padding: 28px; background: #efece6; color: #171717; font: 14px/1.35 -apple-system, "Apple SD Gothic Neo", sans-serif; }
+  h1 { font-size: 20px; margin: 0 0 18px; font-weight: 600; }
+  main { display: grid; grid-template-columns: repeat(${cols}, 520px); gap: 14px; }
+  section { background: #fff; border: 1px solid #d9d4ca; padding: 14px 18px 12px; overflow: hidden; }
+  header { display: flex; justify-content: space-between; font: 12px/1 ui-monospace, monospace; color: #6b655c; }
+  header b { color: #171717; }
+  p { margin: 10px 0 0; white-space: nowrap; overflow: hidden; text-overflow: clip; }
+  .t { font-size: 44px; line-height: 1.15; }
+  .b { font-size: 19px; white-space: normal; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }
+  .m { font-size: 17px; color: #3a3631; }
+  footer { margin-top: 10px; font-size: 12px; color: #8a8378; white-space: nowrap; overflow: hidden; }
+</style><h1>kasaframe 글꼴 짝 ${list.length} — ${esc([...new Set(list.map((x) => x.group))].join(" · "))}</h1><main>${cards.join("")}</main>`;
+  const browser = await launch();
+  try {
+    const context = await browser.newContext({ deviceScaleFactor: 1, viewport: { width: cols * 534 + 56, height: 900 } });
+    await serveCached(context);
+    const page = await context.newPage();
+    await page.goto(ORIGIN);
+    const failed = await page.evaluate(
+      async ({ html, faces }) => {
+        document.open();
+        document.write(html);
+        document.close();
+        const bad: string[] = [];
+        await Promise.all(
+          faces.map(async (f) => {
+            const ff = new FontFace(f.family, `url("${f.src}")`, { weight: f.weight, display: "block" });
+            document.fonts.add(ff);
+            await ff.load().catch(() => bad.push(`${f.family}(${f.weight})`));
+          }),
+        );
+        await document.fonts.ready;
+        return bad;
+      },
+      { html, faces },
+    );
+    if (failed.length) log(`  못 실은 face: ${failed.join(", ")}`);
+    mkdirSync(join(out, ".."), { recursive: true });
+    await page.screenshot({ path: out, fullPage: true });
+  } finally {
+    await browser.close();
+  }
+}
+
+const NOTICE_HEAD = "글꼴 짝 — packages/themes/kit/fonts.json · kit/fonts/<무리>.json (kf fonts notice --write 가 이 절을 짓는다)";
+const RULE = "-".repeat(70);
+
+/** NOTICE 의 글꼴 절 — 글꼴 이름마다 라이선스와 라이선스 글 한 줄 */
+export function noticeSection(pairs: FontPair[]): string {
+  const rows = new Map<string, [string, string, string]>();
+  for (const f of pairs.flatMap((p) => p.faces)) rows.set(`${f.family}\n${f.license}\n${f.source}`, [f.family, f.license, f.source]);
+  const list = [...rows.values()].sort((a, b) => a[0].localeCompare(b[0]) || a[2].localeCompare(b[2]));
+  const w = Math.max(...list.map((r) => r[0].length));
+  const lw = Math.max(...list.map((r) => r[1].length));
+  return [
+    RULE,
+    NOTICE_HEAD,
+    "글꼴 파일은 싣지 않는다 — 영상을 구울 때 판을 박은 주소(jsdelivr gh@커밋·npm@판)에서 받는다. 모두 상업 이용·영상·",
+    "웹 임베딩이 허용된 라이선스이고 출처 표기 의무가 없다. kf fonts check 가 라이선스 글이나 파일 name 13 에서 그 문구를 대 본다.",
+    `짝 ${pairs.length} · 글꼴 ${new Set(list.map((r) => r[0])).size} — 이름 · 라이선스 · 라이선스 글`,
+    "",
+    ...list.map(([fam, lic, src]) => `  ${fam.padEnd(w)}  ${lic.padEnd(lw)}  ${src}`),
+    "",
+  ].join("\n");
+}
+
+/** NOTICE 글에서 글꼴 절을 갈아 끼운다 — 없으면 끝에 붙인다 */
+export function replaceNotice(notice: string, section: string): string {
+  const lines = notice.split("\n");
+  const head = lines.indexOf(NOTICE_HEAD);
+  if (head < 0) return `${notice.trimEnd()}\n\n${section}`;
+  const from = lines[head - 1] === RULE ? head - 1 : head;
+  const next = lines.findIndex((l, i) => i > head && l === RULE);
+  return [...lines.slice(0, from), ...section.split("\n").slice(0, -1), ...(next < 0 ? [""] : lines.slice(next))].join("\n");
+}

package/packages/cli/src/kf.ts

@@ -3,6 +3,7 @@ import { readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { fontsMissing } from "@kasaframe/jizura/install";
 import type { Command } from "./command.ts";
+import { updateGate } from "./update.ts";
 
 const commandsDir = fileURLToPath(new URL("./commands/", import.meta.url));
 
@@ -42,6 +43,10 @@ async function main(argv: string[]): Promise<number> {
     console.log(`kf ${name} — ${cmd.summary}\n\n${cmd.usage ?? ""}`.trimEnd());
     return 0;
   }
+  if (name !== "update") {
+    const relaunched = await updateGate(argv).catch(() => null);
+    if (relaunched !== null) return relaunched;
+  }
   return (await cmd.run(rest)) ?? 0;
 }
 

package/packages/cli/src/mix.ts

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { audioDuration, findSilences } from "@kasaframe/gen";
+import { laySfx, writeFloatWav, type SfxBank, type SfxHit, type SfxPlaced, type SfxSettings } from "./sfx.ts";
 
 // 내레이션 + 곡 섞기 — kf.json 에 audio(섞기 값)가 있는 프로젝트만. 없으면 렌더는 예전처럼 곡만 얹는다
 export interface AudioMix {
@@ -12,6 +13,17 @@ export interface AudioMix {
   fadeOut: number;
 }
 
+// kf.json 에 audio 가 없는데 효과음을 깔 때 — 곡은 그대로(끝 페이드 없이) 두고 전체만 쇼츠·설명과 같은 크기로
+export const SFX_AUDIO: AudioMix = { musicDb: -20, duck: true, lufs: -14, truePeak: -1.5, fadeOut: 0 };
+
+/** 효과음 층 — 깔 소리와 결. 섞은 뒤 measured 에 잰 크기·깐 소리마다 가려짐을 적는다 */
+export interface SfxMix {
+  hits: SfxHit[];
+  settings: SfxSettings;
+  bank: Pick<SfxBank, "file">;
+  measured?: { bed: number | null; sfx: number; lift: number; hits: SfxPlaced[] };
+}
+
 // 목소리를 먼저 이 크기로 맞춘다 — 덕킹 문턱이 목소리 크기에 묶여 있어서 공급자마다 다른 크기를 한 자리로
 const VOICE_LUFS = -18;
 // 덕킹 두 입력의 프레임 크기를 맞춘다 — 목소리 wav(1024)·곡 mp3(1152) 프레임이 도착 차례에 따라 sidechaincompress 결과가
@@ -29,6 +41,25 @@ function ffmpeg(args: string[]): Promise<string> {
   });
 }
 
+// 섞은 판을 왼·오 실수 둘로 — 효과음이 둘레 곡 크기를 재고, 그 순간 곡을 누르고, 그 위에 얹는다
+async function stereo(path: string): Promise<[Float32Array, Float32Array]> {
+  return new Promise((done, fail) => {
+    const p = spawn("ffmpeg", ["-v", "error", "-i", path, "-ac", "2", "-ar", "48000", "-f", "f32le", "-"]);
+    const parts: Buffer[] = [];
+    p.stdout.on("data", (b: Buffer) => parts.push(b));
+    p.on("error", fail);
+    p.on("close", (code) => {
+      if (code !== 0) return fail(new Error(`ffmpeg 풀기 실패(${code}): ${path}`));
+      const b = Buffer.concat(parts);
+      const x = new Float32Array(b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength));
+      const L = new Float32Array(x.length >> 1);
+      const R = new Float32Array(x.length >> 1);
+      for (let i = 0; i < L.length; i++) [L[i], R[i]] = [x[2 * i], x[2 * i + 1]];
+      done([L, R]);
+    });
+  });
+}
+
 // 통합 크기(LUFS) — 무음은 게이트가 빼서 말·곡이 실제로 울리는 곳만 잰다
 async function loudness(input: string[], filter = ""): Promise<number> {
   const err = await ffmpeg([...input, "-af", `${filter ? `${filter},` : ""}ebur128=framelog=quiet`, "-f", "null", "-"]);
@@ -64,8 +95,19 @@ export function mixSettings(dir: string): { audio: AudioMix; voice?: string } |
 }
 
 // 영상 [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> {
+export async function mixAudio(src: Sources, o: { audio: AudioMix; from: number; dur: number; total: number; out: string; sfx?: SfxMix }): Promise<string> {
   const { audio } = o;
+  const sfx = o.sfx?.hits.length ? o.sfx : undefined;
+  // 곡도 목소리도 없으면 효과음만 — 빈 판 위에(둘레 곡이 없으니 크기는 바닥 기준, 누를 것도 없다). 정규화 없이
+  if (!src.voice && !src.music && sfx) {
+    const n = Math.round(o.dur * 48000);
+    const bed: [Float32Array, Float32Array] = [new Float32Array(n), new Float32Array(n)];
+    const { stem, placed } = laySfx(bed, sfx.hits, sfx.bank, sfx.settings, { from: o.from, voice: false });
+    const raw = writeFloatWav(o.out.replace(/\.wav$/, ".with.wav"), bed);
+    await ffmpeg(["-i", raw, "-c:a", "pcm_s16le", o.out]);
+    sfx.measured = { bed: null, sfx: await loudness(["-i", writeFloatWav(o.out.replace(/\.wav$/, ".sfx.wav"), [stem])]), lift: 0, hits: placed };
+    return o.out;
+  }
   const seg = (path: string, at: number) => ["-ss", at.toFixed(6), "-t", o.dur.toFixed(6), "-i", path];
   const inputs: string[] = [];
   const chains: string[] = [];
@@ -102,11 +144,31 @@ export async function mixAudio(src: Sources, o: { audio: AudioMix; from: number;
   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]);
+  // 효과음은 곡·목소리를 다 섞은 판 위에 — 소리마다 둘레 곡 크기에 맞추고 그 순간 곡을 짧게 눌러 자리를 낸다(목소리가 있으면 더 낮게)
+  let norm = pre;
+  if (sfx) {
+    const bedLufs = await loudness(["-i", pre]);
+    const bed = await stereo(pre);
+    const { stem, placed } = laySfx(bed, sfx.hits, sfx.bank, sfx.settings, { from: o.from, voice: !!src.voice });
+    norm = writeFloatWav(o.out.replace(/\.wav$/, ".with.wav"), bed);
+    const stemFile = writeFloatWav(o.out.replace(/\.wav$/, ".sfx.wav"), [stem]);
+    sfx.measured = { bed: bedLufs, sfx: await loudness(["-i", stemFile]), lift: (await loudness(["-i", norm])) - bedLufs, hits: placed };
+  }
   // 두 번 잰다 — 한 번에 loudnorm 을 걸면 동적 모드로 들어가 덕킹 모양이 뭉개진다. 잰 값을 주고 linear 로 한 번에 올린다
-  const err = await ffmpeg(["-i", pre, "-af", `loudnorm=I=${audio.lufs}:TP=${audio.truePeak}:LRA=11:print_format=json`, "-f", "null", "-"]);
+  const err = await ffmpeg(["-i", norm, "-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]);
+  await ffmpeg(["-i", norm, "-af", `${ln},aresample=48000`, "-c:a", "pcm_s16le", o.out]);
+  // 꼭대기가 0dBTP 가까운 곡은 linear 로 못 올려 동적 모드로 빠지고 목표보다 0.5LU 넘게 커졌다 — 효과음을 깐 판만 넘친 만큼 내린다
+  // (내리면 꼭대기도 내려가 truePeak 를 안 넘는다. 끈 판은 예전과 같은 소리로 둔다)
+  if (sfx) {
+    const got = await loudness(["-i", o.out]);
+    if (got - audio.lufs > 0.3) {
+      const fit = o.out.replace(/\.wav$/, ".fit.wav");
+      await ffmpeg(["-i", o.out, "-af", `volume=${(audio.lufs - got).toFixed(2)}dB`, "-c:a", "pcm_s16le", fit]);
+      renameSync(fit, o.out);
+    }
+  }
   return o.out;
 }
 

package/packages/cli/src/segments.ts

@@ -14,7 +14,7 @@ import { repoRoot } from "./serve.ts";
 // 조각 꼴(인코딩·해시 재료)이 바뀌면 올린다 — 옛 조각을 다시 쓰지 않게
 const VERSION = "seg-1";
 // 화면을 안 바꾸는 kf.json 칸 — 소리·굽기 기본값·검사 예외. 굽기 값(모션 블러)은 KeyOpts 로 따로 들어간다
-const NOT_FRAMES = new Set(["scenes", "music", "audio", "voice", "narration", "render", "check"]);
+const NOT_FRAMES = new Set(["scenes", "music", "audio", "sfx", "voice", "narration", "render", "check"]);
 const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
 
 export interface SceneEntry {