kasaframe 0.1.1 → 0.1.4

package/packages/gen/src/ask.ts

@@ -0,0 +1,132 @@
+import { createInterface } from "node:readline/promises";
+
+// 돈이 드는 호출과 없는 능력은 kf make 가 생성 전에 한 번에 모아 묻는다 — 그림·영상·3D·음악·목소리가 같은 꼴로 들어온다
+// theme 은 돈도 능력도 아닌 고르기라 --allow 목록엔 없다 — --yes·--no-gen·--allow 는 그 질문의 「알아서」로 간다
+export type Capability = "image" | "video" | "blender" | "three" | "music" | "voice" | "beats" | "lyrics" | "theme";
+export const CAPABILITIES: Capability[] = ["image", "video", "blender", "three", "music", "voice", "beats", "lyrics"];
+// --no-gen 이 「빼기」로 답해 줄 수 있는 생성 능력 — 3D·박자·가사 도구는 생성 모델이 아니라 --no-gen 으로 넘기지 않는다
+const GENERATIVE = new Set<Capability>(["image", "video", "music", "voice"]);
+// 「키·도구를 넣고 다시」 — 고르면 kf make 가 켜는 법을 찍고 종료 3
+export const WAIT = "wait";
+
+export interface Choice {
+  value: string; // --<flag> 에 그대로 넣는 값
+  label: string;
+  costUsd?: number;
+  note?: string; // 라이선스·지역 경고는 여기 — 묻는 글과 결과 메타에 같이 남는다
+}
+
+export interface Question {
+  id: string;
+  cap: Capability; // --allow 로 묻지 않고 허락하는 단위
+  ask: string;
+  header: string; // 12자 이내 — Claude Code AskUserQuestion 칩
+  choices: Choice[]; // 첫째가 권장
+  default: string; // --yes · --allow <cap> · 터미널 엔터
+  skip: string; // --no-gen · --allow 에 cap 이 없을 때 — 돈 안 드는 길
+  flag: string;
+  // 필요한 능력이 없다 — 조용히 대체하지 않는다. 보기는 ① 넣는 법(wait, 권장) ② 지금 쓸 수 있는 다른 엔진 ③ 빼기.
+  // --yes·--allow 로 넘어가지 않고 사람이 준 답(플래그·--answer·시리즈)만, 생성 능력이면 --no-gen 의 빼기만 받는다
+  missing?: boolean;
+  accepts?: (v: string) => boolean; // 보기 밖 값도 받는 질문(다른 목소리·곡 파일 경로) — 함수라 plan.json 에는 답만 남는다
+}
+
+export interface AnswerInput {
+  given?: Record<string, string | boolean | undefined>; // 명령 줄 opts 그대로 — --<flag> 값이 있으면 그 답
+  yes?: boolean;
+  noGen?: boolean;
+  allow?: Capability[] | null; // null 이면 --allow 를 안 줬다
+}
+
+export interface Settled {
+  answers: Record<string, string>;
+  open: Question[]; // 아직 사람이 골라야 하는 것
+  how: Record<string, "flag" | "no-gen" | "allow" | "yes">;
+}
+
+export function parseAllow(v: string | boolean | undefined): Capability[] | null {
+  if (typeof v !== "string") return null;
+  const list = v.split(",").map((s) => s.trim()).filter(Boolean);
+  const bad = list.filter((c) => !CAPABILITIES.includes(c as Capability));
+  if (bad.length) throw new Error(`--allow 는 ${CAPABILITIES.join("·")} 중에서 — ${bad.join(", ")}`);
+  return list as Capability[];
+}
+
+// 고르는 순서: 사람이 준 플래그 값 > --no-gen > --allow > --yes. 나머지는 묻는다 — 없는 능력(missing)은 플래그·생성 빼기만
+export function settle(questions: Question[], o: AnswerInput): Settled {
+  const out: Settled = { answers: {}, open: [], how: {} };
+  for (const q of questions) {
+    const given = o.given?.[q.flag.replace(/^--/, "")];
+    if (typeof given === "string" && (q.choices.some((c) => c.value === given) || q.accepts?.(given))) {
+      out.answers[q.id] = given;
+      out.how[q.id] = "flag";
+    } else if (q.missing) {
+      if (o.noGen && GENERATIVE.has(q.cap) && q.choices.some((c) => c.value === "none")) {
+        out.answers[q.id] = "none";
+        out.how[q.id] = "no-gen";
+      } else out.open.push(q);
+    } else if (o.noGen) {
+      out.answers[q.id] = q.skip;
+      out.how[q.id] = "no-gen";
+    } else if (o.allow) {
+      out.answers[q.id] = o.allow.includes(q.cap) ? q.default : q.skip;
+      out.how[q.id] = "allow";
+    } else if (o.yes) {
+      out.answers[q.id] = q.default;
+      out.how[q.id] = "yes";
+    } else out.open.push(q);
+  }
+  return out;
+}
+
+const usd = (n?: number) => (n === undefined ? "" : n === 0 ? " · 0원" : ` · 견적 $${n.toFixed(n < 0.1 ? 3 : 2)}`);
+
+function choiceLine(c: Choice, q: Question): string {
+  const tags = [c.value === q.default ? "권장" : "", c.value === q.skip && !q.missing ? "돈 안 듦" : ""].filter(Boolean);
+  return `${c.label}${usd(c.costUsd)}${tags.length ? ` (${tags.join("·")})` : ""}${c.note ? ` — ${c.note}` : ""}`;
+}
+
+// 터미널에서 한 번에 — 엔터만 치면 권장
+export async function askTerminal(questions: Question[]): Promise<Record<string, string> | null> {
+  if (!process.stdin.isTTY || !questions.length) return questions.length ? null : {};
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const out: Record<string, string> = {};
+  try {
+    process.stderr.write(`\n생성 전에 ${questions.length}가지를 정한다(엔터 = 권장)\n`);
+    for (const q of questions) {
+      const lines = q.choices.map((c, i) => `  ${i + 1}) ${choiceLine(c, q)}`).join("\n");
+      const a = (await rl.question(`\n${q.ask}\n${lines}\n번호: `)).trim();
+      out[q.id] = a === "" ? q.default : (q.choices[Number(a) - 1]?.value ?? q.default);
+    }
+  } finally {
+    rl.close();
+  }
+  return out;
+}
+
+// 터미널이 아닐 때 — 보기와 다시 부를 플래그를 찍는다(종료 코드 3 은 부르는 쪽이). 없는 능력은 자동 답 없이 여기서 멈춘다
+export function questionsText(questions: Question[]): string {
+  return questions
+    .map((q) => [`${q.ask}`, ...q.choices.map((c) => `  ${q.flag} ${c.value.padEnd(22)} ${choiceLine(c, q)}`)].join("\n"))
+    .join("\n\n");
+}
+
+// MAKE.md 맨 위 — AskUserQuestion 보기로 옮기기 좋게(질문·칩·보기 라벨·설명) + 답을 넣는 명령
+export function questionsMarkdown(questions: Question[], rerun: (flags: string) => string): string[] {
+  if (!questions.length) return [];
+  return [
+    "## 사용자에게 먼저 물을 것",
+    "",
+    "장면을 쓰기 전에 아래를 한 번에 묻는다(AskUserQuestion 한 번에 질문 여럿 — `header` 는 칩, 보기 첫째가 권장). 답은 같은 줄의 플래그 값으로 되돌려 준다:",
+    // AskUserQuestion 은 보기를 넷까지만 받는다 — 테마처럼 보기가 많은 질문은 나머지를 글로 보이고 Other 로 받는다
+    ...(questions.some((q) => q.choices.length > 4) ? ["보기가 넷을 넘는 질문은 첫 넷만 보기로 올리고, 나머지 보기 이름은 질문 글에 적어 「Other」로 받는다(보기 밖 값도 그 플래그로 받는다)."] : []),
+    "",
+    ...questions.flatMap((q) => [
+      `- **${q.ask}** (header: \`${q.header}\`, 플래그 \`${q.flag}\`)`,
+      ...q.choices.map((c) => `  - \`${c.value}\` — ${choiceLine(c, q)}`),
+    ]),
+    "",
+    `답을 받으면: \`${rerun(questions.map((q) => `${q.flag} <값>`).join(" "))}\``,
+    "",
+  ];
+}

package/packages/gen/src/audio.ts

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+import { run } from "./media.ts";
+
+// 소리 다루기 — 목소리·곡 둘 다 여기 ffmpeg 한 벌로. 결과는 늘 48kHz 로 맞춰 섞을 때 다시 바꾸지 않는다
+const ff = (args: string[]) => run("ffmpeg", ["-v", "error", "-y", ...args]);
+
+export async function duration(path: string): Promise<number> {
+  const out = await run("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", path]);
+  const d = Number(out.toString().trim());
+  if (!Number.isFinite(d)) throw new Error(`길이를 못 읽음: ${path}`);
+  return d;
+}
+
+// 머리 없는 PCM(Gemini l16·DashScope 일부)을 wav 로 감싼다
+export function pcmToWav(pcm: Uint8Array, rate = 24000, channels = 1): Uint8Array {
+  const h = Buffer.alloc(44);
+  h.write("RIFF", 0);
+  h.writeUInt32LE(36 + pcm.length, 4);
+  h.write("WAVEfmt ", 8);
+  h.writeUInt32LE(16, 16);
+  h.writeUInt16LE(1, 20);
+  h.writeUInt16LE(channels, 22);
+  h.writeUInt32LE(rate, 24);
+  h.writeUInt32LE(rate * channels * 2, 28);
+  h.writeUInt16LE(channels * 2, 32);
+  h.writeUInt16LE(16, 34);
+  h.write("data", 36);
+  h.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([h, Buffer.from(pcm)]);
+}
+
+export interface Silence {
+  from: number;
+  to: number;
+}
+
+// 말 사이 숨 — 자막 마디를 이 자리에 붙인다(기본 -38dB 아래 0.12초 넘게).
+// silencedetect 는 결과를 stderr 로만 낸다 — run 은 stderr 를 버리니 따로 띄운다
+export async function findSilences(path: string, o: { db?: number; min?: number } = {}): Promise<Silence[]> {
+  const text = await new Promise<string>((resolve, reject) => {
+    const p = spawn("ffmpeg", ["-hide_banner", "-nostats", "-i", path, "-af", `silencedetect=noise=${o.db ?? -38}dB:d=${o.min ?? 0.12}`, "-f", "null", "-"]);
+    let err = "";
+    p.stderr.on("data", (b: Buffer) => (err += b));
+    p.on("error", reject);
+    p.on("close", (code) => (code === 0 ? resolve(err) : reject(new Error(`무음 찾기 실패(${code})`))));
+  });
+  const out: Silence[] = [];
+  let open: number | null = null;
+  for (const line of text.split("\n")) {
+    const s = line.match(/silence_start: (-?[\d.]+)/);
+    if (s) open = Math.max(0, Number(s[1]));
+    const e = line.match(/silence_end: ([\d.]+)/);
+    if (e && open !== null) {
+      out.push({ from: open, to: Number(e[1]) });
+      open = null;
+    }
+  }
+  if (open !== null) out.push({ from: open, to: Infinity });
+  return out;
+}
+
+// 앞뒤 무음을 깎은 구간 — 공급자마다 머리·꼬리 숨 길이가 달라 장면 길이가 흔들린다
+export async function voicedSpan(path: string): Promise<{ from: number; to: number; total: number }> {
+  const total = await duration(path);
+  const sil = await findSilences(path, { db: -45, min: 0.05 });
+  const head = sil.find((s) => s.from <= 0.01);
+  const tail = sil.find((s) => s.to === Infinity || s.to >= total - 0.01);
+  const from = head ? Math.min(head.to, total) : 0;
+  const to = tail && tail.from > from ? tail.from : total;
+  return { from, to, total };
+}
+
+// 48kHz 모노 wav 로 — 자르고(from..to) 빠르기(tempo, 0.9–1.1)를 바꾼다. 빠르기는 높이를 지키는 atempo
+export async function cutVoice(src: string, dst: string, o: { from: number; to: number; tempo?: number }): Promise<void> {
+  const tempo = o.tempo ?? 1;
+  if (tempo < 0.9 - 1e-6 || tempo > 1.1 + 1e-6) throw new Error(`목소리 빠르기는 0.9–1.1 안에서만: ${tempo}`);
+  const af = [`atrim=start=${o.from.toFixed(4)}:end=${o.to.toFixed(4)}`, "asetpts=PTS-STARTPTS", ...(Math.abs(tempo - 1) > 1e-4 ? [`atempo=${tempo.toFixed(4)}`] : []), "aresample=48000"].join(",");
+  await ff(["-i", src, "-af", af, "-ac", "1", "-c:a", "pcm_s16le", dst]);
+}
+
+// 장면 시각에 목소리 조각을 깔아 영상 길이 한 줄로
+export async function layVoices(clips: { file: string; at: number }[], total: number, dst: string): Promise<void> {
+  if (!clips.length) {
+    await ff(["-f", "lavfi", "-i", `anullsrc=r=48000:cl=mono`, "-t", total.toFixed(4), "-c:a", "pcm_s16le", dst]);
+    return;
+  }
+  const inputs = clips.flatMap((c) => ["-i", c.file]);
+  const chains = clips.map((c, i) => `[${i}]adelay=${Math.round(c.at * 1000)}:all=1[v${i}]`);
+  const mix = `${clips.map((_, i) => `[v${i}]`).join("")}amix=inputs=${clips.length}:normalize=0:dropout_transition=0,apad,atrim=0:${total.toFixed(4)}[out]`;
+  await ff([...inputs, "-filter_complex", [...chains, mix].join(";"), "-map", "[out]", "-ac", "1", "-ar", "48000", "-c:a", "pcm_s16le", dst]);
+}

package/packages/gen/src/blender.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Blender 를 바깥 프로그램으로 찾기만 한다(bpy 를 가져오지 않는다) — kf blender 와 생성 능력 목록이 같은 답을 본다
+export const BLENDER_MIN = [4, 3]; // Grease Pencil v3(라인아트가 일반 모디파이어)가 4.3 부터
+
+// bpy 를 쓰는 헬퍼는 GPL 로 갈라 둔 tools/blender — npm 묶음에는 없어 KF_BLENDER_LIB 로 가리킨다
+export function blenderLibDir(): string {
+  return process.env.KF_BLENDER_LIB ? resolve(process.env.KF_BLENDER_LIB) : fileURLToPath(new URL("../../../tools/blender/", import.meta.url));
+}
+
+export const hasBlenderLib = (dir = blenderLibDir()): boolean => existsSync(join(dir, "run.py")) && existsSync(join(dir, "kfb.py"));
+
+function candidates(given?: string): string[] {
+  const out: string[] = [];
+  if (given) out.push(given);
+  if (process.env.BLENDER) out.push(process.env.BLENDER);
+  const which = spawnSync(process.platform === "win32" ? "where" : "which", ["blender"], { encoding: "utf8" });
+  if (which.status === 0) out.push(...which.stdout.split(/\r?\n/).filter(Boolean));
+  if (process.platform === "darwin") {
+    const apps = existsSync("/Applications") ? readdirSync("/Applications").filter((n) => /^Blender.*\.app$/.test(n)) : [];
+    // 이름에 판 번호를 붙여 여러 개 깔아 둔 기계면 높은 판부터
+    apps.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    out.push(...apps.map((a) => `/Applications/${a}/Contents/MacOS/Blender`));
+  }
+  if (process.platform === "win32") {
+    const base = "C:\\Program Files\\Blender Foundation";
+    if (existsSync(base)) {
+      const dirs = readdirSync(base).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+      out.push(...dirs.map((d) => join(base, d, "blender.exe")));
+    }
+  }
+  return out;
+}
+
+export function findBlender(given?: string, warn: (line: string) => void = () => {}): { exe: string; version: number[] } {
+  const tried: string[] = [];
+  for (const exe of candidates(given)) {
+    if (tried.includes(exe)) continue;
+    tried.push(exe);
+    const r = spawnSync(exe, ["--version"], { encoding: "utf8", timeout: 30_000 });
+    const m = /Blender (\d+)\.(\d+)(?:\.(\d+))?/.exec(r.stdout ?? "");
+    if (r.status !== 0 || !m) continue;
+    const version = [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+    if (version[0] < BLENDER_MIN[0] || (version[0] === BLENDER_MIN[0] && version[1] < BLENDER_MIN[1])) {
+      warn(`${exe} 는 ${version.join(".")} — ${BLENDER_MIN.join(".")} 이상이 필요해 건너뛴다`);
+      continue;
+    }
+    return { exe, version };
+  }
+  throw new Error(`Blender ${BLENDER_MIN.join(".")} 이상을 못 찾았다 — --blender <실행 파일> 또는 BLENDER=<경로>. 본 곳: ${tried.join(", ") || "(없음)"}`);
+}

package/packages/gen/src/capabilities.ts

@@ -0,0 +1,151 @@
+import { existsSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { Capability } from "./ask.ts";
+import { blenderLibDir, findBlender, hasBlenderLib } from "./blender.ts";
+import { estimateImageUsd } from "./generate.ts";
+import { codexBin } from "./image/codex.ts";
+import { findKey, hasKey, whereToPut } from "./keys.ts";
+import { musicGenCapabilities } from "./music/index.ts";
+import { imageProviders, providerReady, videoProviders } from "./registry.ts";
+import { voiceCapabilities } from "./tts/index.ts";
+
+// 생성 능력 한 칸 — 무엇으로 만드는지·지금 쓸 수 있는지·한 번에 얼마인지·어디에 써도 되는지
+export interface CapabilityProvider {
+  cap: Capability;
+  id: string;
+  label: string;
+  ready: boolean;
+  detail: string; // 왜 되는지·안 되는지
+  fix?: string; // 안 될 때 켜는 법
+  unitUsd: number; // 한 번(그림 한 장·5초 영상 하나·샷 하나) 견적
+  unit: string;
+  license: string;
+  // 회사·바깥 결과물에 걸리는 제한 — 묻는 글과 자산 메타·결과 메타에 같이 남긴다
+  restrict?: string;
+}
+
+export interface CapabilityReport {
+  cap: Capability;
+  label: string;
+  providers: CapabilityProvider[];
+  best: CapabilityProvider | null; // 쓸 수 있는 것 중 권장(싼 것 먼저, 제한 없는 것 먼저)
+}
+
+const LABEL: Record<Capability, string> = {
+  image: "그림",
+  video: "영상 모델",
+  blender: "3D 샷(Blender)",
+  three: "3D 전환·화면 속 3D(three.js)",
+  music: "음악",
+  voice: "목소리(TTS)",
+  beats: "박자 분석(librosa)",
+  lyrics: "가사(JIZURA 가사 층·정렬)",
+  theme: "테마",
+};
+
+async function reach(url: string, init: RequestInit = {}, ms = 3000): Promise<number | string> {
+  try {
+    const r = await fetch(url, { ...init, signal: AbortSignal.timeout(ms) });
+    return r.status;
+  } catch (e) {
+    return e instanceof Error ? e.name === "TimeoutError" ? "응답 없음" : e.message.slice(0, 60) : String(e);
+  }
+}
+
+// probe 면 키·주소가 실제로 사는지 가볍게 두드린다(OG 모델 목록·H3 서버) — 돈이 드는 호출은 하지 않는다
+async function images(probe: boolean): Promise<CapabilityProvider[]> {
+  const est = estimateImageUsd({ prompt: "", size: "1920x1080", quality: "high" });
+  let og: { ok: boolean; why: string } = { ok: hasKey("opengateway"), why: hasKey("opengateway") ? "키 있음" : "키 없음" };
+  if (og.ok && probe) {
+    const s = await reach(`${process.env.KF_OG_HOST ?? "https://apis.opengateway.ai"}/v1/models`, { headers: { Authorization: `Bearer ${findKey("opengateway")}` } });
+    og = s === 200 ? { ok: true, why: "키 살아 있음(모델 목록 200)" } : { ok: false, why: `키는 있는데 OG 가 ${s}${s === 401 ? "(키가 틀렸다)" : s === 402 ? "(잔액 부족)" : ""}` };
+  }
+  const out: CapabilityProvider[] = [];
+  for (const p of imageProviders()) {
+    if (p.id === "codex-imagegen") {
+      const bin = codexBin();
+      const ready = providerReady(p);
+      out.push({
+        cap: "image", id: p.id, label: "codex imagegen(ChatGPT 요금제)", ready,
+        detail: !bin ? "codex CLI 없음" : ready ? "로그인 됨 — 한 장 1–2분" : "codex 는 있는데 로그인 안 됨",
+        fix: !bin ? "npm i -g @openai/codex && codex login" : ready ? undefined : "codex login",
+        unitUsd: 0, unit: "장", license: p.license,
+      });
+      continue;
+    }
+    // 같은 키·같은 단가인 OG 모델 셋은 기본만 앞에 세우고 나머지는 같은 판정으로 둔다
+    out.push({ cap: "image", id: p.id, label: `OG ${p.model}`, ready: og.ok, detail: og.why, fix: og.ok ? undefined : whereToPut("opengateway"), unitUsd: est, unit: "1920x1080 high 한 장", license: p.license });
+  }
+  return out;
+}
+
+async function videos(probe: boolean): Promise<CapabilityProvider[]> {
+  const sample = { prompt: "", duration: 5, aspect: "16:9", firstFrame: "x", lastFrame: "y", resolution: "720p" };
+  const out: CapabilityProvider[] = [];
+  for (const p of videoProviders()) {
+    let ready = providerReady(p);
+    let detail = ready ? "키 있음(키만 봄)" : "키 없음";
+    if (p.id === "h3-pod") {
+      const url = findKey("h3");
+      if (!url) detail = "KF_H3_URL 없음";
+      else if (!process.env.KF_H3_STEPS) {
+        ready = false;
+        detail = "KF_H3_STEPS 없음(터보 LoRA 면 9, 없으면 50 — 파드 운영자에게)";
+      } else if (probe) {
+        const s = await reach(`${url.replace(/\/+$/, "")}/v1/models`);
+        ready = s === 200;
+        detail = ready ? "서버 살아 있음" : `서버가 ${s}`;
+      } else detail = "주소 있음(두드려 보지 않음)";
+    }
+    out.push({
+      cap: "video", id: p.id, label: p.model, ready, detail,
+      fix: ready ? undefined : p.id === "h3-pod" ? "KF_H3_URL=<SGLang 주소> KF_H3_STEPS=<9|50>" : whereToPut(p.keyName),
+      unitUsd: p.estimateUsd(sample), unit: "5초 720p 첫+끝 프레임", license: p.license, restrict: p.restrict,
+    });
+  }
+  return out;
+}
+
+function blender(): CapabilityProvider {
+  const lib = blenderLibDir();
+  const base = { cap: "blender" as const, id: "blender", label: "Blender 툰 3D(kf blender)", unitUsd: 0, unit: "샷 하나(로컬 렌더)", license: "Blender GPL — 굽힌 그림·영상은 만든 사람 것, 헬퍼(tools/blender)는 GPL-3.0 로 npm 묶음 밖" };
+  if (!hasBlenderLib(lib)) return { ...base, ready: false, detail: `헬퍼 없음: ${lib}`, fix: "레포의 tools/blender 를 받아 KF_BLENDER_LIB=<그 폴더>" };
+  try {
+    const b = findBlender();
+    return { ...base, ready: true, detail: `Blender ${b.version.join(".")} — 1920x1080 한 장 0.3–0.4초(M 맥)` };
+  } catch (e) {
+    return { ...base, ready: false, detail: (e instanceof Error ? e.message : String(e)).split(" — ")[0], fix: process.platform === "darwin" ? "brew install --cask blender (4.3 이상)" : "blender.org 에서 4.3 이상" };
+  }
+}
+
+// three.js 는 레포 안 의존성이라 늘 있다 — 렌더 크롬이 CanvasDrawElement 로 살아 있는 장면을 텍스처로 올린다
+function three(): CapabilityProvider[] {
+  const license = "three.js MIT";
+  return [
+    { cap: "three", id: "transition3d", label: "3D 전환(이음매 장면 — dive·portal·cards·shatter·zoomOut·fold)", ready: true, detail: "레포 안", unitUsd: 0, unit: "전환 하나", license },
+    { cap: "three", id: "stage3d", label: "화면 속 3D(입체 테마 무대)", ready: true, detail: "레포 안", unitUsd: 0, unit: "장면 하나", license },
+  ];
+}
+
+const musicDir = (): string => process.env.KF_MUSIC_DIR || fileURLToPath(new URL("../../../music/", import.meta.url));
+
+// 곡 모음만 여기서 센다 — 생성 음악·목소리 공급자는 목소리·음악 담당(src/music·src/tts)이 같은 꼴로 더한다
+function music(): CapabilityProvider[] {
+  const dir = musicDir();
+  const songs = existsSync(dir) ? readdirSync(dir).filter((f) => /\.(mp3|wav|m4a|aac|flac|ogg)$/i.test(f)) : [];
+  return [{ cap: "music", id: "library", label: "곡 모음", ready: songs.length > 0, detail: songs.length ? `${songs.length}곡(${dir})` : `비었다: ${dir}`, fix: songs.length ? undefined : "KF_MUSIC_DIR=<곡 폴더> 또는 --music 곡", unitUsd: 0, unit: "곡", license: "곡마다 music/README.md" }];
+}
+
+export async function capabilities(o: { probe?: boolean } = {}): Promise<CapabilityReport[]> {
+  const probe = o.probe ?? false;
+  const [img, vid] = await Promise.all([images(probe), videos(probe)]);
+  const all: CapabilityProvider[] = [...img, ...vid, blender(), ...three(), ...music(), ...voiceCapabilities(), ...musicGenCapabilities()];
+  return (["image", "video", "blender", "three", "music", "voice"] as Capability[]).map((cap) => {
+    const providers = all.filter((p) => p.cap === cap);
+    // 그림은 목록 순서(OG 기본 — 빠르고 실측된 길)가 권장, codex 는 0원 대안. 나머지는 제한 없는 것·싼 것 먼저
+    const usable = providers
+      .filter((p) => p.ready)
+      .sort((a, b) => Number(!!a.restrict) - Number(!!b.restrict) || (cap === "image" ? providers.indexOf(a) - providers.indexOf(b) : a.unitUsd - b.unitUsd));
+    return { cap, label: LABEL[cap], providers, best: usable[0] ?? null };
+  });
+}

package/packages/gen/src/generate.ts

@@ -128,6 +128,7 @@ async function store(
     elapsedMs,
     license: p.license,
     region: p.region,
+    ...(p.restrict ? { restrict: p.restrict } : {}),
     cacheKey: key,
     createdAt: new Date().toISOString(),
     width: pr.width,
@@ -154,7 +155,8 @@ async function makeImage(p: ImageProvider, req: ImageRequest, tmp: string): Prom
       raw = { ...again, costUsd: raw.costUsd + again.costUsd, notes: [...(again.notes ?? []), "alpha-failed", "chroma-key"] };
     }
   }
-  const { w, h } = apiSize(req.size);
+  // 공급자마다 그리는 크기가 다르다(OG 는 16의 배수, codex 는 세 꼴) — 실제로 나온 크기를 재서 맞춘다
+  const { width: w, height: h } = await probe(tmp);
   const [rw, rh] = req.size.split("x").map(Number);
   if (w !== rw || h !== rh) {
     await fitImage(tmp, tmp, rw, rh);
@@ -169,7 +171,7 @@ export async function genImage(id: string, req: ImageRequest, ctx: GenContext, p
   const key = cacheKey("img", p, req, inputs);
   const hit = fromCache(id, key, ctx);
   if (hit) return hit;
-  const est = estimateImageUsd(req);
+  const est = p.estimateUsd ? p.estimateUsd(req) : estimateImageUsd(req);
   const cap = ctx.imageMaxUsd ?? DEFAULT_IMAGE_MAX_USD;
   if (est > cap) throw new NeedsApproval(p.id, est, `그림 한 장 상한 $${cap} 초과`);
   mkdirSync(cacheDir(ctx), { recursive: true });

package/packages/gen/src/image/codex.ts

@@ -0,0 +1,117 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { KEY_BG } from "../media.ts";
+import type { ImageProvider, ImageRequest, RawResult } from "../types.ts";
+
+// ChatGPT 로그인으로 도는 codex CLI 의 내장 imagegen — API 키·요금 없이 구독 안에서 그린다(한 장 1–2분).
+// kasaterm pane 의 codex 는 pane 전용 홈을 세우는 래퍼라 PATH 에서 그 shim 을 빼고 순정 codex 를 찾는다
+export function codexBin(): string | null {
+  if (process.env.KF_CODEX) return existsSync(process.env.KF_CODEX) ? process.env.KF_CODEX : null;
+  const path = (process.env.PATH ?? "").split(":").filter((p) => !p.includes("kasaterm-shim-")).join(":");
+  const r = spawnSync("sh", ["-c", "command -v codex"], { encoding: "utf8", env: { ...process.env, PATH: path } });
+  const bin = r.stdout?.trim();
+  return r.status === 0 && bin ? bin : null;
+}
+
+export function codexLoggedIn(bin = codexBin()): boolean {
+  if (!bin) return false;
+  const r = spawnSync(bin, ["login", "status"], { encoding: "utf8", timeout: 10_000 });
+  return r.status === 0 && /logged in/i.test(`${r.stdout}${r.stderr}`);
+}
+
+// imagegen 이 받는 세 꼴 — 요청 크기와 비율이 가장 가까운 것으로 그린 뒤 generate.ts 가 잘라 맞춘다
+function orientation(size: string): string {
+  const [w, h] = size.split("x").map(Number);
+  const r = w / h;
+  return r > 1.2 ? "landscape 1536x1024" : r < 0.83 ? "portrait 1024x1536" : "square 1024x1024";
+}
+
+function run(bin: string, args: string[], cwd: string, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const p = spawn(bin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    p.stdout.on("data", (b: Buffer) => out.push(b));
+    p.stderr.on("data", (b: Buffer) => out.push(b));
+    // codex 가 가끔 멈춘다 — 끊고 실패로 돌린다
+    const timer = setTimeout(() => p.kill("SIGKILL"), timeoutMs);
+    p.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    p.on("close", (code) => {
+      clearTimeout(timer);
+      const log = Buffer.concat(out).toString();
+      if (code === 0) resolve(log);
+      else reject(new Error(`codex 실패(${code ?? "시간 초과"}): ${log.trim().split("\n").slice(-4).join(" / ").slice(0, 400)}`));
+    });
+  });
+}
+
+// 저장 지시를 안 따르면 codex 가 늘 쓰는 자리에서 이번에 생긴 그림을 찾는다
+function newestGenerated(since: number): string | null {
+  const root = join(homedir(), ".codex", "generated_images");
+  if (!existsSync(root)) return null;
+  let best: { p: string; t: number } | null = null;
+  const walk = (d: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/\.png$/i.test(e.name)) {
+        const t = statSync(p).mtimeMs;
+        if (t >= since && (!best || t > best.t)) best = { p, t };
+      }
+    }
+  };
+  walk(root);
+  return (best as { p: string } | null)?.p ?? null;
+}
+
+export function codexImage(): ImageProvider {
+  return {
+    id: "codex-imagegen",
+    kind: "img",
+    model: "codex imagegen (gpt-image, ChatGPT 요금제)",
+    license: "OpenAI 이용약관 — 출력물 권리는 사용자에게, 상업 사용 가능(ChatGPT 요금제 안, 추가 요금 없음)",
+    region: "ChatGPT 로그인(codex CLI) — 한국 사용 가능",
+    keyName: "codex",
+    available: () => codexLoggedIn(),
+    estimateUsd: () => 0,
+
+    async generate(o: ImageRequest): Promise<RawResult> {
+      const bin = codexBin();
+      if (!bin) throw new Error("codex CLI 가 없다 — npm i -g @openai/codex 뒤 codex login(ChatGPT 계정)");
+      const work = mkdtempSync(join(tmpdir(), "kf-codex-img-"));
+      const started = Date.now();
+      try {
+        const keyed = !!o.transparent;
+        const prompt = [
+          `Use $imagegen to create exactly one image, ${orientation(o.size)}, and save it as ./image.png in the current directory.`,
+          o.refs?.length ? "Use the attached image(s) as the reference — keep the same character, shapes and colors." : "",
+          o.prompt,
+          keyed ? KEY_BG : "",
+          "No text, letters, watermarks or logos unless the description above asks for them. Do not ask for confirmation. Do not create any other file.",
+        ].filter(Boolean).join("\n\n");
+        // -i 는 가변 인자라 프롬프트 앞에 두면 프롬프트까지 그림 파일로 먹는다 — 프롬프트 뒤에
+        const args = ["-c", "features.daemon_auto_start=false", "exec", "-s", "workspace-write", "--skip-git-repo-check", "-C", work, prompt];
+        if (o.refs?.length) args.push("-i", ...o.refs);
+        await run(bin, args, work, Number(process.env.KF_CODEX_TIMEOUT_MS ?? 420_000));
+        const file = existsSync(join(work, "image.png")) ? join(work, "image.png") : newestGenerated(started);
+        if (!file) throw new Error("codex 가 그림을 남기지 않았다(./image.png·~/.codex/generated_images 둘 다 없음)");
+        return {
+          bytes: readFileSync(file),
+          ext: "png",
+          model: "codex imagegen",
+          seed: null,
+          costUsd: 0,
+          costEstimated: false,
+          params: { size: orientation(o.size), refs: o.refs?.length ?? 0 },
+          notes: ["codex", ...(keyed ? ["chroma-key"] : [])],
+        };
+      } finally {
+        rmSync(work, { recursive: true, force: true });
+      }
+    },
+  };
+}

package/packages/gen/src/index.ts

@@ -1,6 +1,11 @@
 export type { Asset, AssetKind, AssetMeta, ImageProvider, ImageRequest, ProviderInfo, RawResult, VideoProvider, VideoRequest } from "./types.ts";
-export { findKey, hasKey, MissingKeyError, readKey, whereToPut } from "./keys.ts";
-export { DEFAULT_IMAGE, imageProviders, pickImage, pickVideo, videoProviders } from "./registry.ts";
+export { findKey, hasKey, howToGet, keyFile, MissingKeyError, readKey, whereToPut } from "./keys.ts";
+export { DEFAULT_IMAGE, imageProviders, pickImage, pickVideo, providerReady, videoProviders } from "./registry.ts";
+export { askTerminal, CAPABILITIES, parseAllow, WAIT, questionsMarkdown, questionsText, settle, type AnswerInput, type Capability, type Choice, type Question, type Settled } from "./ask.ts";
+export { capabilities, type CapabilityProvider, type CapabilityReport } from "./capabilities.ts";
+export { BLENDER_MIN, blenderLibDir, findBlender, hasBlenderLib } from "./blender.ts";
+export { codexBin, codexLoggedIn } from "./image/codex.ts";
+export { H3_RESTRICT } from "./video/h3.ts";
 export {
   cacheDir,
   cacheKey,
@@ -16,3 +21,6 @@ export {
 export { aspectOf, seam, seamFrames, still, type SeamOptions } from "./seam.ts";
 export { genSpecs, referencedIds, resolvePlan, type GenReport, type GenSpec } from "./plan.ts";
 export { retime } from "./media.ts";
+export { cutVoice, duration as audioDuration, findSilences, layVoices, voicedSpan } from "./audio.ts";
+export { alignWords, DEFAULT_STYLE, parseVoice, pickTts, speak, ttsProviders, voiceCapabilities, voiceQuestion, type Speech, type SpeechRequest, type TtsProvider, type Voice, type Word } from "./tts/index.ts";
+export { addToLibrary, byMood, genMusic, listLibrary, MOOD_PROMPT, MOOD_TAGS, musicDir, musicGenCapabilities, musicLength, musicProviders, musicQuestion, pickMusic, type MusicAsset, type MusicProvider, type Track } from "./music/index.ts";

package/packages/gen/src/keys.ts

@@ -10,8 +10,34 @@ const SOURCES: Record<string, { env: string[]; files: string[] }> = {
   gemini: { env: ["GEMINI_API_KEY", "GOOGLE_API_KEY"], files: ["~/.config/gemini.key"] },
   ltx: { env: ["LTX_API_KEY"], files: ["~/.config/ltx.key"] },
   h3: { env: ["KF_H3_URL"], files: [] },
+  elevenlabs: { env: ["ELEVENLABS_API_KEY", "XI_API_KEY"], files: ["~/.config/elevenlabs.key"] },
+  dashscope: { env: ["DASHSCOPE_API_KEY"], files: ["~/.config/dashscope.key"] },
+  "qwen3-tts": { env: ["KF_QWEN3_TTS_URL"], files: [] },
 };
 
+// 없는 키를 물을 때 「어디서 받아 어디에 넣나」를 같이 보인다 — 받는 곳은 공급자 콘솔, 넣기는 kf setup key 가 값을 숨겨 받아 파일로
+const HELP: Record<string, { label: string; get: string }> = {
+  opengateway: { label: "OpenGateway 키", get: "OpenGateway 콘솔(opengateway.ai)에서 API 키" },
+  fal: { label: "fal 키", get: "fal.ai/dashboard/keys" },
+  minimax: { label: "MiniMax 키", get: "platform.minimax.io 의 API 키" },
+  gemini: { label: "Gemini 키", get: "aistudio.google.com/apikey" },
+  ltx: { label: "LTX 키", get: "ltx.io 콘솔의 API 키" },
+  h3: { label: "사내 H3 주소", get: "파드 운영자에게 SGLang 주소(닫힌 망이면 터널) — 걸음 수 KF_H3_STEPS(터보 LoRA 9·없으면 50)도 같이" },
+  elevenlabs: { label: "ElevenLabs 키", get: "elevenlabs.io/app/settings/api-keys" },
+  dashscope: { label: "DashScope 키", get: "Alibaba Cloud Model Studio(dashscope) 콘솔의 API 키" },
+  "qwen3-tts": { label: "로컬 Qwen3-TTS 서버 주소", get: "tools/tts 의 서버를 띄운 주소" },
+};
+
+// 주소(h3·로컬 서버)는 비밀이 아니라 환경 변수로, 나머지는 kf setup key 로
+export function howToGet(name: string): string {
+  const h = HELP[name];
+  const env = sources(name).env;
+  const put = name === "h3" || name.endsWith("-tts") ? `${env.join("·")}=<주소>` : `kf setup key ${name}(값을 숨겨 받아 ~/.config/kasaframe/keys/${name} 에) 또는 ${whereToPut(name)}`;
+  return `${h?.label ?? name}: ${h?.get ?? "공급자 콘솔"} → ${put}`;
+}
+
+export const keyFile = (name: string): string => expand(`~/.config/kasaframe/keys/${name}`);
+
 export class MissingKeyError extends Error {
   keyName: string;
   constructor(keyName: string) {