kasaframe 0.1.1 → 0.1.3

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

@@ -16,6 +16,7 @@ export interface AssetMeta {
   elapsedMs: number;
   license: string;
   region: string;
+  restrict?: string; // 회사·바깥 결과물에 걸리는 제한(공급자의 restrict) — kf make --finish 가 결과 메타로 모은다
   cacheKey: string;
   createdAt: string;
   width?: number;
@@ -68,11 +69,14 @@ export interface ProviderInfo {
   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>;
 }

package/packages/gen/src/video/h3.ts

@@ -45,6 +45,10 @@ export function h3Body(o: { prompt: string; firstFrame?: string; lastFrame?: str
   };
 }
 
+// 공개 가중치 라이선스가 한국·미국·EU·영국을 제외 지역으로 두고 산출물에도 건다 — 사내 파드로 돌려도 같다(API 판은 전 세계 가능)
+export const H3_RESTRICT =
+  "MiniMax H3 공개 가중치는 한국 제외 지역 — 회사·바깥 결과물엔 쓰지 않는다(시험·사내 보기만). 밖에 낼 영상은 minimax-h3 API(전 세계 가능)나 다른 공급자로";
+
 export function h3Video(): VideoProvider {
   const { steps, shortEdge, flowShift, extra } = settings();
   return {
@@ -54,6 +58,7 @@ export function h3Video(): VideoProvider {
     model: "MiniMaxAI/MiniMax-H3",
     license: "공개 가중치 — 지역 제한 확인 필요(MiniMax H3 커뮤니티 라이선스는 한국·미국·EU·영국을 제외 지역으로 둔다)",
     region: "사내 GPU 파드 자체 호스팅 — 한국 사용은 MiniMax 라이선스 신청 여부 확인 필요",
+    restrict: H3_RESTRICT,
     keyName: "h3",
     durations: DURATIONS,
     firstLast: true,

package/packages/gen/src/video/http.ts

@@ -5,7 +5,7 @@ export async function json(url: string, init: RequestInit, who: string): Promise
   const text = await r.text();
   if (!r.ok) {
     const hint = r.status === 402 || r.status === 403 ? " (잔액·권한을 확인)" : "";
-    throw new Error(`${who} ${r.status}${hint}: ${text.slice(0, 300)}`);
+    throw Object.assign(new Error(`${who} ${r.status}${hint}: ${text.slice(0, 300)}`), { status: r.status });
   }
   return text ? JSON.parse(text) : {};
 }

package/packages/jizura/src/index.ts

@@ -1,5 +1,5 @@
-export { jizuraLayer, jizuraPlans, jizuraReady, jizuraCuts, loadJizura } from "./layer.ts";
-export type { DrawMode, JizuraPaint, LayerOptions, PlanSettings } from "./layer.ts";
+export { jizuraLayer, jizuraPlans, jizuraReady, jizuraCuts, loadJizura, lyricsMode } from "./layer.ts";
+export type { DrawMode, JizuraPaint, LayerOptions, LyricsMode, PlanSettings } from "./layer.ts";
 export { DENY, partPool } from "./deny.ts";
 export type { PartGroup, PoolOptions } from "./deny.ts";
 export { toLrc, parseLyrics, wordsOf } from "./lyrics.ts";