kasaframe 0.1.5 → 0.1.7

package/NOTICE

@@ -147,6 +147,19 @@ MIT — Copyright (c) 2026 NikusonP
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
   SOFTWARE.
 
+----------------------------------------------------------------------
+효과음 — sfx/<결>/<역할>.wav
+Kenney(www.kenney.nl) 묶음 여섯에서 골라 다듬었다(몇은 두 소리를 꼭대기에 맞춰 겹침, 앞 무음·꼬리 자르기, 길이 상한, 페이드, 꼭대기 -1dBFS).
+모두 CC0 1.0 — 묶음마다 받은 zip 의 License.txt 로 확인했다(tools/sfx/build.ts 가 다시 지을 때도 본다). 출처 표기 의무는 없다.
+파일마다 원본 파일 이름은 sfx/tags.json·sfx/README.md.
+  Kenney UI SFX Set            https://kenney.nl/assets/ui-audio
+  Kenney Interface Sounds 1.0  https://kenney.nl/assets/interface-sounds
+  Kenney Impact Sounds 1.0     https://kenney.nl/assets/impact-sounds
+  Kenney Digital Audio         https://kenney.nl/assets/digital-audio
+  Kenney RPG Audio             https://kenney.nl/assets/rpg-audio
+  Kenney Casino Audio 1.1      https://kenney.nl/assets/casino-audio
+  CC0 1.0 원문: https://creativecommons.org/publicdomain/zero/1.0/
+
 ----------------------------------------------------------------------
 글꼴 짝 — packages/themes/kit/fonts.json · kit/fonts/<무리>.json (kf fonts notice --write 가 이 절을 짓는다)
 글꼴 파일은 싣지 않는다 — 영상을 구울 때 판을 박은 주소(jsdelivr gh@커밋·npm@판)에서 받는다. 모두 상업 이용·영상·

package/README.md

@@ -67,7 +67,7 @@ kf skill install                   # ~/.claude/skills/kasaframe 에 스킬 링
 
 ## 목소리·곡
 
-쇼츠·설명은 차분한 TTS 내레이션과 깊은 앰비언트 곡(`deep`)이 기본이다. 목소리가 장면 길이를 정하고, 렌더가 곡을 말 아래로 덕킹해 -14 LUFS 로 섞는다. 곡은 틀이 박은 분위기(`deep`)대로 매번 같고, 목소리는 만들기 전에 묻는다(로컬 Qwen3·ElevenLabs·자막만·그 밖 차례). 엔진·곡이 없으면 다른 것으로 넘어가지 않고 키 넣기·다른 엔진·빼기를 묻는다.
+쇼츠·설명은 차분한 TTS 내레이션과 깊은 앰비언트 곡(`deep`)이 기본이다. 목소리가 장면 길이를 정하고, 렌더가 곡을 말 아래로 덕킹해 -14 LUFS 로 섞는다. 효과음도 기본으로 깐다 — 뜻 있는 자리(장면 바뀜·드롭·주인공 착지·짚개가 요점에 닿는 순간)에만 테마가 고른 결(`sfx/` 의 CC0 소리)을 둘레 곡과 비슷한 크기로, 그 순간 곡을 살짝 눌러 들리게(목소리가 있으면 더 낮게). 끄기는 `kf.json` 의 `sfx: false` 나 `kf render|make --sfx off`. 곡은 틀이 박은 분위기(`deep`)대로 매번 같고, 목소리는 만들기 전에 묻는다(로컬 Qwen3·ElevenLabs·자막만·그 밖 차례). 엔진·곡이 없으면 다른 것으로 넘어가지 않고 키 넣기·다른 엔진·빼기를 묻는다.
 
 | 쓰는 것 | 키 | 상태 |
 |---|---|---|
@@ -85,7 +85,7 @@ kf skill install                   # ~/.claude/skills/kasaframe 에 스킬 링
 | `kf new` | 용도 틀에서 프로젝트 뼈대 — 곡 분석·박에 맞춘 장면 시간표·장면 파일 |
 | `kf make` | 요청 한 줄로 끝까지 — 용도 판별·계획·장면·렌더·검사 |
 | `kf preview` | 미리보기 — 곡이 기준 시계, 타임라인·박·드롭·프레임 이동 |
-| `kf render` | MP4(또는 ProRes·PNG 묶음)로 굽기 — 탭 병렬, 곡 얹기, 자막 |
+| `kf render` | MP4(또는 ProRes·PNG 묶음)로 굽기 — 탭 병렬, 곡·목소리·효과음 얹기, 자막 |
 | `kf check` | 검사 — 멈춤·빈 화면·글 깨짐·화면 밖 글·대비·섬광·박 경계·움직임 규칙 |
 | `kf still` · `kf sheet` · `kf look` | 한 장 · 장면 모음 · 장면별 확인표 |
 | `kf beats` | 곡을 재서 `beats.json` — 박·마디·프레이즈·구간·드롭·대역 에너지 |

package/docs/AGENTS.md

@@ -101,6 +101,7 @@ export default {
 - DOM 은 `build` 에서 한 번 짓고, `(t) => …` 에서는 글·스타일만 바꾼다.
 - 박자는 `ctx.beats`(`drop(0)`·`nearestBeat`·`phrase`·`inDrop`), 그림은 `ctx.asset("x.png")`, 글은 `ctx.safe` 안에.
 - 움직임은 `@kasaframe/motion` 부품을 쓴다 — 손으로 짠 흔들림·펄스는 검사가 셀 수 없다. 부품 표와 Remotion 대응표: [`packages/motion/README.md`](../packages/motion/README.md).
+- 효과음은 렌더가 깐다 — 부품(등장·드롭·전환·테마 효과·패턴)이 움직임 시작 자리를 저절로 남긴다. 손으로 지은 움직임만 `ctx.sfx("land", 1.2)`(역할: appear·stick·land·hop·whoosh·tick·select·type·drop·burst·end, 시각은 장면 초). 끄기는 `kf.json` `sfx: false`.
 - React 장면: `export default { react: Component }`, `Component({ t, ctx })`.
 
 하지 말 것:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasaframe",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "말로 시키는 코드 영상 엔진 — 쇼츠·홍보·설명·뮤비를 장면 파일로 짜고 박에 맞춰 MP4 로 굽고 검사한다",
   "keywords": [
     "video",

package/packages/adapters/src/project.ts

@@ -1,6 +1,7 @@
 import {
   createBeats,
   cssVars,
+  cueAt,
   fontCss,
   setBeats,
   silentBeats,
@@ -169,6 +170,7 @@ export function mountProject(o: MountOptions): KfPage {
         style: style as KfStyle,
         safe: caps?.safe ?? kf.safeArea ?? ZERO,
         asset: assetUrl,
+        sfx: (role, at, so) => cueAt(role, entry.from + at, { ...so, source: so?.source ?? `ctx:${role}`, scene: entry.id }),
       };
       let draw: SceneDraw;
       if (mod.react) {

package/packages/check/package.json

@@ -13,6 +13,7 @@
     "@kasaframe/cli": "*",
     "@kasaframe/clock": "*",
     "@kasaframe/core": "*",
+    "@kasaframe/themes": "*",
     "playwright": "^1.64.0",
     "pngjs": "^7.0.0"
   }

package/packages/check/src/check.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { clockScript } from "@kasaframe/clock";
 import { openProject, repoRoot } from "@kasaframe/cli";
+import { freezeLimits } from "@kasaframe/core";
+import { themeFreezeSec } from "@kasaframe/themes";
 import { scanPage } from "./scan.ts";
 import { serveStatic } from "./serve.ts";
 import { probeVideo, videoText, videoThumbs } from "./video.ts";
@@ -41,6 +43,8 @@ interface Project {
   kf: any | null;
   beats: Beats | null;
   rules: MotionRules;
+  /** 멈춤 경고·오류 기준(초) — 틀·style.json 값과 테마가 늘린 값(freezeLimits) */
+  freeze: { warn: number; error: number };
   safe?: SafeArea;
   text: TextPolicy;
   allowText: string[];
@@ -75,12 +79,14 @@ function loadProject(dir: string | null, o: CheckOptions): Project {
   // 틀의 motion 이 style.json 위에 덮인다(SPEC 계약 7).
   const template = kf?.template ? readJson(join(repoRoot, "templates", kf.template, "template.json")) : null;
   const rules: MotionRules = { ...(style?.motion ?? {}), ...(template?.motion ?? {}) };
+  // 테마는 멈춤 오류 기준을 늘리기만 한다 — 테마 없는 프로젝트·기준을 안 정한 테마는 틀·style.json 값 그대로
   const scenes: number[] = Array.isArray(kf?.scenes) ? kf.scenes.map((s: any) => Number(s.from)).filter((t: number) => Number.isFinite(t)) : [];
   return {
     dir,
     kf,
     beats: beats && Array.isArray(beats.beats) ? beats : null,
     rules,
+    freeze: freezeLimits(rules.maxFreezeSec, themeFreezeSec(kf?.theme)),
     safe: kf?.safeArea,
     text: { ...(template?.text ?? {}), ...(kf?.text ?? {}) },
     allowText: kf?.check?.allowText ?? [],
@@ -184,7 +190,7 @@ async function checkPage(o: CheckOptions): Promise<Report> {
     f.push(...contrast(r.contrast, { shotFps: o.shotFps ?? 2 }));
     if (proj.text.minPx || proj.text.maxOnScreen) f.push(...textPolicy(r.texts, proj.text, { fps: meta.fps }));
     if (projDir) f.push(...genAssets(projDir));
-    f.push(...freezes(r.thumbs, { errorSec: proj.rules.maxFreezeSec }));
+    f.push(...freezes(r.thumbs, { errorSec: proj.freeze.error, warnSec: proj.freeze.warn }));
     f.push(...blanks(r.thumbs, meta.duration));
     f.push(...spikes(r.thumbs, { exclude: [...sceneSpans(proj.kf).map((s) => s.from), ...(proj.beats?.drops ?? []), ...r.markers.filter((m) => m.kind === "scene" || m.kind === "drop").map((m) => m.t)] }));
     f.push(...flashes(r.thumbs, { maxPerSec: proj.rules.maxFlashPerSec, cuts: [...sceneSpans(proj.kf).map((s) => s.from), ...cuts(r.thumbs)] }));
@@ -236,7 +242,7 @@ async function checkVideo(o: CheckOptions): Promise<Report> {
 
   log(`프레임 읽기: ${from.toFixed(2)}–${to.toFixed(2)}초 · ${info.width}×${info.height} · ${info.fps.toFixed(2)}fps`);
   const thumbs = await videoThumbs(file, info, from, to);
-  f.push(...freezes(thumbs, { errorSec: proj.rules.maxFreezeSec }));
+  f.push(...freezes(thumbs, { errorSec: proj.freeze.error, warnSec: proj.freeze.warn }));
   f.push(...blanks(thumbs, info.duration));
   f.push(...spikes(thumbs, { exclude: [...sceneSpans(proj.kf).map((s) => s.from), ...(proj.beats?.drops ?? [])] }));
   f.push(...flashes(thumbs, { maxPerSec: proj.rules.maxFlashPerSec, cuts: [...sceneSpans(proj.kf).map((s) => s.from), ...cuts(thumbs)] }));

package/packages/check/src/rules/frames.ts

@@ -1,10 +1,11 @@
+import { MAX_FREEZE_SEC } from "@kasaframe/core";
 import { meanAbsDiff, type Thumb } from "../image.ts";
 import type { Finding } from "../types.ts";
 
 export interface FreezeOptions {
   // 160×90 회색조 평균 절대차(0..255). 커서 깜빡임 한 번이면 넘는 정도.
   threshold?: number;
-  // 틀·style.json 의 motion.maxFreezeSec(틀이 이긴다) — 고정 관찰 화면(설명·뮤비)은 틀에서 늘려 허용한다. 없으면 0.1초
+  // 틀·style.json 의 motion.maxFreezeSec(틀이 이긴다)와 테마 값 중 큰 쪽(freezeLimits) — 고정 관찰 화면은 늘려 허용한다. 없으면 0.1초
   errorSec?: number;
   warnSec?: number;
 }
@@ -24,9 +25,7 @@ export function diffs(thumbs: Thumb[]): number[] {
 
 // 이웃 프레임끼리 비교하면 60fps 의 느린 움직임이 멈춤으로 보인다. 멈춤이 시작된 프레임(닻)과 비교해
 // 닻에서 얼마나 멀어졌는지로 잰다 — 10fps 로 찍든 60fps 로 읽든 같은 답이 나온다.
-// 공통 규칙: 단 0.1초도 쉬지 않는다 — 끝 카드·큰 숫자·로고도 예외 없이 0.1초(60fps 6프레임) 넘게 멈추면 오류
-export const MAX_FREEZE_SEC = 0.1;
-
+// 공통 규칙: 단 0.1초도 쉬지 않는다(MAX_FREEZE_SEC) — 끝 카드·큰 숫자·로고도 예외 없이. 테마가 늘린 만큼만 경고로 남긴다
 export function freezes(thumbs: Thumb[], o: FreezeOptions = {}): Finding[] {
   const thr = o.threshold ?? 0.35;
   const errorSec = o.errorSec ?? MAX_FREEZE_SEC;
@@ -47,7 +46,7 @@ export function freezes(thumbs: Thumb[], o: FreezeOptions = {}): Finding[] {
         severity,
         from: thumbs[a].t,
         to: thumbs[end].t,
-        message: `화면이 ${len.toFixed(2)}초 ${area > 0 ? `거의 멈췄다(바뀐 면적 ${(area * 100).toFixed(1)}%)` : "멈췄다"}${severity === "warn" ? ` — 경고 기준 ${warnSec}초 넘음` : ` — 기준 ${errorSec}초(틀·style.json maxFreezeSec)`} — 그 사이에 눈에 띄는 움직임 하나를 둔다`,
+        message: `화면이 ${len.toFixed(2)}초 ${area > 0 ? `거의 멈췄다(바뀐 면적 ${(area * 100).toFixed(1)}%)` : "멈췄다"}${severity === "warn" ? ` — 경고 기준 ${warnSec}초 넘음` : ` — 기준 ${errorSec}초(틀·style.json·테마 maxFreezeSec)`} — 그 사이에 눈에 띄는 움직임 하나를 둔다`,
         detail: { seconds: Math.round(len * 100) / 100, changedArea: Math.round(area * 10000) / 10000 },
       });
     }

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

@@ -8,6 +8,7 @@ import { parseDuration } from "@kasaframe/plan";
 import { type Command, num, parseFlags } from "../command.ts";
 
 const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+const FALLBACK = "any.words";
 // 검사가 떨어뜨려도 패턴 탓이 아닌 규칙 — 장면 경계(시간표)·생성 자산·자막 판
 const NOT_PATTERN = /^(beat\.|asset\.|caption\.)/;
 // 생성 능력 질문의 답 — kf make 로 그대로 넘긴다
@@ -130,6 +131,7 @@ const cmd: Command = {
     let code = 0;
     if (!opts["no-check"]) {
       const retries = num(opts.retries, 2);
+      let forced = false;
       for (let round = 0; ; round++) {
         // 옛 결과를 치우고 돌린다 — 검사가 돌지 못하고 끝나면 옛 check.json 을 이번 결과로 읽게 된다
         const report_ = join(dir, "out", "check.json");
@@ -154,14 +156,32 @@ const cmd: Command = {
         }
         const blame = blameScenes(dir, report);
         console.error(`kf check 오류 — ${blame.lines.join(" · ")}`);
-        if (round >= retries || (!Object.keys(blame.failed).length && !Object.keys(blame.seamFailed).length)) break;
+        if (!Object.keys(blame.failed).length && !Object.keys(blame.seamFailed).length) break;
+        // 다시 짓기를 다 써도 떨어지는 장면은 감독 기본(any.words)으로 한 번 더 — 막혀도 대체로는 끝까지 간다. 후보가 많은 type 은
+        // 다시 짓기 두 번 안에 기본까지 내려오지 못했다. 기본도 떨어지면 멈춘다
+        const left = Object.keys(blame.failed).filter((id) => report.scenes.find((s) => s.id === id)?.pattern !== FALLBACK);
+        const fallback = (): Record<string, string> | null => {
+          if (forced || !left.length) return null;
+          forced = true;
+          return Object.fromEntries(left.map((id) => [id, FALLBACK]));
+        };
+        let force = round >= retries ? fallback() : undefined;
+        if (force === null) break;
         try {
-          report = await build(dir, content, { seed, failed: blame.failed, seamFailed: blame.seamFailed, log });
+          report = await build(dir, content, { seed, failed: blame.failed, seamFailed: blame.seamFailed, force, log });
         } catch (e) {
+          // 남은 후보가 없어 고르기가 멈췄으면 그 장면들을 감독 기본으로
           console.error(`kf direct: ${e instanceof Error ? e.message : e}`);
-          break;
+          force = fallback();
+          if (!force) break;
+          try {
+            report = await build(dir, content, { seed, failed: blame.failed, seamFailed: blame.seamFailed, force, log });
+          } catch (e2) {
+            console.error(`kf direct: ${e2 instanceof Error ? e2.message : e2}`);
+            break;
+          }
         }
-        console.error(`다시 지음(${round + 1}/${retries}) — ${[...Object.entries(blame.failed), ...Object.entries(blame.seamFailed)].map(([id]) => `${id} → ${report.scenes.find((s) => s.id === id)?.pattern ?? report.scenes.find((s) => s.id === id)?.transition}`).join(" · ")}`);
+        console.error(`${force ? "감독 기본으로" : `다시 지음(${round + 1}/${retries})`} — ${[...Object.entries(blame.failed), ...Object.entries(blame.seamFailed)].map(([id]) => `${id} → ${report.scenes.find((s) => s.id === id)?.pattern ?? report.scenes.find((s) => s.id === id)?.transition}`).join(" · ")}`);
       }
       if (code !== 0) console.error(`kf check 가 아직 떨어진다 — ${dir}/out/check.json 을 보고 content.json 을 고치거나 --seed 를 바꿔 다시`);
     }

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

@@ -103,6 +103,7 @@ kf make --answer <폴더> --image <값> --video <값> …   Claude Code 모드
   --video-provider  영상 공급자를 못 박는다(예: h3-pod — KF_H3_URL·KF_H3_STEPS 필요). 기본은 KF_VIDEO_PROVIDER, 없으면 생성 담당 기본
   --fix           검사가 떨어졌을 때 고치기 횟수(기본 2)
   --captions on|off|fit  화면 자막(fit 은 장면을 자막 띠 위로 줄여 올린다) — 새로 만들 땐 kf.json 에 적고, --finish 에선 그 판만 덮는다(다시 만들지 않고 켜고 끄기). srt·vtt 는 둘 다 낸다
+  --sfx on|off    효과음(기본 켬 — 테마가 고른 결로 장면 움직임 자리에 곡 아래 작게) — 새로 만들 땐 off 를 kf.json 에 sfx: false 로 적고, --finish 에선 그 판만 덮는다
   --suffix [글]   --finish 결과 이름 뒤에 붙인다(값 없이면 -자막 · -자막없음) — 원본 video.mp4 를 덮지 않고 둘 다 남긴다
   --no-gen        생성 모델을 부르지 않는다 — 묻지 않고 그림·영상 모델은 빼고, Blender 가 없으면 three 로 대신한다
 
@@ -171,6 +172,11 @@ async function make(argv: string[], at: Track): Promise<number> {
     return 2;
   }
   const suffix = str("suffix") ?? (opts.suffix ? (captions === "off" ? "-자막없음" : "-자막") : "");
+  const sfx = str("sfx");
+  if (sfx !== undefined && sfx !== "on" && sfx !== "off") {
+    console.error(`kf make: --sfx 는 on·off — ${sfx}`);
+    return 2;
+  }
 
   if (opts.answer) {
     at.quiet = true;
@@ -192,7 +198,7 @@ async function make(argv: string[], at: Track): Promise<number> {
       const narrate = sayChanged(dir, ids) ? [] : ["--no-narrate"];
       const d = await relay(["direct", dir, "--scenes", ids.join(","), ...narrate, "--no-check", ...pick]);
       if (d !== 0) return d;
-      return finish(dir, { model: "direct", vision, fixes: 0, scenes: ids });
+      return finish(dir, { model: "direct", vision, fixes: 0, scenes: ids, sfx });
     }
     // 다시 쓰기는 그 일을 만든 모델로 — 기본 모델로 몰래 바꾸지 않는다
     const own = str("model") ?? readPlan(dir).model;
@@ -208,7 +214,7 @@ async function make(argv: string[], at: Track): Promise<number> {
     }
     writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
     await writeScenes(dir, own, ids);
-    return finish(dir, { model: own, vision, fixes, scenes: ids });
+    return finish(dir, { model: own, vision, fixes, scenes: ids, sfx });
   }
   if (opts.finish) {
     const dir = resolve(typeof opts.finish === "string" ? opts.finish : (args[0] ?? "."));
@@ -220,7 +226,7 @@ async function make(argv: string[], at: Track): Promise<number> {
     if (studio) console.log(`작업실: ${studio.url}`);
     await studio?.send({ phase: "render" });
     const scenes = str("scenes")?.split(",").filter(Boolean);
-    const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen, captions, suffix, ...(scenes?.length ? { scenes } : {}) });
+    const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen, captions, suffix, sfx, ...(scenes?.length ? { scenes } : {}) });
     await unmirror?.();
     await studio?.send({ done: true, ok: code === 0 });
     return code;
@@ -352,6 +358,10 @@ async function make(argv: string[], at: Track): Promise<number> {
     writeJson(kfPath, { ...JSON.parse(readFileSync(kfPath, "utf8")), captions });
     plan.captions = captionMode(captions);
   }
+  if (sfx === "off") {
+    const kfPath = join(dir, "kf.json");
+    writeJson(kfPath, { ...JSON.parse(readFileSync(kfPath, "utf8")), sfx: false });
+  }
   if (!str("purpose") && !series) {
     plan.confidence = chosen?.p ?? det.confidence;
     plan.alternatives = det.ranked.filter((r) => r.purpose !== purpose).slice(0, 2).map((r) => ({ purpose: r.purpose, p: r.p }));
@@ -901,7 +911,7 @@ async function seamStills(dir: string, only?: string[]): Promise<void> {
 
 // captions 를 주면 그 판만 화면 자막을 켜고 끈다(kf.json 은 그대로) — 굽기·검사·자막 트랙이 같은 값을 본다
 // scenes 를 주면 그 장면 둘레(그 장면 + 붙은 이음매)만 — 이음 화면·검사를 그 구간에서. 굽기는 kf render 가 바뀐 조각만 다시 찍는다
-async function finish(dir: string, o: { model: string; vision: string; fixes: number; gen?: GenOpts; captions?: "on" | "off" | "fit"; suffix?: string; scenes?: string[] }): Promise<number> {
+async function finish(dir: string, o: { model: string; vision: string; fixes: number; gen?: GenOpts; captions?: "on" | "off" | "fit"; suffix?: string; scenes?: string[]; sfx?: string }): Promise<number> {
   if (!existsSync(join(dir, "kf.json"))) {
     console.error(`kf make: ${dir} 에 kf.json 이 없다`);
     return 2;
@@ -921,7 +931,7 @@ async function finish(dir: string, o: { model: string; vision: string; fixes: nu
     if (round > 0) await seamStills(dir, touched);
     // 굽기와 검사 사이에 잠금을 놓으면 기다리던 남의 긴 렌더가 끼어든다 — 둘을 한 번에 쥐고 자식은 잠금 없이
     const release = await acquireRenderLock(dir, 3600);
-    const r = await relay(["render", dir, "--out", out, "--tabs", "2", "--no-lock", ...capFlag]);
+    const r = await relay(["render", dir, "--out", out, "--tabs", "2", "--no-lock", ...capFlag, ...(o.sfx ? ["--sfx", o.sfx] : [])]);
     if (r !== 0) {
       release();
       console.error("kf make: 렌더가 실패했다");

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

@@ -8,7 +8,8 @@ import { acquireRenderLock } from "../lock.ts";
 import { blurOpts, captureBlurred, projectBlur, rgbaToPng } from "../blur.ts";
 import { outPath } from "../out.ts";
 import { cachedSegment, collectEvents, type KeyOpts, type MotionEvent, pruneSegments, renderSegments, sceneKeys, sceneSpans, type SegmentReport, type SegmentWork, variantOf } from "../segments.ts";
-import { mixAudio, mixSettings } from "../mix.ts";
+import { mixAudio, mixSettings, SFX_AUDIO, type SfxMix } from "../mix.ts";
+import { cuesOf, loadBank, placeSfx, projectDrops, sfxSettings } from "../sfx.ts";
 
 const MAX_TABS = 3;
 
@@ -61,7 +62,7 @@ function withSuffix(p: string, suffix: string): string {
 
 const cmd: Command = {
   summary: "MP4(또는 ProRes·PNG 묶음)로 굽기 — 탭 병렬, 곡 얹기, 잠금",
-  usage: `kf render <폴더> [--out x.mp4] [--scenes a,b] [--from 초 --to 초] [--tabs 3] [--prores | --png] [--music 곡 | --no-music] [--captions on|off|fit [--suffix]]
+  usage: `kf render <폴더> [--out x.mp4] [--scenes a,b] [--from 초 --to 초] [--tabs 3] [--prores | --png] [--music 곡 | --no-music] [--sfx on|off] [--captions on|off|fit [--suffix]]
   --out       기본 <폴더>/out/render.mp4 (--prores 면 .mov, --png 면 폴더)
   seek 모드는 장면 조각으로 굽는다 — 장면마다 out/segments/<장면>-<해시>.mp4(해시: 그 장면이 실제로 불러온 모듈·kf.json 그 장면 칸·
               자산·자막 줄·굽기 설정, 이음매는 앞뒤 장면까지). 해시가 같은 조각은 다시 찍지 않고 이어 붙인 뒤 곡·목소리를 전체로 얹는다
@@ -71,6 +72,8 @@ const cmd: Command = {
   --tabs      크롬 탭 수(최대 ${MAX_TABS}). seek 모드는 구간을 나눠 찍고, step 모드는 탭마다 구간 앞까지 빨리 돌린 뒤 찍는다
   --music     기본은 페이지 meta.music(kf.json 의 music). 곡은 beats.json 의 from 초부터 얹는다
   --music-from 곡에서 시작할 초를 직접 준다(--music 으로 다른 곡을 줄 때)
+  --sfx on|off 효과음(기본 켬) — 장면 움직임이 남긴 소리 자리(__kf.events 의 sfx)와 곡의 드롭에 테마가 고른 결(theme.json sfx)의 소리를
+              곡 아래로 작게 깐다. off 면 이 판만 끄고(효과음 이전과 같은 소리), on 이면 kf.json sfx: false 도 이 판만 켠다. --no-music 이면 없다
   --crf       H.264 화질(기본 16, 낮을수록 좋다)
   --motion-blur N  한 프레임을 하위 프레임 N 장(예 8)으로 찍어 평균 — 빠른 것만 번진다. 3D 전환은 같은 평균으로 피사계 심도도. seek 모드만, N 배 느리다.
               안 주면 kf.json 의 render.motionBlur(쇼츠·홍보 틀은 켜 둔다), 0 이면 끈다
@@ -91,6 +94,8 @@ const cmd: Command = {
     const format: VideoFormat | "png" = opts.png ? "png" : opts.prores ? "prores" : "h264";
     const ext = format === "prores" ? ".mov" : format === "png" ? "" : ".mp4";
     const captions = opts.captions === undefined ? undefined : String(opts.captions);
+    const sfxFlag = opts.sfx === undefined ? undefined : String(opts.sfx);
+    if (sfxFlag !== undefined && sfxFlag !== "on" && sfxFlag !== "off") throw new Error(`--sfx 는 on·off: ${sfxFlag}`);
     if (captions !== undefined && captions !== "on" && captions !== "off" && captions !== "fit") throw new Error(`--captions 는 on·off·fit: ${captions}`);
     const suffix = typeof opts.suffix === "string" ? opts.suffix : opts.suffix ? (captions === "off" ? "-자막없음" : "-자막") : "";
     const out = withSuffix(outPath(dir, opts.out, format === "png" ? "frames/x" : `render${ext}`).replace(/\/x$/, ""), suffix);
@@ -139,6 +144,8 @@ const cmd: Command = {
         console.error(`  ${done}/${todo} (${((done / Math.max(1, todo)) * 100).toFixed(0)}%) ${(done / sec).toFixed(1)} 장/초`);
       }, 5000);
 
+      let sfx: SfxMix | undefined;
+      let sfxCues = 0;
       let segFiles: string[] = [];
       let events: MotionEvent[] = [];
       let segments: { rendered: string[]; reused: string[] } | undefined;
@@ -209,13 +216,24 @@ const cmd: Command = {
       if (format !== "png") {
         const list = join(tmp, "list.txt");
         writeFileSync(list, segFiles.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
-        // kf.json 에 audio(섞기 값)가 있으면 내레이션·곡을 섞은 소리를 얹는다(덕킹·끝 페이드·LUFS) — 없으면 곡만
-        const mix = opts["no-music"] ? null : mixSettings(resolve(dir));
-        const mixed = mix && (mix.voice || music)
-          ? await mixAudio({ voice: mix.voice, music, musicFrom: songFrom }, { audio: mix.audio, from: startF / fps, dur: frames / fps, total: meta.duration, out: join(tmp, "mix.wav") })
+        // 효과음 — 찍는 동안 페이지가 남긴 소리 자리를 밀도대로 걸러 깐다. 끄면(--sfx off·kf.json sfx: false) 아래는 효과음 이전과 같은 길
+        const settings = opts["no-music"] ? null : sfxSettings(resolve(dir), sfxFlag);
+        if (settings) {
+          const bank = loadBank();
+          if (!bank.sets.includes(settings.set)) throw new Error(`효과음 결 "${settings.set}" 이 없다 — 있는 결: ${bank.sets.join(" · ")}`);
+          const cues = cuesOf(events, settings.only && !settings.only.includes("drop") ? [] : projectDrops(resolve(dir)));
+          sfx = { hits: placeSfx(cues, settings, bank, { from: startF / fps, to: endF / fps }), settings, bank };
+          sfxCues = cues.filter((c) => c.t >= startF / fps && c.t < endF / fps).length;
+        }
+        // kf.json 에 audio(섞기 값)가 있으면 내레이션·곡을 섞은 소리를 얹는다(덕킹·끝 페이드·LUFS) — 없으면 곡만. 효과음을 깔면 audio 가 없어도 섞는다
+        const found = opts["no-music"] ? null : mixSettings(resolve(dir));
+        const mix = found ?? (sfx?.hits.length ? { audio: SFX_AUDIO, voice: undefined } : null);
+        const mixed = mix && (mix.voice || music || sfx?.hits.length)
+          ? await mixAudio({ voice: mix.voice, music, musicFrom: songFrom }, { audio: mix.audio, from: startF / fps, dur: frames / fps, total: meta.duration, out: join(tmp, "mix.wav"), sfx })
           : undefined;
         await concat({ list, out, format, music: mixed ?? music, from: mixed ? 0 : songFrom + startF / fps, dur: frames / fps });
-        if (mixed) console.error(`소리: ${mix!.voice ? "내레이션" : ""}${mix!.voice && music ? " + " : ""}${music ? "곡" : ""} → ${mix!.audio.lufs} LUFS`);
+        const layers = [mix?.voice ? "내레이션" : "", music ? "곡" : "", sfx?.hits.length ? `효과음 ${sfx.hits.length}(${sfx.settings.set})` : ""].filter(Boolean);
+        if (mixed) console.error(`소리: ${layers.join(" + ")} → ${mix!.audio.lufs} LUFS`);
       }
       const sec = (Date.now() - started) / 1000;
       const report = {
@@ -230,6 +248,15 @@ const cmd: Command = {
         motionBlur: blur,
         captions: captions ?? null,
         music: music ?? null,
+        sfx: sfx
+          ? {
+              ...sfx.settings,
+              cues: sfxCues,
+              placed: sfx.hits.length,
+              ...(sfx.measured ? { lufs: { bed: sfx.measured.bed, sfx: sfx.measured.sfx, lift: sfx.measured.lift } } : {}),
+              hits: sfx.measured?.hits ?? sfx.hits,
+            }
+          : null,
         seconds: Math.round(sec * 10) / 10,
         ...(segments ? { segments } : {}),
         markers: s.info.markers,

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 {