kasaframe 0.1.1 → 0.1.3

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

@@ -0,0 +1,41 @@
+import { hasKey, readKey } from "../keys.ts";
+import type { MusicProvider } from "./types.ts";
+
+// 키가 없어 실호출로 검증하지 못했다 — 모양은 ElevenLabs API 문서(2026-10, music/compose) 그대로. 200 이면 소리 파일 날것이 온다
+const BASE = process.env.KF_ELEVENLABS_BASE ?? "https://api.elevenlabs.io";
+const MODEL = process.env.KF_ELEVENLABS_MUSIC_MODEL ?? "music_v2_5";
+// 1분에 $0.15 (elevenlabs.io/pricing/api)
+const PER_MIN = 0.15;
+
+export function elevenlabsMusic(): MusicProvider {
+  return {
+    id: "elevenlabs-music",
+    label: "Eleven Music",
+    model: MODEL,
+    keyName: "elevenlabs",
+    license: "Eleven Music 약관 — 유료 요금제는 온·오프라인 상업 가능(영화·TV·라디오는 Enterprise Music 만), 무료는 출처 표기·내려받기 불가",
+    region: "전 세계 API(유료 요금제)",
+    verified: false,
+    maxSec: 300,
+    ready: () => hasKey("elevenlabs"),
+    estimateUsd: (sec) => (sec / 60) * PER_MIN,
+
+    async compose(o) {
+      const ms = Math.min(600_000, Math.max(3000, Math.ceil(o.duration * 1000)));
+      const r = await fetch(`${BASE}/v1/music?output_format=mp3_44100_128`, {
+        method: "POST",
+        headers: { "xi-api-key": readKey("elevenlabs"), "Content-Type": "application/json" },
+        body: JSON.stringify({ prompt: o.prompt, music_length_ms: ms, model_id: MODEL, force_instrumental: true }),
+      });
+      if (!r.ok) throw new Error(`Eleven Music ${r.status}: ${(await r.text()).slice(0, 300)}`);
+      return {
+        bytes: new Uint8Array(await r.arrayBuffer()),
+        ext: "mp3",
+        model: MODEL,
+        costUsd: (ms / 60000) * PER_MIN,
+        costEstimated: true,
+        params: { music_length_ms: ms, force_instrumental: true },
+      };
+    },
+  };
+}

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

@@ -0,0 +1,120 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Question } from "../ask.ts";
+import { duration as audioDuration } from "../audio.ts";
+import type { CapabilityProvider } from "../capabilities.ts";
+import { cacheDir, sha256 } from "../generate.ts";
+import { whereToPut } from "../keys.ts";
+import { elevenlabsMusic } from "./elevenlabs.ts";
+import { byMood, MOOD_PROMPT } from "./library.ts";
+import { lyriaMusic } from "./lyria.ts";
+import type { MusicProvider } from "./types.ts";
+
+export type { MusicProvider, MusicRaw, MusicRequest } from "./types.ts";
+export { addToLibrary, byMood, listLibrary, MOOD_PROMPT, MOOD_TAGS, musicDir, type Track } from "./library.ts";
+
+// 고르는 순서 — 이미 쓰는 Gemini 키 하나로 되는 Lyria 3.5 먼저(곡 하나 $0.08), 그다음 Eleven Music
+export function musicProviders(): MusicProvider[] {
+  return [lyriaMusic("lyria-3.5"), elevenlabsMusic(), lyriaMusic("lyria-3-clip-preview")];
+}
+
+export function pickMusic(id?: string): MusicProvider {
+  const all = musicProviders();
+  if (id) {
+    const p = all.find((x) => x.id === id);
+    if (!p) throw new Error(`음악 공급자 없음: ${id} (있는 것: ${all.map((x) => x.id).join(" ")})`);
+    return p;
+  }
+  const p = all.find((x) => x.ready());
+  if (!p) throw new Error("키가 있는 음악 공급자가 없다 — Gemini 키(Lyria) 또는 ElevenLabs 키");
+  return p;
+}
+
+// 길이를 몇 칸으로 묶는다 — 내레이션이 1–2초 달라도 같은 프롬프트·같은 캐시라 시리즈마다 같은 곡이 깔린다
+const BUCKETS = [30, 45, 60, 90, 120, 180, 240];
+export function musicLength(sec: number): number {
+  return BUCKETS.find((b) => b >= sec + 2) ?? Math.ceil((sec + 2) / 30) * 30;
+}
+
+export interface MusicAsset {
+  path: string;
+  provider: string;
+  model: string;
+  mood: string;
+  seconds: number;
+  prompt: string;
+  costUsd: number;
+  license: string;
+  notes: string[];
+  cached: boolean;
+}
+
+// 분위기·길이로 곡 하나 → outDir/<id>.mp3 + <id>.json. 같은 분위기·같은 길이 칸·같은 공급자면 캐시에서 0원(같은 곡)
+export async function genMusic(id: string, o: { mood: string; duration: number; prompt?: string }, ctx: { outDir: string; cacheDir?: string; log?: (l: string) => void }, providerId?: string): Promise<MusicAsset> {
+  const p = pickMusic(providerId);
+  if (!p.ready()) throw new Error(`${p.label} 를 못 쓴다 — ${whereToPut(p.keyName)}`);
+  const seconds = Math.min(p.maxSec, musicLength(o.duration));
+  const prompt = o.prompt ?? MOOD_PROMPT[o.mood] ?? MOOD_PROMPT.deep;
+  const key = sha256(JSON.stringify({ kind: "music", provider: p.id, model: p.model, prompt, seconds }));
+  const dir = cacheDir(ctx);
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(ctx.outDir, { recursive: true });
+  const metaPath = join(dir, `${key}.json`);
+  let meta: Omit<MusicAsset, "path" | "cached"> & { file: string };
+  let cached = existsSync(metaPath);
+  if (cached) meta = JSON.parse(readFileSync(metaPath, "utf8"));
+  if (!cached || !existsSync(join(dir, meta!.file))) {
+    cached = false;
+    ctx.log?.(`곡 ${id}: ${p.id} ${seconds}초 견적 $${p.estimateUsd(seconds).toFixed(3)} — 생성 중(수십 초)`);
+    const raw = await p.compose({ prompt, duration: seconds });
+    const file = `${key}.${raw.ext}`;
+    writeFileSync(join(dir, file), raw.bytes);
+    const got = await audioDuration(join(dir, file));
+    meta = { file, provider: p.id, model: raw.model, mood: o.mood, seconds: +got.toFixed(2), prompt, costUsd: raw.costUsd, license: p.license, notes: raw.notes ?? [] };
+    writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`);
+  }
+  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, ...rest, cached }, null, 2)}\n`);
+  return { ...rest, path, cached };
+}
+
+// 묻기 틀(ask.ts)에 얹는 곡 질문. 분위기 맞는 곡 모음 곡(0원) → 생성 → 없음. 곡 모음 곡이 있으면 그게 권장이고 돈 안 드는 길
+// ready 는 쓸 수 있는 생성 공급자 id(생성 능력 표에서) — 안 주면 키를 직접 본다
+export function musicQuestion(o: { mood: string; duration: number; ready?: string[] }): Question {
+  const lib = byMood(o.mood).slice(0, 2);
+  const gen = musicProviders().find((p) => (o.ready ? o.ready.includes(p.id) : p.ready()) && p.id !== "lyria-3-clip-preview");
+  const seconds = musicLength(o.duration);
+  const choices: Question["choices"] = lib.map((t) => ({ value: t.path, label: `곡 모음 「${t.title}」 — ${t.mood.join("·")}`, costUsd: 0, note: t.license }));
+  if (gen) choices.push({ value: `gen:${gen.id}`, label: `${gen.label} 로 「${o.mood}」 곡 ${seconds}초 생성`, costUsd: gen.estimateUsd(seconds), note: `${gen.license}${gen.verified ? "" : " · 실호출 미검증"}` });
+  choices.push({ value: "none", label: "음악 없이", costUsd: 0 });
+  const free = lib[0]?.path ?? "none";
+  return {
+    id: "music",
+    cap: "music",
+    ask: lib.length || gen ? `깔 음악은?(분위기 ${o.mood} — 직접 넣으려면 --music <파일>)` : `분위기 ${o.mood} 에 맞는 곡이 곡 모음에 없고 음악 생성 키도 없다 — 음악 없이 갈까?(직접 넣으려면 --music <파일>)`,
+    header: "음악",
+    choices: choices.slice(0, 4),
+    default: choices[0].value,
+    skip: free,
+    flag: "--music",
+    accepts: (v: string) => v === "none" || (v.startsWith("gen:") ? musicProviders().some((p) => p.id === v.slice(4) && p.ready()) : existsSync(v)),
+  };
+}
+
+// 생성 능력 표의 음악 칸(생성 공급자만 — 곡 모음 줄은 capabilities.ts 가 센다)
+export function musicGenCapabilities(): CapabilityProvider[] {
+  return musicProviders().map((p) => ({
+    cap: "music",
+    id: p.id,
+    label: `${p.label}(${p.model})`,
+    ready: p.ready(),
+    detail: p.ready() ? `키 있음(키만 봄)${p.verified ? "" : " · 실호출 미검증"}` : "키 없음",
+    fix: p.ready() ? undefined : whereToPut(p.keyName),
+    unitUsd: p.estimateUsd(60),
+    unit: "곡 하나(60초)",
+    license: p.license,
+  }));
+}

package/packages/gen/src/music/library.ts

@@ -0,0 +1,73 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// 곡 모음 — 파일 옆 tags.json 이 곡마다 분위기·원본·라이선스를 쥔다. 사람용 표는 README.md 에 같은 줄로
+export interface Track {
+  file: string;
+  path: string;
+  title: string;
+  mood: string[];
+  genre?: string;
+  bpm?: number;
+  source: string;
+  license: string;
+}
+
+const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
+
+export const musicDir = (): string => process.env.KF_MUSIC_DIR || fileURLToPath(new URL("../../../../music/", import.meta.url));
+
+// 손으로 쓴 tags.json 은 칸이 빠질 수 있다 — 빠진 칸은 목록에서 빈 값으로 채운다
+function readTags(dir: string): Record<string, Partial<Omit<Track, "file" | "path">>> {
+  const f = join(dir, "tags.json");
+  return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {};
+}
+
+// 태그 없는 곡도 목록에는 나온다(분위기는 빈 채) — 출처를 모르는 곡은 고르는 쪽이 뒤로 민다
+export function listLibrary(dir = musicDir()): Track[] {
+  if (!existsSync(dir)) return [];
+  const tags = readTags(dir);
+  return readdirSync(dir)
+    .filter((f) => AUDIO.test(f))
+    .sort()
+    .map((file) => ({ title: file, mood: [], source: "", license: "", ...tags[file], file, path: join(dir, file) }));
+}
+
+// 분위기가 맞는 곡 — 맞은 태그가 많은 순, 같으면 파일 이름 순(같은 요청이면 늘 같은 곡)
+export function byMood(mood: string, dir = musicDir()): Track[] {
+  const want = MOOD_TAGS[mood] ?? [mood];
+  const score = (t: Track) => t.mood.filter((m) => want.includes(m)).length;
+  return listLibrary(dir)
+    .filter((t) => score(t) > 0 && t.license)
+    .sort((a, b) => score(b) - score(a) || a.file.localeCompare(b.file));
+}
+
+// name 을 주면 그 이름으로 넣는다(생성 곡은 캐시 키 이름이라 사람이 읽을 이름으로)
+export function addToLibrary(src: string, info: Omit<Track, "file" | "path">, dir = musicDir(), name?: string): Track {
+  if (!info.source || !info.license) throw new Error("곡 모음에는 원본(--source)과 라이선스(--license)가 있는 곡만 넣는다");
+  mkdirSync(dir, { recursive: true });
+  const file = name ?? basename(src);
+  const path = join(dir, file);
+  if (src !== path) copyFileSync(src, path);
+  const tags = readTags(dir);
+  tags[file] = info;
+  writeFileSync(join(dir, "tags.json"), `${JSON.stringify(Object.fromEntries(Object.entries(tags).sort(([a], [b]) => a.localeCompare(b))), null, 2)}\n`);
+  return { file, path, ...info };
+}
+
+// 틀이 적는 분위기 이름 → 곡 태그. 같은 분위기면 곡 모음 고르기도 생성 프롬프트도 같은 결로 간다
+export const MOOD_TAGS: Record<string, string[]> = {
+  deep: ["deep", "ambient", "cinematic", "minimal", "piano", "calm", "dark"],
+  bright: ["upbeat", "bright", "pop", "kawaii", "future-bass"],
+  calm: ["calm", "lofi", "chill", "piano", "ambient"],
+  epic: ["epic", "cinematic", "orchestral", "trailer"],
+};
+
+// 생성 모델에 줄 분위기 글 — 요청 글을 섞지 않는다(같은 분위기·길이면 같은 프롬프트라 캐시가 같은 곡을 돌려준다)
+export const MOOD_PROMPT: Record<string, string> = {
+  deep: "Deep ambient, minimal cinematic underscore for a calm explanatory narration. Low warm analog pads, slow sparse felt piano notes, soft sub-bass drone, distant airy textures, very light soft percussion far in the background. Around 70 BPM, D minor, contemplative and spacious with long reverb tails. Leaves the mid range open for a spoken voice.",
+  bright: "Bright uplifting electronic pop underscore, plucky synths, light future-bass chords, steady soft kick. Around 110 BPM, major key, positive and clean, leaves room for a spoken voice.",
+  calm: "Calm lo-fi underscore, mellow electric piano, soft vinyl texture, gentle brushed drums. Around 80 BPM, relaxed and warm, leaves room for a spoken voice.",
+  epic: "Cinematic epic underscore, slow building strings and low brass, deep taiko hits only at peaks. Around 90 BPM, minor key, grand but restrained under a spoken voice.",
+};

package/packages/gen/src/music/lyria.ts

@@ -0,0 +1,52 @@
+import { findKey, readKey } from "../keys.ts";
+import { json } from "../video/http.ts";
+import type { MusicProvider } from "./types.ts";
+
+// Gemini API Interactions(2026-10, ai.google.dev/gemini-api/docs/music-generation). 길이 칸이 없다 —
+// Clip 은 늘 30초, 3.5 는 프롬프트의 길이·시각 구간([0:00 - 0:20])으로 끌고 받은 뒤 잘라 맞춘다
+const BASE = "https://generativelanguage.googleapis.com/v1beta";
+// 곡 하나 값(유료 등급만, 무료 등급 없음 — ai.google.dev/gemini-api/docs/pricing)
+const PRICE: Record<string, number> = { "lyria-3-clip-preview": 0.04, "lyria-3.5": 0.08 };
+
+export function lyriaMusic(model: "lyria-3.5" | "lyria-3-clip-preview"): MusicProvider {
+  const clip = model === "lyria-3-clip-preview";
+  return {
+    id: model,
+    label: clip ? "Lyria 3 Clip(30초)" : "Lyria 3.5",
+    model,
+    keyName: "gemini",
+    license: "Google 생성형 AI 약관 — 출력물 소유권 주장 없음, 상업 가능 · SynthID 소리 워터마크(안 들림)",
+    region: "Gemini API 유료 등급",
+    verified: false,
+    maxSec: clip ? 30 : 240,
+    ready: () => findKey("gemini") !== null,
+    estimateUsd: () => PRICE[model],
+
+    async compose(o) {
+      const sec = Math.ceil(o.duration);
+      const mmss = (s: number) => `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+      // 3.5 는 길이를 말로만 받는다 — 시작·한가운데·끝 구간을 시각으로 적어 길이와 흐름을 붙잡는다
+      const shape = clip
+        ? ""
+        : ` Total length exactly ${sec} seconds. [0:00 - ${mmss(Math.round(sec * 0.25))}] sparse intro. [${mmss(Math.round(sec * 0.25))} - ${mmss(Math.round(sec * 0.8))}] slow build, same calm tempo. [${mmss(Math.round(sec * 0.8))} - ${mmss(sec)}] gentle resolve and fade.`;
+      const body = { model, input: `${o.prompt}${shape} Instrumental only, no vocals.`, response_format: { type: "audio" } };
+      const r = await json(`${BASE}/interactions`, { method: "POST", headers: { "x-goog-api-key": readKey("gemini"), "Content-Type": "application/json" }, body: JSON.stringify(body) }, "Lyria");
+      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(`Lyria 응답에 소리가 없다: ${JSON.stringify(r).slice(0, 200)}`);
+      const bytes = Buffer.from(audio.data, "base64");
+      return {
+        bytes,
+        ext: bytes.subarray(0, 4).toString() === "RIFF" ? "wav" : "mp3",
+        model,
+        costUsd: PRICE[model],
+        costEstimated: true,
+        params: { seconds: sec },
+        notes: ["synthid"],
+      };
+    },
+  };
+}

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

@@ -0,0 +1,28 @@
+export interface MusicRequest {
+  prompt: string;
+  duration: number; // 초 — 이만큼은 넘게 받아 영상 길이에 잘라 맞춘다
+}
+
+export interface MusicRaw {
+  bytes: Uint8Array;
+  ext: "mp3" | "wav";
+  model: string;
+  costUsd: number;
+  costEstimated: boolean;
+  params: Record<string, unknown>;
+  notes?: string[];
+}
+
+export interface MusicProvider {
+  id: string; // --music gen:<id>
+  label: string;
+  model: string;
+  keyName: string;
+  license: string;
+  region: string;
+  verified: boolean;
+  maxSec: number;
+  ready(): boolean;
+  estimateUsd(sec: number): number;
+  compose(o: MusicRequest): Promise<MusicRaw>;
+}

package/packages/gen/src/registry.ts

@@ -1,6 +1,7 @@
+import { codexImage } from "./image/codex.ts";
 import { ogImage } from "./image/og.ts";
 import { hasKey } from "./keys.ts";
-import type { ImageProvider, VideoProvider, VideoRequest } from "./types.ts";
+import type { ImageProvider, ProviderInfo, VideoProvider, VideoRequest } from "./types.ts";
 import { FAL_MODELS, falVideo } from "./video/fal.ts";
 import { h3Video } from "./video/h3.ts";
 import { ltxVideo } from "./video/ltx.ts";
@@ -10,9 +11,11 @@ import { veoVideo } from "./video/veo.ts";
 export const DEFAULT_IMAGE = "og-gpt-image-2.5-sunburst";
 
 export function imageProviders(): ImageProvider[] {
-  return [ogImage("openai/gpt-image-2.5-sunburst"), ogImage("openai/gpt-image-2.5-flare"), ogImage("openai/gpt-image-2")];
+  return [ogImage("openai/gpt-image-2.5-sunburst"), ogImage("openai/gpt-image-2.5-flare"), ogImage("openai/gpt-image-2"), codexImage()];
 }
 
+export const providerReady = (p: ProviderInfo): boolean => (p.available ? p.available() : hasKey(p.keyName));
+
 export function videoProviders(): VideoProvider[] {
   return [
     h3Video(),
@@ -44,7 +47,7 @@ export function pickVideo(id: string | undefined, req: VideoRequest): VideoProvi
     return p;
   }
   const usable = all
-    .filter((p) => hasKey(p.keyName) && (!req.lastFrame || p.firstLast))
+    .filter((p) => providerReady(p) && (!req.lastFrame || p.firstLast))
     .sort((a, b) => a.estimateUsd(req) - b.estimateUsd(req));
   if (!usable.length) throw new Error("키가 있는 영상 공급자가 없다 — kf gen models 로 무엇이 필요한지 본다");
   return usable[0];

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

@@ -0,0 +1,64 @@
+import { hasKey, readKey } from "../keys.ts";
+import { download, json } from "../video/http.ts";
+import type { TtsProvider } from "./types.ts";
+
+// 키가 없어 실호출로 검증하지 못했다 — 모양은 Alibaba Model Studio qwen-tts-api 문서(2026-10) 그대로.
+// 싱가포르(국제)가 기본, 베이징 키면 KF_DASHSCOPE_BASE=https://dashscope.aliyuncs.com (두 지역 키는 서로 다르다)
+const BASE = process.env.KF_DASHSCOPE_BASE ?? "https://dashscope-intl.aliyuncs.com";
+const MODEL = process.env.KF_DASHSCOPE_TTS_MODEL ?? "qwen3-tts-flash";
+// 입력 글자 1만 자당 $0.1(instruct $0.115), 중국어 한 글자는 둘로 센다 — 한글도 둘로 잡아 넉넉히
+const PER_10K = /instruct/.test(MODEL) ? 0.115 : 0.1;
+const LANG: Record<string, string> = { ko: "Korean", en: "English", ja: "Japanese", zh: "Chinese", de: "German", fr: "French", es: "Spanish", it: "Italian", pt: "Portuguese", ru: "Russian" };
+// 한 번에 600자까지(문서) — 장면 한 줄은 이보다 짧다
+const MAX_CHARS = 600;
+
+// 48개 모두 한국어를 받는다(문서 목록). 차분한 내레이션에 맞는 것만 앞에
+const VOICES = [
+  { id: "Neil", label: "남 · 고른 뉴스 앵커" },
+  { id: "Elias", label: "여 · 학자풍 이야기꾼" },
+  { id: "Eldric Sage", label: "남 · 차분하고 지혜로운 노인" },
+  { id: "Serena", label: "여 · 부드럽고 조용한" },
+  { id: "Kai", label: "남 · 편안한" },
+  { id: "Sohee", label: "여 · 한국어 화자, 표정이 큰" },
+];
+
+export function dashscopeTts(): TtsProvider {
+  return {
+    id: "dashscope",
+    label: "Qwen TTS(DashScope)",
+    model: MODEL,
+    keyName: "dashscope",
+    license: "Alibaba Cloud Model Studio 약관 — 출력물 상업 가능",
+    region: "싱가포르 국제 지역(베이징은 키가 따로)",
+    timestamps: false,
+    verified: false,
+    voices: VOICES,
+    defaultVoice: "Neil",
+    ready: () => hasKey("dashscope"),
+    estimateUsd: (text) => ((text.length * 2) / 10000) * PER_10K,
+
+    async synth(o) {
+      if (o.text.length > MAX_CHARS) throw new Error(`Qwen TTS 는 한 번에 ${MAX_CHARS}자까지 — ${o.text.length}자`);
+      const input: Record<string, unknown> = { text: o.text, voice: o.voice, language_type: LANG[o.lang ?? ""] ?? "Auto" };
+      const body: Record<string, unknown> = { model: MODEL, input };
+      // 연기 지시는 instruct 모델만, 중국어·영어로만 받는다
+      if (o.style && /instruct/.test(MODEL)) input.instructions = o.style;
+      const r = await json(
+        `${BASE}/api/v1/services/aigc/multimodal-generation/generation`,
+        { method: "POST", headers: { Authorization: `Bearer ${readKey("dashscope")}`, "Content-Type": "application/json" }, body: JSON.stringify(body) },
+        "Qwen TTS",
+      );
+      const url = r.output?.audio?.url;
+      if (!url) throw new Error(`Qwen TTS 응답에 소리 주소가 없다: ${JSON.stringify(r).slice(0, 200)}`);
+      const chars = r.usage?.characters;
+      return {
+        bytes: await download(url),
+        ext: "wav",
+        model: MODEL,
+        costUsd: ((typeof chars === "number" ? chars : o.text.length * 2) / 10000) * PER_10K,
+        costEstimated: typeof chars !== "number",
+        params: { voice: o.voice, language_type: input.language_type },
+      };
+    },
+  };
+}

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 },
+      };
+    },
+  };
+}