kasaframe 0.0.0-stage → 0.1.3

package/packages/gen/src/tts/elevenlabs.ts

@@ -0,0 +1,84 @@
+import { hasKey, readKey } from "../keys.ts";
+import { json } from "../video/http.ts";
+import type { TtsProvider, Word } from "./types.ts";
+
+// 키가 없어 실호출로 검증하지 못했다 — 요청·응답 모양은 ElevenLabs API 문서(2026-10, text-to-speech/convert-with-timestamps) 그대로.
+// eleven_v4 는 Text to Dialogue 로만 열려 있어 낱말 시각을 주는 with-timestamps 에는 multilingual_v2(문서 기본, 긴 글에 가장 안정)를 쓴다
+const BASE = process.env.KF_ELEVENLABS_BASE ?? "https://api.elevenlabs.io";
+const MODEL = process.env.KF_ELEVENLABS_MODEL ?? "eleven_multilingual_v2";
+// 1천 글자당 — multilingual·v3 $0.08, flash·turbo $0.04 (elevenlabs.io/pricing/api)
+const PER_1K = /flash|turbo/.test(MODEL) ? 0.04 : 0.08;
+
+// 기본 제공 목소리 — 이름으로 고르면 id 로 바꿔 보낸다. 계정에서 만든 목소리는 id 를 그대로 준다
+const VOICES: { id: string; name: string; label: string }[] = [
+  { id: "JBFqnCBsd6RMkjVDRZzb", name: "George", label: "남 · 따뜻하고 낮은 이야기꾼" },
+  { id: "onwK4e9ZLuTAKqWW03F9", name: "Daniel", label: "남 · 깊고 단단한 낭독" },
+  { id: "nPczCjzI2devNBz1zQrb", name: "Brian", label: "남 · 깊고 차분한 내레이션" },
+  { id: "XrExE9yKIg1WjnnlVkGX", name: "Matilda", label: "여 · 차분하고 따뜻한 설명" },
+  { id: "Xb7hH8MSUJpSbSDYk0k2", name: "Alice", label: "여 · 또렷한 설명" },
+  { id: "pFZP5JQG7iQjIQuC4Bku", name: "Lily", label: "여 · 부드럽고 낮은 목소리" },
+];
+
+// 글자마다 온 시각을 띄어쓰기로 묶어 낱말로 — 자막 판은 어절 단위로 끊는다
+export function charsToWords(chars: string[], starts: number[], ends: number[]): Word[] {
+  const out: Word[] = [];
+  let cur: Word | null = null;
+  chars.forEach((c, i) => {
+    if (/\s/.test(c)) {
+      if (cur) out.push(cur);
+      cur = null;
+      return;
+    }
+    if (!cur) cur = { text: c, from: starts[i], to: ends[i] };
+    else {
+      cur.text += c;
+      cur.to = ends[i];
+    }
+  });
+  if (cur) out.push(cur);
+  return out;
+}
+
+export function elevenlabsTts(): TtsProvider {
+  return {
+    id: "elevenlabs",
+    label: "ElevenLabs",
+    model: MODEL,
+    keyName: "elevenlabs",
+    license: "ElevenLabs 약관 — 유료 요금제 출력물 상업 가능(무료는 출처 표기)",
+    region: "전 세계 API",
+    timestamps: true,
+    verified: false,
+    voices: VOICES.map((v) => ({ id: v.name, label: v.label })),
+    defaultVoice: "George",
+    ready: () => hasKey("elevenlabs"),
+    estimateUsd: (text) => (text.length / 1000) * PER_1K,
+
+    async synth(o) {
+      const id = VOICES.find((v) => v.name.toLowerCase() === o.voice.toLowerCase())?.id ?? o.voice;
+      const body: Record<string, unknown> = {
+        text: o.text,
+        model_id: MODEL,
+        voice_settings: { stability: 0.55, similarity_boost: 0.75, style: 0, speed: 1, use_speaker_boost: true },
+      };
+      // multilingual_v2 는 language_code 를 받지 않는다(문서)
+      if (o.lang && !/multilingual_v2/.test(MODEL)) body.language_code = o.lang;
+      const r = await json(
+        `${BASE}/v1/text-to-speech/${encodeURIComponent(id)}/with-timestamps?output_format=mp3_44100_128`,
+        { method: "POST", headers: { "xi-api-key": readKey("elevenlabs"), "Content-Type": "application/json" }, body: JSON.stringify(body) },
+        "ElevenLabs",
+      );
+      const a = r.alignment ?? r.normalized_alignment;
+      if (!r.audio_base64) throw new Error(`ElevenLabs 응답에 소리가 없다: ${JSON.stringify(r).slice(0, 200)}`);
+      return {
+        bytes: Buffer.from(r.audio_base64, "base64"),
+        ext: "mp3",
+        model: MODEL,
+        words: a ? charsToWords(a.characters, a.character_start_times_seconds, a.character_end_times_seconds) : undefined,
+        costUsd: (o.text.length / 1000) * PER_1K,
+        costEstimated: true,
+        params: { voice: id, model_id: MODEL },
+      };
+    },
+  };
+}

package/packages/gen/src/tts/gemini.ts

@@ -0,0 +1,73 @@
+import { findKey, readKey } from "../keys.ts";
+import { pcmToWav } from "../audio.ts";
+import { json } from "../video/http.ts";
+import type { TtsProvider } from "./types.ts";
+
+// Gemini API Interactions(2026-10, ai.google.dev/gemini-api/docs/speech-generation). 낱말 시각은 주지 않는다 — 무음 자리로 맞춘다
+const BASE = "https://generativelanguage.googleapis.com/v1beta";
+const MODEL = process.env.KF_GEMINI_TTS_MODEL ?? "gemini-3.8-flash-tts";
+// 1M 토큰당 — 소리 출력은 1초에 25토큰(2026-12-31 까지 값). lite 는 출력 $6
+const PRICE = /lite/.test(MODEL) ? { in: 0.5, out: 6 } : { in: 0.5, out: 9 };
+// 한국어 낭독은 1초에 6글자 안팎
+const CHARS_PER_SEC = 6;
+
+const VOICES = [
+  { id: "Charon", label: "남 · 차분한 정보 전달(Informative)" },
+  { id: "Gacrux", label: "여 · 성숙하고 낮은(Mature)" },
+  { id: "Algenib", label: "남 · 거칠고 낮은(Gravelly)" },
+  { id: "Sulafat", label: "여 · 따뜻한(Warm)" },
+  { id: "Schedar", label: "남 · 고른(Even)" },
+  { id: "Vindemiatrix", label: "여 · 부드러운(Gentle)" },
+  { id: "Kore", label: "여 · 단단한(Firm)" },
+  { id: "Orus", label: "남 · 단단한(Firm)" },
+];
+
+export function geminiTts(): TtsProvider {
+  return {
+    id: "gemini",
+    label: "Gemini TTS",
+    model: MODEL,
+    keyName: "gemini",
+    license: "Google 생성형 AI 약관 — 출력물 소유권 주장 없음, 상업 가능",
+    region: "Gemini API 제공 지역(한국 포함)",
+    timestamps: false,
+    verified: true,
+    voices: VOICES,
+    defaultVoice: "Charon",
+    ready: () => findKey("gemini") !== null,
+    estimateUsd: (text) => ((text.length / CHARS_PER_SEC) * 25 * PRICE.out + text.length * PRICE.in) / 1e6,
+
+    async synth(o) {
+      const content: Record<string, unknown> = { type: "text", text: o.text };
+      if (o.style) content.annotations = [{ type: "speech_metadata", style: o.style }];
+      const body = {
+        model: MODEL,
+        input: [{ type: "user_input", content: [content] }],
+        response_format: { type: "audio", mime_type: "audio/l16", sample_rate: 24000 },
+        generation_config: { speech_config: [{ voice: o.voice }] },
+      };
+      const r = await json(`${BASE}/interactions`, { method: "POST", headers: { "x-goog-api-key": readKey("gemini"), "Content-Type": "application/json" }, body: JSON.stringify(body) }, "Gemini TTS");
+      const audio = (r.steps ?? [])
+        .filter((s: { type: string }) => s.type === "model_output")
+        .flatMap((s: { content?: { type: string; data?: string; mime_type?: string }[] }) => s.content ?? [])
+        .filter((c: { type: string }) => c.type === "audio")
+        .at(-1);
+      if (!audio?.data) throw new Error(`Gemini TTS 응답에 소리가 없다: ${JSON.stringify(r).slice(0, 200)}`);
+      const raw = Buffer.from(audio.data, "base64");
+      // l16 을 달라고 했지만 머리 붙은 wav 가 오면 그대로
+      const bytes = raw.subarray(0, 4).toString() === "RIFF" ? raw : pcmToWav(raw, 24000, 1);
+      const out = r.usage?.total_output_tokens ?? r.usage?.output_tokens;
+      const inp = r.usage?.total_input_tokens ?? r.usage?.input_tokens;
+      const real = typeof out === "number";
+      const sec = (bytes.length - 44) / (24000 * 2);
+      return {
+        bytes,
+        ext: "wav",
+        model: MODEL,
+        costUsd: real ? (out * PRICE.out + (inp ?? 0) * PRICE.in) / 1e6 : (sec * 25 * PRICE.out + o.text.length * PRICE.in) / 1e6,
+        costEstimated: !real,
+        params: { voice: o.voice, style: o.style ?? null },
+      };
+    },
+  };
+}

package/packages/gen/src/tts/index.ts

@@ -0,0 +1,241 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type Choice, type Question, WAIT } from "../ask.ts";
+import { findSilences, voicedSpan } from "../audio.ts";
+import type { CapabilityProvider } from "../capabilities.ts";
+import { cacheDir, sha256 } from "../generate.ts";
+import { howToGet, whereToPut } from "../keys.ts";
+import { dashscopeTts } from "./dashscope.ts";
+import { elevenlabsTts } from "./elevenlabs.ts";
+import { geminiTts } from "./gemini.ts";
+import { localTts } from "./local.ts";
+import type { SpeechRequest, TtsProvider, Word } from "./types.ts";
+
+export type { SpeechRaw, SpeechRequest, TtsProvider, Voice, Word } from "./types.ts";
+export { charsToWords } from "./elevenlabs.ts";
+
+// 고르는 순서 — 낱말 시각을 직접 주는 ElevenLabs 먼저, 그다음 싸고 실호출로 확인한 Gemini
+export function ttsProviders(): TtsProvider[] {
+  return [elevenlabsTts(), geminiTts(), dashscopeTts(), localTts()];
+}
+
+export function pickTts(engine: string): TtsProvider {
+  const p = ttsProviders().find((x) => x.id === engine);
+  if (!p) throw new Error(`목소리 엔진 없음: ${engine} (있는 것: ${ttsProviders().map((x) => x.id).join(" ")})`);
+  return p;
+}
+
+// "gemini:Charon" → 엔진·목소리. "none" 이면 목소리 없이 자막만. 목소리를 빼면 그 엔진 기본
+export function parseVoice(v: string): { engine: string; voice: string } | null {
+  if (!v || v === "none") return null;
+  const i = v.indexOf(":");
+  const engine = i < 0 ? v : v.slice(0, i);
+  const p = pickTts(engine);
+  return { engine, voice: i < 0 ? p.defaultVoice : v.slice(i + 1) };
+}
+
+// 차분하고 낮은 낭독 — 용도 틀의 분위기(deep)와 같은 결
+export const DEFAULT_STYLE = "차분하고 낮은 다큐멘터리 내레이션. 서두르지 않고 문장 끝을 내려 놓는다";
+
+export interface Speech {
+  path: string;
+  words: Word[];
+  voiced: { from: number; to: number }; // 앞뒤 무음을 뺀 말 구간(조각 기준 초)
+  duration: number;
+  engine: string;
+  model: string;
+  voice: string;
+  costUsd: number;
+  costEstimated: boolean;
+  license: string;
+  cached: boolean;
+}
+
+// 문장 하나를 읽혀 outDir/<id>.wav|mp3 + <id>.json(낱말 시각). 같은 글·목소리·모델은 캐시에서 0원
+export async function speak(id: string, req: SpeechRequest, ctx: { outDir: string; cacheDir?: string; log?: (l: string) => void }, engine: string): Promise<Speech> {
+  const p = pickTts(engine);
+  if (!p.ready()) throw new Error(`${p.label} 를 못 쓴다 — ${whereToPut(p.keyName)}`);
+  const key = sha256(JSON.stringify({ kind: "tts", provider: p.id, model: p.model, text: req.text, voice: req.voice, lang: req.lang ?? null, style: req.style ?? null }));
+  const dir = cacheDir(ctx);
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(ctx.outDir, { recursive: true });
+  const metaPath = join(dir, `${key}.json`);
+  let cached = existsSync(metaPath);
+  let meta: Omit<Speech, "path" | "cached"> & { file: string };
+  if (cached) meta = JSON.parse(readFileSync(metaPath, "utf8"));
+  if (!cached || !existsSync(join(dir, meta!.file))) {
+    cached = false;
+    ctx.log?.(`목소리 ${id}: ${p.id} ${req.voice} 견적 $${p.estimateUsd(req.text).toFixed(4)}`);
+    const raw = await retryBusy(() => p.synth(req), { log: ctx.log });
+    const file = `${key}.${raw.ext}`;
+    writeFileSync(join(dir, file), raw.bytes);
+    const span = await voicedSpan(join(dir, file));
+    // 공급자가 준 시각만 캐시에 — 숨 자리로 맞춘 시각은 꺼낼 때마다 다시 맞춰 맞추는 법이 나아지면 캐시 소리에도 먹는다
+    meta = { file, words: raw.words ?? [], voiced: { from: span.from, to: span.to }, duration: span.total, engine: p.id, model: raw.model, voice: req.voice, costUsd: Number(raw.costUsd.toFixed(5)), costEstimated: raw.costEstimated, license: p.license };
+    writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`);
+  }
+  if (!meta!.words.length || !p.timestamps) meta!.words = await alignWords(req.text, join(dir, meta!.file), meta!.voiced);
+  const ext = meta!.file.split(".").pop()!;
+  const path = join(ctx.outDir, `${id}.${ext}`);
+  copyFileSync(join(dir, meta!.file), path);
+  const { file: _f, ...rest } = meta!;
+  writeFileSync(join(ctx.outDir, `${id}.json`), `${JSON.stringify({ id, text: req.text, ...rest, cached }, null, 2)}\n`);
+  return { ...rest, path, cached };
+}
+
+// kf narrate 는 줄을 동시에 읽힌다 — 분당 호출 수가 빡빡한 키(Gemini 무료 등급 등)는 429 를 낸다. 물러섰다 다시, 다른 실패는 바로
+const BUSY = new Set([429, 503]);
+export async function retryBusy<T>(fn: () => Promise<T>, o: { waits?: number[]; log?: (l: string) => void; sleep?: (ms: number) => Promise<void> } = {}): Promise<T> {
+  const waits = o.waits ?? [5000, 10000, 20000, 40000];
+  const sleep = o.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  for (let i = 0; ; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      const status = (e as { status?: number }).status;
+      if (!status || !BUSY.has(status) || i >= waits.length) throw e;
+      o.log?.(`목소리: 공급자가 바쁨(${status}) — ${waits[i] / 1000}초 뒤 다시`);
+      await sleep(waits[i]);
+    }
+  }
+}
+
+const spoken = (s: string) => Math.max(1, s.replace(/[\s,.?!…:;·"'“”‘’()\-]/g, "").length);
+
+// 마디 경계(글자 비율로 어림한 자리)를 숨에 순서대로 짝짓는다 — 하나씩 가까운 숨을 고르면 앞에서 어긋난 어림이 뒤까지 끈다.
+// 짝 비용 = 거리 - 긴 숨 덤, 짝 없는 경계는 SKIP(어림 자리 그대로). 경계에 안 쓰인 숨(마디 안 숨)은 비용 없다
+const SKIP = 1.0;
+export function matchPauses(expect: number[], pauses: { from: number; to: number }[]): number[] {
+  const k = expect.length;
+  const m = pauses.length;
+  const cost = Array.from({ length: k + 1 }, () => new Array<number>(m + 1).fill(Infinity));
+  const back = Array.from({ length: k + 1 }, () => new Array<0 | 1 | 2>(m + 1).fill(0));
+  for (let j = 0; j <= m; j++) cost[0][j] = 0;
+  for (let i = 1; i <= k; i++) {
+    for (let j = 0; j <= m; j++) {
+      // 0: 경계 i 를 짝 없이 · 1: 숨 j 를 안 쓰고 · 2: 경계 i ↔ 숨 j
+      let best = cost[i - 1][j] + SKIP;
+      let how: 0 | 1 | 2 = 0;
+      if (j > 0 && cost[i][j - 1] < best) {
+        best = cost[i][j - 1];
+        how = 1;
+      }
+      if (j > 0) {
+        const p = pauses[j - 1];
+        const c = cost[i - 1][j - 1] + Math.abs((p.from + p.to) / 2 - expect[i - 1]) - 0.5 * Math.min(p.to - p.from, 0.6);
+        if (c < best) {
+          best = c;
+          how = 2;
+        }
+      }
+      cost[i][j] = best;
+      back[i][j] = how;
+    }
+  }
+  const out = new Array<number>(k).fill(-1);
+  for (let i = k, j = m; i > 0; ) {
+    const how = back[i][j];
+    if (how === 2) out[--i] = --j;
+    else if (how === 1) j--;
+    else i--;
+  }
+  return out;
+}
+
+// 시각을 안 주는 공급자 — 쉼표·마침표 자리를 말 사이 숨(무음)에 붙이고, 마디 안 낱말은 글자 수 비율로 편다
+export async function alignWords(text: string, path: string, span?: { from: number; to: number }): Promise<Word[]> {
+  const tokens = text.trim().split(/\s+/).filter(Boolean);
+  if (!tokens.length) return [];
+  const { from: t0, to: t1 } = span ?? (await voicedSpan(path));
+  const total = tokens.reduce((a, w) => a + spoken(w), 0);
+  // 마디 끝 = 문장부호로 끝나는 어절(마지막 어절은 늘 끝)
+  const ends = tokens.map((w, i) => i < tokens.length - 1 && /[,.?!…:;]$/.test(w)).flatMap((e, i) => (e ? [i] : []));
+  const pauses = (await findSilences(path, { db: -38, min: 0.12 })).filter((s) => s.from > t0 + 0.05 && s.to < t1 - 0.05);
+  // 마디 경계의 글자 비율 자리
+  const expect: number[] = [];
+  let acc = 0;
+  for (let i = 0, k = 0; i < tokens.length && k < ends.length; i++) {
+    acc += spoken(tokens[i]);
+    if (i === ends[k]) {
+      expect.push(t0 + ((t1 - t0) * acc) / total);
+      k++;
+    }
+  }
+  const bounds = matchPauses(expect, pauses).map((j, i) => ({ at: ends[i], end: j < 0 ? expect[i] : pauses[j].from, start: j < 0 ? expect[i] : pauses[j].to }));
+  const out: Word[] = [];
+  let start = t0;
+  let first = 0;
+  for (const b of [...bounds, { at: tokens.length - 1, end: t1, start: t1 }]) {
+    const seg = tokens.slice(first, b.at + 1);
+    const n = seg.reduce((a, w) => a + spoken(w), 0);
+    let t = start;
+    for (const w of seg) {
+      const d = ((b.end - start) * spoken(w)) / n;
+      out.push({ text: w, from: +t.toFixed(3), to: +(t + d).toFixed(3) });
+      t += d;
+    }
+    start = b.start;
+    first = b.at + 1;
+  }
+  return out;
+}
+
+// 묻기 틀(ask.ts)에 얹는 목소리 질문. 보기 차례는 로컬 Qwen3(KF_QWEN3_TTS_URL 이 있을 때) · ElevenLabs · 자막만 · 그 밖 엔진 — 첫째가 권장.
+// 키 없는 ElevenLabs 는 넣는 법을 붙인 보기(wait)로 서고, 로컬도 ElevenLabs 도 없으면 그 밖 엔진으로 조용히 넘어가지 않게 missing.
+// voices 는 틀(template.json narration.voices)이 엔진마다 박은 목소리 — 같은 틀이면 늘 같은 목소리. chars 는 견적용 대본 글자 수(모르면 쇼츠 한 편 300자)
+// ready 는 쓸 수 있는 엔진 id(생성 능력 표에서) — 안 주면 키를 직접 본다
+export function voiceQuestion(o: { chars?: number; voices?: Record<string, string>; ready?: string[] } = {}): Question {
+  const sample = "가".repeat(o.chars ?? 300);
+  const all = ttsProviders();
+  const ready = new Set(all.filter((p) => (o.ready ? o.ready.includes(p.id) : p.ready())).map((p) => p.id));
+  const note = (p: TtsProvider) => [p.verified ? "" : "실호출 미검증", p.timestamps ? "낱말 시각 정확" : "낱말 시각은 숨 자리로 맞춤"].filter(Boolean).join(" · ");
+  const pick = (p: TtsProvider): Choice => {
+    const v = p.voices.find((x) => x.id === (o.voices?.[p.id] ?? p.defaultVoice)) ?? { id: o.voices?.[p.id] ?? p.defaultVoice, label: "틀이 정한 목소리" };
+    return { value: `${p.id}:${v.id}`, label: `${p.label} ${v.id} — ${v.label}`, costUsd: p.estimateUsd(sample), note: note(p) };
+  };
+  const local = all.find((p) => p.id === "local")!;
+  const eleven = all.find((p) => p.id === "elevenlabs")!;
+  const head = ready.has("local") ? [pick(local)] : [];
+  const choices = [
+    ...head,
+    ready.has("elevenlabs") ? pick(eleven) : { value: WAIT, label: `${eleven.label} 키를 넣고 다시`, note: howToGet(eleven.keyName) },
+    { value: "none", label: "목소리 없이 — 자막만", costUsd: 0 },
+    ...all.filter((p) => p.id !== "local" && p.id !== "elevenlabs" && ready.has(p.id)).map(pick),
+  ].slice(0, 4);
+  const missing = !ready.has("local") && !ready.has("elevenlabs");
+  return {
+    id: "voice",
+    cap: "voice",
+    ask: missing ? "내레이션 목소리 — 로컬 Qwen3(KF_QWEN3_TTS_URL)도 ElevenLabs 키도 없다" : "내레이션 목소리는?",
+    header: "목소리",
+    choices,
+    default: choices[0].value,
+    skip: head[0]?.value ?? "none",
+    flag: "--voice",
+    ...(missing ? { missing: true } : {}),
+    accepts: (v: string) => {
+      try {
+        const engine = parseVoice(v)?.engine;
+        return !engine || (o.ready ? o.ready.includes(engine) : pickTts(engine).ready());
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+// 생성 능력 표(capabilities)의 목소리 칸
+export function voiceCapabilities(): CapabilityProvider[] {
+  const sample = "가".repeat(300);
+  return ttsProviders().map((p) => ({
+    cap: "voice",
+    id: p.id,
+    label: `${p.label} ${p.model}`,
+    ready: p.ready(),
+    detail: p.ready() ? `${p.id === "local" ? "주소 있음" : "키 있음"}(키만 봄)${p.verified ? "" : " · 실호출 미검증"} · 목소리 ${p.voices.map((v) => v.id).join("·")}` : p.id === "local" ? "KF_QWEN3_TTS_URL 없음" : "키 없음",
+    fix: p.ready() ? undefined : p.id === "local" ? "메모리 넉넉한 기계에 tools/tts/qwen3_tts_server.py → KF_QWEN3_TTS_URL=<주소>" : whereToPut(p.keyName),
+    unitUsd: p.estimateUsd(sample),
+    unit: "쇼츠 한 편 대본(300자)",
+    license: p.license,
+  }));
+}

package/packages/gen/src/tts/local.ts

@@ -0,0 +1,42 @@
+import { findKey } from "../keys.ts";
+import type { TtsProvider } from "./types.ts";
+
+// 로컬 Qwen3-TTS(공개 가중치 Apache-2.0)는 이 기계에서 바로 띄우지 않는다 — 1.7B 를 여러 칸이 같이 쓰는 노트북에 올리면 메모리가 넘친다.
+// 메모리 넉넉한 기계에 tools/tts/qwen3_tts_server.py 를 띄우고 KF_QWEN3_TTS_URL 로 주소만 준다. 설정돼 있을 때만 보기에 나온다
+const VOICES = [
+  { id: "Sohee", label: "여 · 한국어 화자" },
+  { id: "Ryan", label: "남 · 리듬감 있는" },
+  { id: "Serena", label: "여 · 부드러운" },
+  { id: "Aiden", label: "남 · 밝은" },
+  { id: "Vivian", label: "여 · 또렷한" },
+];
+const LANG: Record<string, string> = { ko: "Korean", en: "English", ja: "Japanese", zh: "Chinese" };
+
+export function localTts(): TtsProvider {
+  return {
+    id: "local",
+    label: "로컬 Qwen3-TTS",
+    model: process.env.KF_QWEN3_TTS_MODEL ?? "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+    keyName: "qwen3-tts",
+    license: "Qwen3-TTS 가중치 Apache-2.0 — 출력물 상업 가능",
+    region: "자체 호스팅",
+    timestamps: false,
+    verified: false,
+    voices: VOICES,
+    defaultVoice: "Sohee",
+    ready: () => findKey("qwen3-tts") !== null,
+    estimateUsd: () => 0,
+
+    async synth(o) {
+      const url = findKey("qwen3-tts")!.replace(/\/+$/, "");
+      const r = await fetch(`${url}/tts`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: o.text, speaker: o.voice, language: LANG[o.lang ?? ""] ?? "Auto", instruct: o.style ?? "" }),
+        signal: AbortSignal.timeout(10 * 60_000),
+      });
+      if (!r.ok) throw new Error(`로컬 Qwen3-TTS ${r.status}: ${(await r.text()).slice(0, 200)}`);
+      return { bytes: new Uint8Array(await r.arrayBuffer()), ext: "wav", model: this.model, costUsd: 0, costEstimated: false, params: { voice: o.voice } };
+    },
+  };
+}

package/packages/gen/src/tts/types.ts

@@ -0,0 +1,44 @@
+// 낱말 하나와 그 시각(조각 기준 초) — 자막이 이 시각 그대로 끊긴다
+export interface Word {
+  text: string;
+  from: number;
+  to: number;
+}
+
+export interface Voice {
+  id: string; // --voice <엔진>:<id> 의 id
+  label: string; // 사람이 고르는 한 줄(성별·결)
+}
+
+export interface SpeechRequest {
+  text: string;
+  voice: string;
+  lang?: string; // "ko" 같은 ISO 639-1 — 공급자 꼴로 바꿔 보낸다
+  style?: string; // 「차분하고 낮게」 같은 연기 지시 — 받는 공급자만 쓴다
+}
+
+export interface SpeechRaw {
+  bytes: Uint8Array;
+  ext: "wav" | "mp3";
+  model: string;
+  words?: Word[]; // 공급자가 시각을 주면(ElevenLabs with-timestamps). 없으면 무음 자리로 맞춘다
+  costUsd: number;
+  costEstimated: boolean;
+  params: Record<string, unknown>;
+}
+
+export interface TtsProvider {
+  id: string; // --voice 의 엔진 이름
+  label: string;
+  model: string;
+  keyName: string;
+  license: string;
+  region: string;
+  timestamps: boolean; // 낱말 시각을 직접 주는지
+  verified: boolean; // 실호출로 확인했는지 — 아니면 고르는 글에 적는다
+  voices: Voice[];
+  defaultVoice: string;
+  ready(): boolean;
+  estimateUsd(text: string): number;
+  synth(o: SpeechRequest): Promise<SpeechRaw>;
+}

package/packages/gen/src/types.ts

@@ -0,0 +1,90 @@
+export type AssetKind = "img" | "vid";
+
+// 자산 옆 <id>.json. 같은 것을 다시 만들지, 얼마 들었는지, 어디에 써도 되는지를 이 파일 하나로 판단한다.
+export interface AssetMeta {
+  id: string;
+  kind: AssetKind;
+  file: string; // 메타 파일 기준 상대 경로
+  provider: string;
+  model: string;
+  prompt: string;
+  seed: number | null;
+  params: Record<string, unknown>;
+  inputs: { role: string; sha256: string }[];
+  costUsd: number;
+  costEstimated: boolean; // 응답에 실제 사용량이 없어 단가표로 계산했으면 true
+  elapsedMs: number;
+  license: string;
+  region: string;
+  restrict?: string; // 회사·바깥 결과물에 걸리는 제한(공급자의 restrict) — kf make --finish 가 결과 메타로 모은다
+  cacheKey: string;
+  createdAt: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  fps?: number;
+  notes?: string[];
+}
+
+export interface Asset {
+  path: string;
+  meta: AssetMeta;
+  cached: boolean;
+}
+
+export interface ImageRequest {
+  prompt: string;
+  size: string; // "1536x1024" 처럼. 모델이 못 받는 크기면 가까운 크기로 만든 뒤 잘라 맞춘다
+  refs?: string[];
+  transparent?: boolean;
+  quality?: string;
+}
+
+export interface VideoRequest {
+  prompt: string;
+  firstFrame?: string;
+  lastFrame?: string;
+  duration: number;
+  aspect: string; // "16:9" · "9:16" · "1:1"
+  seed?: number;
+  resolution?: string; // "480p" · "720p" · "1080p"
+}
+
+// 공급자가 돌려주는 날것. 캐시·메타·파일 이름은 generate.ts 가 붙인다.
+export interface RawResult {
+  bytes: Uint8Array;
+  ext: string;
+  model: string;
+  seed: number | null;
+  costUsd: number;
+  costEstimated: boolean;
+  params: Record<string, unknown>;
+  notes?: string[];
+}
+
+export interface ProviderInfo {
+  id: string;
+  kind: AssetKind;
+  model: string;
+  license: string;
+  region: string;
+  keyName: string;
+  restrict?: string; // 회사·바깥 결과물에 걸리는 라이선스·지역 제한 — 묻는 글·자산 메타에 그대로 남는다
+  available?(): boolean; // 키 말고 로그인·실행 파일로 서는 공급자(codex) — 없으면 keyName 의 키 유무
+  variant?: Record<string, unknown>; // 같은 모델이라도 결과를 바꾸는 서버 설정(걸음 수 등) — 캐시 키에 들어간다
+}
+
+export interface ImageProvider extends ProviderInfo {
+  kind: "img";
+  estimateUsd?(o: ImageRequest): number; // 없으면 OG 토큰 단가표
+  generate(o: ImageRequest): Promise<RawResult>;
+  edit?(o: ImageRequest): Promise<RawResult>;
+}
+
+export interface VideoProvider extends ProviderInfo {
+  kind: "vid";
+  durations: number[]; // 받을 수 있는 길이(초). 그 사이 값은 가장 가까운 위로 올린다
+  firstLast: boolean; // 끝 프레임까지 받는지 — 이음매 전환에는 이게 필요하다
+  estimateUsd(o: VideoRequest): number;
+  generate(o: VideoRequest): Promise<RawResult>;
+}