kasaframe 0.1.5 → 0.1.7

package/packages/cli/src/sfx.ts

@@ -0,0 +1,429 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SFX_ROLES, type SfxRole } from "@kasaframe/core";
+import { loadTheme } from "@kasaframe/themes";
+
+// 효과음 — 장면 움직임이 남긴 소리 자리(__kf.events 의 sfx)를 뜻 있는 것만 적게 고르고, 테마가 고른 결의 파일을 곡 둘레 크기에 맞춰 깔고
+// 그 순간 곡을 짧게 눌러 자리를 낸다. 같은 자리·같은 설정이면 같은 소리 — 고르기·음높이 흔들기는 시각과 역할의 해시로만 정한다
+
+const SR = 48000;
+
+export interface SfxSettings {
+  /** 소리 결 — sfx/tags.json 의 sets */
+  set: string;
+  /** 둘레 곡(소리 자리 앞뒤 0.2초) 크기 대비 dB — 0 이면 곡과 비슷하게 */
+  db: number;
+  /** 1초에 몇 개까지(2초 창으로 센다 — 0.5 면 2초에 하나) */
+  perSec: number;
+  only: SfxRole[] | null;
+  /** 목소리가 있으면 더 낮춘다 */
+  voiceDb: number;
+  /** 잔소리(낱낱이 나타남·숫자 째깍·타자)도 깐다 — 기본은 뜻 있는 자리만 */
+  chatter: boolean;
+  /** 소리마다 곡을 이만큼(dB) 짧게 눌러 자리를 낸다 */
+  duck: number;
+}
+
+const DEFAULT: SfxSettings = { set: "ui", db: -2, perSec: 1, only: null, voiceDb: -4, chatter: false, duck: 3 };
+
+// 역할마다 결 크기 위아래(db)·밀도가 넘칠 때 남기는 차례(prio 높은 것부터)·저역을 걷는 곳(Hz — 킥·베이스와 안 겹치게, 드롭 쿵만 낮게 둔다)
+export const ROLE: Record<SfxRole, { db: number; prio: number; cut: number }> = {
+  drop: { db: 2, prio: 10, cut: 60 },
+  end: { db: 1, prio: 9, cut: 250 },
+  whoosh: { db: -1, prio: 8, cut: 250 },
+  land: { db: 0, prio: 7, cut: 150 },
+  stick: { db: 0, prio: 6, cut: 200 },
+  burst: { db: 0, prio: 6, cut: 250 },
+  hop: { db: -1, prio: 5, cut: 200 },
+  select: { db: -1, prio: 4, cut: 250 },
+  appear: { db: -2, prio: 3, cut: 250 },
+  tick: { db: -4, prio: 2, cut: 300 },
+  type: { db: -4, prio: 1, cut: 300 },
+};
+
+/** 같은 역할은 이 안에 하나 */
+const SAME_ROLE = 0.1;
+/** 아무 소리끼리 이만큼 띄운다 — 붙어 나면 하나로 뭉개진다 */
+const MIN_GAP = 0.25;
+/** 드롭 앞뒤 이 안은 드롭만 */
+const DROP_CLEAR = 0.35;
+/** 밀도를 세는 창(초) */
+const WINDOW = 2;
+/** 가려짐 목표 — 소리 대역에서 소리 순간에 효과음이 곡보다 이만큼(dB) 위. 모자라면 BOOST 까지 더 키운다 */
+const SMR_TARGET = 4;
+const BOOST = 6;
+/**
+ * 소리가 차지하는 대역 후보(Hz) — 소리마다 제 가장 센 대역에서 10dB 안쪽인 대역들(그 소리가 실제로 차지하는 곳)을 잡고, 그중 곡을 가장 넘는 대역에서
+ * 가려짐을 잰다(귀는 소리가 곡을 넘는 대역에서 그 소리를 듣는다). 낮은 몸에 2–6kHz 어택을 얹은 소리는 어택 대역이 잡힌다
+ */
+export const BANDS: readonly [number, number][] = [
+  [40, 150],
+  [150, 600],
+  [600, 2000],
+  [2000, 6000],
+  [6000, 12000],
+];
+
+export const sfxDir = (): string => process.env.KF_SFX_DIR || fileURLToPath(new URL("../../../sfx/", import.meta.url));
+
+interface BankFile {
+  path: string;
+  lead: number;
+  level: number;
+}
+
+export interface SfxBank {
+  dir: string;
+  sets: string[];
+  file(set: string, role: SfxRole): BankFile | null;
+}
+
+export function loadBank(dir = sfxDir()): SfxBank {
+  const tags = JSON.parse(readFileSync(join(dir, "tags.json"), "utf8")) as { sets: Record<string, unknown>; files: Record<string, { set: string; role: string; lead: number; level: number }> };
+  const by = new Map(Object.entries(tags.files).map(([rel, f]) => [`${f.set}/${f.role}`, { path: join(dir, rel), lead: f.lead, level: f.level }]));
+  return { dir, sets: Object.keys(tags.sets), file: (set, role) => by.get(`${set}/${role}`) ?? null };
+}
+
+const isRole = (r: unknown): r is SfxRole => (SFX_ROLES as readonly unknown[]).includes(r);
+
+/**
+ * 이 프로젝트의 효과음 설정 — 기본 ← theme.json sfx ← kf.json sfx. 끄면 null.
+ * flag 는 kf render|make --sfx: off 면 끈다, on 이면 kf.json sfx: false 도 이 판만 켠다
+ */
+export function sfxSettings(dir: string, flag?: string): SfxSettings | null {
+  if (flag === "off") return null;
+  type Loose = Partial<Omit<SfxSettings, "only">> & { only?: string[] | null };
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) as { theme?: string; sfx?: false | Loose };
+  if (kf.sfx === false && flag !== "on") return null;
+  let theme: Loose = {};
+  if (kf.theme) {
+    try {
+      theme = loadTheme(kf.theme).sfx ?? {};
+    } catch {}
+  }
+  const over = kf.sfx && typeof kf.sfx === "object" ? kf.sfx : {};
+  const s: Loose & Omit<SfxSettings, "only"> = { ...DEFAULT, ...theme, ...over };
+  const only = s.only ? s.only.filter(isRole) : null;
+  return {
+    set: s.set,
+    db: Number(s.db),
+    perSec: Math.max(0.1, Number(s.perSec)),
+    only: only?.length ? only : null,
+    voiceDb: Number(s.voiceDb),
+    chatter: !!s.chatter,
+    duck: Math.max(0, Number(s.duck)),
+  };
+}
+
+export interface SfxCue {
+  t: number;
+  role: SfxRole;
+  source: string;
+  weight: number;
+  /** 잔소리 — chatter 가 아니면 안 깐다 */
+  minor?: boolean;
+}
+
+/** 페이지가 남긴 기록에서 소리 자리를, 곡의 드롭(beats.json — 영상 0초 기준)은 드롭 쿵으로 */
+export function cuesOf(events: readonly { t: number; kind: string; source: string; name?: string; value?: number; minor?: boolean }[], drops: readonly number[] = []): SfxCue[] {
+  const out: SfxCue[] = [];
+  for (const e of events)
+    if (e.kind === "sfx" && isRole(e.name)) out.push({ t: e.t, role: e.name, source: e.source, weight: Math.min(1, Math.max(0.05, e.value ?? 1)), ...(e.minor ? { minor: true } : {}) });
+  for (const d of drops) out.push({ t: Math.round(d * 1000) / 1000, role: "drop", source: "beats", weight: 1 });
+  return out;
+}
+
+export function projectDrops(dir: string): number[] {
+  try {
+    const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) as { beats?: string };
+    if (!kf.beats) return [];
+    return (JSON.parse(readFileSync(resolve(dir, kf.beats), "utf8")) as { drops?: number[] }).drops ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export interface SfxHit {
+  t: number;
+  role: SfxRole;
+  /** 결 안 역할 파일 — 섞을 때 bank 에서 찾는다 */
+  set: string;
+  /** 역할 크기 + 무게 + 흔들기(dB) */
+  db: number;
+  /** 음높이 배수 — 같은 소리가 줄줄이 나도 기계음처럼 안 들리게 */
+  rate: number;
+}
+
+// 시각·역할 → 0..1 두 개(fnv1a). 같은 자리면 어느 기계에서나 같은 흔들기
+function hash2(key: string): [number, number] {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 0x01000193) >>> 0;
+  const a = (h & 0xffff) / 0x10000;
+  const b = (h >>> 16) / 0x10000;
+  return [a, b];
+}
+
+/**
+ * 소리 자리를 깔 소리로 — 잔소리(chatter 가 아니면)·결에 없는 역할·only 밖 역할은 빼고, 같은 역할은 SAME_ROLE 안에 하나, 차례(ROLE.prio)대로
+ * 드롭 앞뒤를 비우고 MIN_GAP 을 띄우고 아무 2초 창에 perSec×2 개(적어도 하나)까지 남긴다. 결과는 시각 차례
+ */
+export function placeSfx(cues: readonly SfxCue[], s: SfxSettings, bank: Pick<SfxBank, "file">, o: { from: number; to: number }): SfxHit[] {
+  const ok = cues
+    .filter((c) => c.t >= o.from - 1e-9 && c.t < o.to - 1e-9 && (s.chatter || !c.minor) && (!s.only || s.only.includes(c.role)) && bank.file(s.set, c.role))
+    .sort((a, b) => a.t - b.t || ROLE[b.role].prio - ROLE[a.role].prio || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0));
+  const merged: SfxCue[] = [];
+  const last = new Map<SfxRole, SfxCue>();
+  for (const c of ok) {
+    const prev = last.get(c.role);
+    if (prev && c.t - prev.t < SAME_ROLE) {
+      prev.weight = Math.max(prev.weight, c.weight);
+      continue;
+    }
+    const m = { ...c };
+    merged.push(m);
+    last.set(c.role, m);
+  }
+  const order = [...merged].sort((a, b) => ROLE[b.role].prio - ROLE[a.role].prio || a.t - b.t);
+  const kept: SfxCue[] = [];
+  const most = Math.max(1, Math.round(s.perSec * WINDOW));
+  // t 를 품은 어느 창 [w, w+WINDOW) 이 most 를 넘나 — 가장 붐비는 창은 t 앞 WINDOW 안의 소리(t 포함)에서 시작한다
+  const crowded = (t: number) => {
+    const xs = [...kept.map((k) => k.t), t];
+    return xs.filter((w) => w <= t && w > t - WINDOW).some((w) => xs.filter((x) => x >= w && x < w + WINDOW).length > most);
+  };
+  for (const c of order) {
+    if (kept.some((k) => Math.abs(k.t - c.t) < MIN_GAP)) continue;
+    if (c.role !== "drop" && kept.some((k) => k.role === "drop" && Math.abs(k.t - c.t) < DROP_CLEAR)) continue;
+    if (crowded(c.t)) continue;
+    kept.push(c);
+  }
+  return kept
+    .sort((a, b) => a.t - b.t)
+    .map((c) => {
+      const [h1, h2] = hash2(`${c.role}|${c.t.toFixed(3)}`);
+      return { t: c.t, role: c.role, set: s.set, db: Math.round((ROLE[c.role].db + 20 * Math.log10(c.weight) + (h1 - 0.5) * 2) * 100) / 100, rate: Math.round((1 + (h2 - 0.5) * 0.06) * 10000) / 10000 };
+    });
+}
+
+// --- 소리 다루기: 2차 버터워스 거르개(RBJ) — 같은 입력이면 같은 출력
+
+type Biquad = [number, number, number, number, number];
+
+function biquad(kind: "lp" | "hp", f: number): Biquad {
+  const w = (2 * Math.PI * f) / SR;
+  const c = Math.cos(w);
+  const a = Math.sin(w) / Math.SQRT2;
+  const b0 = kind === "lp" ? (1 - c) / 2 : (1 + c) / 2;
+  const b1 = kind === "lp" ? 1 - c : -(1 + c);
+  const a0 = 1 + a;
+  return [b0 / a0, b1 / a0, b0 / a0, (-2 * c) / a0, (1 - a) / a0];
+}
+
+function filter(x: Float32Array, q: Biquad): Float32Array {
+  const [b0, b1, b2, a1, a2] = q;
+  const y = new Float32Array(x.length);
+  let x1 = 0;
+  let x2 = 0;
+  let y1 = 0;
+  let y2 = 0;
+  for (let i = 0; i < x.length; i++) {
+    const v = b0 * x[i] + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
+    x2 = x1;
+    x1 = x[i];
+    y2 = y1;
+    y1 = v;
+    y[i] = v;
+  }
+  return y;
+}
+
+/** 대역 [lo, hi] 만 — 높은·낮은 거르개를 두 번씩(4차) */
+function band(x: Float32Array, [lo, hi]: readonly [number, number]): Float32Array {
+  const h = biquad("hp", lo);
+  const l = biquad("lp", Math.min(hi, SR * 0.45));
+  return filter(filter(filter(filter(x, h), h), l), l);
+}
+
+// [a, b) 창 평균 에너지 — 창이 소리 끝·앞을 넘으면 넘은 자리는 0 으로 친다(잘린 길이로 나누면 짧은 소리가 5dB 넘게 부풀었다)
+const energy = (x: Float32Array, a: number, b: number): number => {
+  let e = 0;
+  for (let i = Math.max(0, a); i < Math.min(x.length, b); i++) e += x[i] * x[i];
+  return b > a ? e / (b - a) : 0;
+};
+const db = (e: number): number => 10 * Math.log10(e + 1e-15);
+
+// 100ms 창 RMS 최댓값(dBFS) — tools/sfx/build.ts 의 level 과 같은 잣대
+function peak100(y: Float32Array): number {
+  const win = Math.round(SR * 0.1);
+  let best = 0;
+  for (let i = 0; i < Math.max(1, y.length - win + 1); i += Math.round(SR * 0.01)) best = Math.max(best, energy(y, i, i + win));
+  return db(best);
+}
+
+// sfx/ 의 16비트 모노 wav — tools/sfx/build.ts 가 쓴 꼴만
+const raw = new Map<string, Float32Array>();
+function samples(path: string): Float32Array {
+  const hit = raw.get(path);
+  if (hit) return hit;
+  const b = readFileSync(path);
+  let p = 12;
+  let data: Buffer | null = null;
+  let bits = 16;
+  let channels = 1;
+  while (p + 8 <= b.length) {
+    const id = b.toString("ascii", p, p + 4);
+    const size = b.readUInt32LE(p + 4);
+    if (id === "fmt ") {
+      channels = b.readUInt16LE(p + 10);
+      bits = b.readUInt16LE(p + 22);
+    } else if (id === "data") data = b.subarray(p + 8, p + 8 + size);
+    p += 8 + size + (size & 1);
+  }
+  if (!data || bits !== 16 || channels !== 1) throw new Error(`효과음 파일 꼴이 아니다(16비트 모노 wav): ${path}`);
+  const y = new Float32Array(data.length / 2);
+  for (let i = 0; i < y.length; i++) y[i] = data.readInt16LE(i * 2) / 32768;
+  raw.set(path, y);
+  return y;
+}
+
+interface Voiced {
+  y: Float32Array;
+  /** 파일 시작 → 꼭대기(샘플) */
+  lead: number;
+  level: number;
+  /** 소리가 차지하는 대역들과 그 대역으로 거른 소리 */
+  bands: { band: readonly [number, number]; y: Float32Array }[];
+}
+
+// 음높이를 옮기고(선형 보간) 저역을 걷은 소리 — 크기·대역은 걷은 뒤에 잰다
+const voiced = new Map<string, Voiced>();
+function voice(f: BankFile, rate: number, cut: number): Voiced {
+  const key = `${f.path}|${rate}|${cut}`;
+  const hit = voiced.get(key);
+  if (hit) return hit;
+  const src = samples(f.path);
+  const len = Math.floor((src.length - 1) / rate);
+  const moved = new Float32Array(len);
+  for (let i = 0; i < len; i++) {
+    const x = i * rate;
+    const k = Math.floor(x);
+    moved[i] = src[k] + (src[k + 1] - src[k]) * (x - k);
+  }
+  const hp = biquad("hp", cut);
+  const y = filter(filter(moved, hp), hp);
+  const split = BANDS.map((b) => ({ band: b, y: band(y, b) }));
+  const loud = split.map((x) => db(energy(x.y, 0, x.y.length)));
+  const top = Math.max(...loud);
+  const v = { y, lead: Math.round((f.lead / rate) * SR), level: peak100(y), bands: split.filter((_, i) => loud[i] >= top - 10) };
+  voiced.set(key, v);
+  return v;
+}
+
+export interface SfxPlaced extends SfxHit {
+  /** 둘레 곡 크기(앞뒤 0.2초 RMS, dBFS) */
+  local: number;
+  /** 소리 크기(100ms 창, dBFS) − 둘레 곡 */
+  over: number;
+  /** 가려짐을 잰 대역(Hz) */
+  band: readonly [number, number];
+  /** 그 대역에서 소리 순간(꼭대기 앞 10ms·뒤 90ms) 효과음 ÷ 눌린 곡(dB) */
+  smr: number;
+  /** 가려져서 더 키운 dB */
+  boost: number;
+}
+
+/**
+ * 곡(·목소리)을 섞은 판 bed(스테레오, 영상 from 초가 0)에 효과음을 깐다 — 소리마다
+ * ① 크기: 둘레 곡 크기 + s.db + 역할 크기(목소리가 있으면 voiceDb 더) ② 그 순간 곡을 s.duck dB 짧게(소리 시작 10ms 앞부터 꼭대기 100ms 뒤까지) 눌러 자리를 내고
+ * ③ 소리 대역에서 효과음이 눌린 곡보다 SMR_TARGET 위가 안 되면 BOOST 까지 더 키운다. bed 를 바꿔 쓰고, 깐 소리와 잰 값을 돌려준다
+ */
+export function laySfx(bed: [Float32Array, Float32Array], hits: readonly SfxHit[], bank: Pick<SfxBank, "file">, s: SfxSettings, o: { from: number; voice: boolean }): { stem: Float32Array; placed: SfxPlaced[] } {
+  const [L, R] = bed;
+  const n = L.length;
+  const mono = new Float32Array(n);
+  for (let i = 0; i < n; i++) mono[i] = (L[i] + R[i]) / 2;
+  // 곡이 비었거나 아주 조용한 곳은 판 전체(무음 뺀 400ms 창 평균)에서 12dB 아래를 바닥으로
+  const blocks: number[] = [];
+  for (let i = 0; i + 0.4 * SR <= n; i += 0.1 * SR) {
+    const e = energy(mono, i, i + 0.4 * SR);
+    if (e > 1e-7) blocks.push(e);
+  }
+  const floor = blocks.length ? db(blocks.reduce((x, y) => x + y, 0) / blocks.length) - 12 : -32;
+  const at = (t: number) => Math.round((t - o.from) * SR);
+  const items = hits.flatMap((h) => {
+    const f = bank.file(h.set, h.role);
+    if (!f) return [];
+    const v = voice(f, h.rate, ROLE[h.role].cut);
+    const peak = at(h.t);
+    return [{ h, v, peak, start: peak - v.lead, local: Math.max(floor, db(energy(mono, peak - 0.2 * SR, peak + 0.2 * SR))) }];
+  });
+  // 누르기 — 소리마다 작은 골짜기, 겹치면 깊은 쪽
+  const env = new Float32Array(n).fill(1);
+  const dip = 10 ** (-s.duck / 20);
+  const rampIn = Math.round(0.01 * SR);
+  const rampOut = Math.round(0.04 * SR);
+  for (const it of items) {
+    const a = it.start - rampIn;
+    const b = it.peak + Math.round(0.1 * SR);
+    for (let i = Math.max(0, a - rampIn); i < Math.min(n, b + rampOut); i++) {
+      const k = i < a ? (i - (a - rampIn)) / rampIn : i > b ? 1 - (i - b) / rampOut : 1;
+      env[i] = Math.min(env[i], 1 - (1 - dip) * Math.max(0, Math.min(1, k)));
+    }
+  }
+  const ducked = new Float32Array(n);
+  for (let i = 0; i < n; i++) ducked[i] = mono[i] * env[i];
+  const stem = new Float32Array(n);
+  const placed: SfxPlaced[] = [];
+  const pre = Math.round(0.2 * SR);
+  for (const it of items) {
+    const { h, v } = it;
+    const target = it.local + s.db + h.db + (o.voice ? s.voiceDb : 0);
+    let gain = target - v.level;
+    // 가려짐 — 소리 꼭대기 앞 10ms·뒤 90ms 를 그 소리 대역마다. 곡 쪽은 거르개가 자리 잡게 앞 0.2초부터 걸러 뒤만 잰다
+    const a = it.peak - Math.round(0.01 * SR);
+    const b = it.peak + Math.round(0.09 * SR);
+    const ref = ducked.subarray(Math.max(0, a - pre), Math.min(n, b));
+    const per = v.bands.map((x) => ({
+      band: x.band,
+      smr: db(energy(x.y, v.lead - Math.round(0.01 * SR), v.lead + Math.round(0.09 * SR)) * 10 ** (gain / 10)) - db(energy(band(ref, x.band), a - Math.max(0, a - pre), ref.length)),
+    }));
+    const best = per.reduce((p, q) => (q.smr > p.smr ? q : p));
+    const smr0 = best.smr;
+    const boost = Math.min(BOOST, Math.max(0, SMR_TARGET - smr0));
+    gain += boost;
+    const k = 10 ** (gain / 20);
+    for (let i = Math.max(0, -it.start); i < v.y.length && it.start + i < n; i++) stem[it.start + i] += k * v.y[i];
+    const r = (x: number) => Math.round(x * 10) / 10;
+    placed.push({ ...h, local: r(it.local), over: r(v.level + gain - it.local), band: best.band, smr: r(smr0 + boost), boost: r(boost) });
+  }
+  for (let i = 0; i < n; i++) {
+    L[i] = L[i] * env[i] + stem[i];
+    R[i] = R[i] * env[i] + stem[i];
+  }
+  return { stem, placed };
+}
+
+/** 32비트 실수 wav — 채널을 받은 차례로 엇갈려 쓴다 */
+export function writeFloatWav(path: string, channels: Float32Array[]): string {
+  const c = channels.length;
+  const n = channels[0].length;
+  const body = new Float32Array(n * c);
+  for (let i = 0; i < n; i++) for (let k = 0; k < c; k++) body[i * c + k] = channels[k][i];
+  const data = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+  const head = Buffer.alloc(44);
+  head.write("RIFF", 0);
+  head.writeUInt32LE(36 + data.length, 4);
+  head.write("WAVEfmt ", 8);
+  head.writeUInt32LE(16, 16);
+  head.writeUInt16LE(3, 20);
+  head.writeUInt16LE(c, 22);
+  head.writeUInt32LE(SR, 24);
+  head.writeUInt32LE(SR * 4 * c, 28);
+  head.writeUInt16LE(4 * c, 32);
+  head.writeUInt16LE(32, 34);
+  head.write("data", 36);
+  head.writeUInt32LE(data.length, 40);
+  writeFileSync(path, Buffer.concat([head, data]));
+  return path;
+}

package/packages/core/src/frame.ts

@@ -39,20 +39,22 @@ export function onFrame(fn: (t: number) => void): () => void {
   };
 }
 
-export type MotionEventKind = "pulse" | "shake" | "camera" | "flash" | "move";
+export type MotionEventKind = "pulse" | "shake" | "camera" | "flash" | "move" | "sfx";
 
 /** 검사(kf check)가 style.json 움직임 규칙 위반을 세는 기록. 효과가 0 이 아닌 프레임마다 한 줄 */
 export interface KfMotionEvent {
-  /** 전체 시각(초) — 그 프레임 */
+  /** 전체 시각(초) — 그 프레임. sfx 는 그 소리가 날 시각 */
   t: number;
   kind: MotionEventKind;
   /** 부품 id */
   source: string;
-  /** pulse 0..1, shake 는 px, camera 는 이동량(px 또는 배율 차), flash 0..1, move 1 */
+  /** pulse 0..1, shake 는 px, camera 는 이동량(px 또는 배율 차), flash 0..1, move 1, sfx 는 크기(0..1) */
   value: number;
-  /** move 일 때 움직임 이름(fade·rise·whip …) — 같은 움직임 되풀이를 센다 */
+  /** move 일 때 움직임 이름(fade·rise·whip …) — 같은 움직임 되풀이를 센다. sfx 면 효과음 역할 */
   name?: string;
   scene?: string;
+  /** sfx 만 — 낱낱이 나타남·숫자 째깍·타자 같은 잔소리. 렌더는 기본으로 안 깐다(테마 sfx.chatter 면 깐다) */
+  minor?: boolean;
 }
 
 interface KfEventHost {
@@ -83,6 +85,7 @@ export function emit(e: Omit<KfMotionEvent, "t"> & { t?: number }): void {
   const row: KfMotionEvent = { t, kind: e.kind, source: e.source, value: Math.round(e.value * 1000) / 1000 };
   if (e.name !== undefined) row.name = e.name;
   if (e.scene !== undefined) row.scene = e.scene;
+  if (e.minor) row.minor = true;
   sink().push(row);
 }
 

package/packages/core/src/index.ts

@@ -23,5 +23,7 @@ export { combine, toCss, applyStyle } from "./style.ts";
 export type { Style, CssStyle } from "./style.ts";
 export { setFrameTime, frameTime, onFrame, emit, motionEvents, resetMotionEvents, setFrameSample, frameSample } from "./frame.ts";
 export type { KfMotionEvent, MotionEventKind, FrameSample } from "./frame.ts";
-export { silentBeats, scaleOf, cssVars, fontCss } from "./project.ts";
+export { SFX_ROLES, SFX_LABEL, cue, cueAt, withoutSfx } from "./sfx.ts";
+export type { SfxRole, CueOpts } from "./sfx.ts";
+export { silentBeats, scaleOf, cssVars, fontCss, MAX_FREEZE_SEC, freezeLimits } from "./project.ts";
 export type { CaptionLook, KfMeta, KfStyle, MotionRules, SafeArea, SceneCtx, FontFace, StyleLook } from "./project.ts";

package/packages/core/src/project.ts

@@ -1,4 +1,5 @@
 import { createBeats, type Beats } from "./beats.ts";
+import type { CueOpts, SfxRole } from "./sfx.ts";
 
 export interface KfMeta {
   fps: number;
@@ -36,6 +37,19 @@ export interface MotionRules {
   durations?: { fast: number; base: number; slow: number };
 }
 
+/** 멈춤 기본 기준 — 단 0.1초(60fps 6프레임)도 쉬지 않는다 */
+export const MAX_FREEZE_SEC = 0.1;
+
+/**
+ * 멈춤 기준 — 경고는 틀·style.json 값(틀이 이긴다, 없으면 0.1초), 오류는 그 값과 테마 값(theme.json motion.maxFreezeSec) 중 큰 쪽.
+ * 테마는 늘리기만 한다 — 짚음이 요점에 머물러 화면이 쉬는 세계(OG 측정 화면)가 그 쉼으로 장면을 떨어뜨리지 않게 하되,
+ * 고정 관찰 화면 틀·스타일이 늘린 값(0.5)을 조이지는 못하고, 늘린 만큼도 경고로는 보인다
+ */
+export function freezeLimits(base: number | undefined, theme?: number | null): { warn: number; error: number } {
+  const warn = base ?? MAX_FREEZE_SEC;
+  return { warn, error: Math.max(warn, theme ?? 0) };
+}
+
 export interface FontFace {
   family: string;
   src: string;
@@ -131,6 +145,11 @@ export interface SceneCtx {
   safe: SafeArea;
   /** 프로젝트 assets/ 기준 경로 → 페이지에서 쓸 주소 */
   asset(path: string): string;
+  /**
+   * 효과음 자리 — 장면 시각 at(초)에 그 역할 소리. build 에서 불러도 draw 에서 불러도 된다(같은 자리는 한 번).
+   * 라이브러리 부품(테마 효과·패턴·전환·드롭)은 저절로 남기니, 부품 밖에서 손으로 지은 움직임에만 쓴다
+   */
+  sfx(role: SfxRole, at: number, o?: Omit<CueOpts, "scene">): void;
 }
 
 /** 곡 없는 프로젝트용. pulse 는 늘 0(드롭이 없다), drop(i) 는 던진다 */

package/packages/core/src/sfx.ts

@@ -0,0 +1,70 @@
+import { emit, frameTime } from "./frame.ts";
+
+/**
+ * 효과음 역할 — 소리 결(테마가 고른 묶음)마다 역할 하나에 파일 하나가 있다. 렌더가 이 이름으로 파일을 고르고, 밀도 상한을 넘으면
+ * 앞 역할(드롭·끝·휙…)부터 남긴다
+ */
+export const SFX_ROLES = ["appear", "stick", "land", "hop", "whoosh", "tick", "select", "type", "drop", "burst", "end"] as const;
+
+export type SfxRole = (typeof SFX_ROLES)[number];
+
+export const SFX_LABEL: Record<SfxRole, string> = {
+  appear: "나타남",
+  stick: "톡 붙기",
+  land: "착지",
+  hop: "통 뛰기",
+  whoosh: "휙 전환",
+  tick: "숫자 째깍",
+  select: "짚기 딸깍",
+  type: "타자",
+  drop: "드롭 쿵",
+  burst: "팡 터짐",
+  end: "끝 마무리",
+};
+
+export interface CueOpts {
+  /** 부품 id — 같은 시각·같은 부품은 한 번만 남는다 */
+  source?: string;
+  scene?: string;
+  /** 0..1 — 역할 크기에 곱한다(작은 칸은 작게) */
+  weight?: number;
+  /**
+   * 잔소리 — 낱낱이 나타나는 칸·숫자 째깍·타자처럼 자주 나는 것. 렌더가 기본으로 안 깐다(다 깔면 곡에 묻히고 시끄럽다).
+   * 장면 바뀜·드롭·주인공 착지·짚개가 핵심 값에 닿는 순간만 minor 없이 남긴다
+   */
+  minor?: boolean;
+}
+
+let muted = 0;
+
+/**
+ * 이 안에서 그린 것은 소리 자리를 안 남긴다 — 이음매가 앞뒤 장면을 한 벌 더 지어 다른 시각으로 그릴 때(진짜 장면이 이미 남겼고,
+ * 첫 프레임에 서 있는 뒤 장면은 시작 직후로 보이는 부품이 프레임마다 새 자리를 남긴다)
+ */
+export function withoutSfx<T>(fn: () => T): T {
+  muted++;
+  try {
+    return fn();
+  } finally {
+    muted--;
+  }
+}
+
+// 움직임이 시작하고 이만큼 안에 그린 프레임이 그 자리를 남긴다 — 검사(30fps)·렌더(60fps)·모션 블러 하위 프레임 어느 쪽도 한 번은 이 안에 든다
+const WINDOW = 0.12;
+
+/** 효과음 자리를 전체 시각 t(초)에 남긴다 — 장면 작성자의 ctx.sfx 가 부르는 자리 */
+export function cueAt(role: SfxRole, t: number, o: CueOpts = {}): void {
+  if (muted || !Number.isFinite(t) || t < 0) return;
+  emit({ kind: "sfx", t, name: role, source: o.source ?? role, scene: o.scene, value: o.weight ?? 1, ...(o.minor ? { minor: true } : {}) });
+}
+
+/**
+ * 움직임 부품이 부른다 — since 는 그 움직임이 시작하고 지난 초(그 프레임의 부품 시각 − 시작 시각). 시작 직후 프레임에서
+ * 「지금 프레임 시각 − since」를 소리 자리로 남긴다. 부품이 장면 시각을 얼마나 밀어 받았든 시작 순간의 전체 시각이 나오고,
+ * 어느 프레임이 남기든 같은 값이라 탭을 나눠 찍어도 같은 소리다
+ */
+export function cue(role: SfxRole, since: number, o: CueOpts = {}): void {
+  if (!(since >= 0 && since < WINDOW)) return;
+  cueAt(role, frameTime() - since, o);
+}

package/packages/director/src/assemble.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { themeTransitions } from "@kasaframe/themes";
 import { worldOf } from "@kasaframe/themes/name";
 import { dressSeed, type Dress } from "@kasaframe/motion/menu";
 import { loadTemplate, sceneSkeleton, type Template } from "@kasaframe/plan";
@@ -8,7 +9,7 @@ import { catalog } from "./catalog.ts";
 import { TYPES, type Content, type Scene, type SceneType } from "./content.ts";
 import type { AspectName, Energy, TextPolicy } from "./pattern.ts";
 import { type Entry, type Pick, repick, selectAll, type Slot } from "./select.ts";
-import { type BeatsLite, cyclingText, dressAll, energyOf, seamKinds, seamSpots, type Spot } from "./transitions.ts";
+import { type BeatsLite, cyclingText, dressAll, energyOf, seamKinds, seamsAllowed, seamSpots, type Spot } from "./transitions.ts";
 
 // content.json → 장면 시간표·장면 파일. 두 단계로 나뉜다 — 그 사이에 kf narrate 가 목소리로 장면 길이를 정한다.
 //   1. layout: 내용 장면 + 이음매를 kf.json 에 놓고 들릴 말을 captions.json 에(길이는 어림)
@@ -79,7 +80,8 @@ export function layout(dir: string, content: Content, o: { keepTiming?: boolean
   const seamSec = tplSeams[0]?.sec ?? 1.2;
   // 투영을 맞춰 구운 3D 샷(kf blender 가 kf.json 장면에 남긴 matched)은 다시 놓아도 잃지 않는다
   const matched = new Set<string>((kf.scenes ?? []).filter((s: KfScene) => s.matched).map((s: KfScene) => s.id));
-  const spots = seamSpots(content.scenes.map((s) => s.type), content.scenes.map(spaceOf), tplSeams.length, content.scenes.map((s) => matched.has(s.id)));
+  // 테마가 이음매 전환을 하나도 허용하지 않으면(컷·덮기만) 이음매 장면을 안 넣는다
+  const spots = seamsAllowed(themeTransitions(kf.theme)) ? seamSpots(content.scenes.map((s) => s.type), content.scenes.map(spaceOf), tplSeams.length, content.scenes.map((s) => matched.has(s.id))) : [];
   const taken = new Set(content.scenes.map((s) => s.id));
   const seamIds: string[] = [];
   for (let k = 0; seamIds.length < spots.length; k++) {
@@ -131,6 +133,8 @@ export interface BuildOpts {
   only?: string[];
   /** 사람이 고른 것 — 장면 id → 패턴 id·장면 씨앗. director.json 의 pinned 에 남아 다음 kf direct 가 덮지 않는다 */
   pins?: Record<string, Pin>;
+  /** 이번 짓기에만 — 장면 id → 패턴 id. pins 와 달리 director.json 에 안 남는다(다시 짓기를 다 쓰고 감독 기본으로 박을 때) */
+  force?: Record<string, string>;
   /** 장면마다 진행 줄(「장면 <id>: 쓰는 중|씀|실패 <까닭>」 — 굽기·검사까지 끝난 「끝」은 작업실·render 몫) */
   log?: (line: string) => void;
 }
@@ -256,10 +260,14 @@ export async function build(dir: string, content: Content, o: BuildOpts = {}): P
       if (!r) throw new Error(`장면 ${s.id}: 남은 패턴 후보가 없다 — 떨어진 것 ${(failed[s.id] ?? []).join(", ")}`);
       picks[i] = r;
     }
-  } else picks = selectAll(slots, entries, ctx, failed);
+  } else {
+    // 박을 장면은 떨어진 기록 없이 고른다 — 후보가 다 떨어졌으면 고르기가 「고를 패턴이 없다」로 멈춰 박기까지 못 간다
+    const left = o.force ? Object.fromEntries(Object.entries(failed).filter(([id]) => !(id in o.force!))) : failed;
+    picks = selectAll(slots, entries, ctx, left);
+  }
   // 사람이 고른 패턴이 이긴다 — 그 type 의 패턴이어야 한다
   for (const [i, s] of slots.entries()) {
-    const want = pinned[s.id]?.pattern;
+    const want = o.force?.[s.id] ?? pinned[s.id]?.pattern;
     if (!want || picks[i].pattern === want) continue;
     const e = entryOf.get(want);
     if (!e || (!e.fallback && e.meta.type !== s.type)) throw new Error(`--pattern ${s.id}=${want}: ${e ? `${s.type} 장면에 ${e.meta.type} 패턴` : "없는 패턴"} — 후보는 director.json 의 order`);
@@ -274,9 +282,10 @@ export async function build(dir: string, content: Content, o: BuildOpts = {}): P
     const b = spaceOf(scenes[i + 1] ?? {});
     return { at: i, bridge: a === b ? false : b === "3d" ? "up" : "down" };
   });
-  const kinds = seamKinds(spots, key, tpl.scenes.find((s) => s.role === "seam")?.transition ?? "dive", Object.fromEntries(seamIdx.map((i, k) => [k, seamFailed[scenes[i].id] ?? []])));
+  const allow = themeTransitions(theme);
+  const kinds = seamKinds(spots, key, tpl.scenes.find((s) => s.role === "seam")?.transition ?? "dive", Object.fromEntries(seamIdx.map((i, k) => [k, seamFailed[scenes[i].id] ?? []])), allow);
 
-  const dress = dressAll(key, scenes, tpl.moves, world);
+  const dress = dressAll(key, scenes, tpl.moves, world, allow);
   const scenesDir = join(dir, "scenes");
   mkdirSync(scenesDir, { recursive: true });
   const report: SceneReport[] = [];