kasaframe 0.0.0-stage → 0.1.3

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/plan.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { genImage, genVideo, NeedsApproval, type GenContext } from "./generate.ts";
+import { seam } from "./seam.ts";
+
+// plan.json 의 gen — 장면 assets 의 "gen:img:<id>"·"gen:vid:<id>" 가 가리키는 만들 거리.
+export interface GenSpec {
+  id?: string;
+  kind: "img" | "vid";
+  scene?: string;
+  prompt: string;
+  size?: string; // img
+  transparent?: boolean;
+  quality?: string;
+  refs?: string[]; // 프로젝트 기준 경로
+  seam?: boolean; // vid: 이 id 가 kf.json 의 이음매 장면이다
+  dur?: number; // vid(이음매가 아닐 때)
+  first?: string;
+  last?: string;
+  provider?: string;
+}
+
+export interface GenReport {
+  id: string;
+  kind: "img" | "vid";
+  status: "made" | "cached" | "needs-approval" | "error";
+  path?: string;
+  costUsd?: number;
+  estimateUsd?: number;
+  provider?: string;
+  error?: string;
+}
+
+export function referencedIds(plan: any): { kind: "img" | "vid"; id: string }[] {
+  const out: { kind: "img" | "vid"; id: string }[] = [];
+  for (const s of plan.scenes ?? []) {
+    for (const a of s.assets ?? []) {
+      const m = /^gen:(img|vid):(.+)$/.exec(a);
+      if (m && !out.some((x) => x.id === m[2])) out.push({ kind: m[1] as "img" | "vid", id: m[2] });
+    }
+  }
+  return out;
+}
+
+// 정본은 id 를 품은 배열. id 를 키로 쓴 객체도 받는다.
+export function genSpecs(plan: any): Record<string, GenSpec> {
+  const g = plan.gen ?? {};
+  if (!Array.isArray(g)) return g;
+  const out: Record<string, GenSpec> = {};
+  for (const [i, spec] of g.entries()) {
+    if (typeof spec?.id !== "string") throw new Error(`plan.json gen[${i}] 에 id 가 없다`);
+    out[spec.id] = spec;
+  }
+  return out;
+}
+
+function aspectSize(aspect: string | undefined): string {
+  return aspect === "9:16" ? "1080x1920" : aspect === "1:1" ? "1080x1080" : "1920x1080";
+}
+
+export async function resolvePlan(project: string, ctx: Omit<GenContext, "outDir">): Promise<GenReport[]> {
+  const dir = resolve(project);
+  const plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const specs = genSpecs(plan);
+  const at = (p?: string) => (p ? (isAbsolute(p) ? p : join(dir, p)) : undefined);
+  const outDir = join(dir, "assets", "gen");
+  const full = { ...ctx, outDir };
+  const reports: GenReport[] = [];
+  const ids = referencedIds(plan);
+  for (const id of Object.keys(specs)) if (!ids.some((x) => x.id === id)) ids.push({ kind: specs[id].kind, id });
+  // 이음매는 앞뒤 장면을 찍어 만든다 — 그 장면들이 쓰는 그림·영상이 먼저 있어야 한다.
+  const rank = (id: string) => (specs[id]?.kind === "img" ? 0 : specs[id]?.seam ? 2 : 1);
+  ids.sort((a, b) => rank(a.id) - rank(b.id));
+
+  for (const { kind, id } of ids) {
+    const spec = specs[id];
+    if (!spec) {
+      reports.push({ id, kind, status: "error", error: `plan.json gen.${id} 이 없다 — prompt 를 적어야 만든다` });
+      continue;
+    }
+    try {
+      if (spec.kind === "img") {
+        const a = await genImage(
+          id,
+          { prompt: spec.prompt, size: spec.size ?? aspectSize(plan.aspect), transparent: spec.transparent, quality: spec.quality, refs: spec.refs?.map((r) => at(r)!) },
+          full,
+          spec.provider,
+        );
+        reports.push({ id, kind, status: a.cached ? "cached" : "made", path: a.path, costUsd: a.cached ? 0 : a.meta.costUsd, provider: a.meta.provider });
+      } else if (spec.seam) {
+        const a = await seam({ project: dir, scene: id, prompt: spec.prompt, provider: spec.provider, first: at(spec.first), last: at(spec.last) }, full);
+        reports.push({ id, kind, status: a.cached ? "cached" : "made", path: a.path, costUsd: a.cached ? 0 : a.meta.costUsd, provider: a.meta.provider });
+      } else {
+        const first = at(spec.first);
+        if (first && !existsSync(first)) throw new Error(`첫 프레임 없음: ${spec.first} — 그림을 먼저 만든다(gen 순서)`);
+        const req = { prompt: spec.prompt, duration: spec.dur ?? 5, aspect: plan.aspect ?? "16:9", firstFrame: first, lastFrame: at(spec.last) };
+        const a = await genVideo(id, req, full, spec.provider);
+        reports.push({ id, kind, status: a.cached ? "cached" : "made", path: a.path, costUsd: a.cached ? 0 : a.meta.costUsd, provider: a.meta.provider });
+      }
+    } catch (e) {
+      if (e instanceof NeedsApproval) reports.push({ id, kind, status: "needs-approval", estimateUsd: e.estimateUsd, provider: e.provider, error: e.message });
+      else reports.push({ id, kind, status: "error", error: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  return reports;
+}

package/packages/gen/src/registry.ts

@@ -0,0 +1,54 @@
+import { codexImage } from "./image/codex.ts";
+import { ogImage } from "./image/og.ts";
+import { hasKey } from "./keys.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";
+import { minimaxVideo } from "./video/minimax.ts";
+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"), codexImage()];
+}
+
+export const providerReady = (p: ProviderInfo): boolean => (p.available ? p.available() : hasKey(p.keyName));
+
+export function videoProviders(): VideoProvider[] {
+  return [
+    h3Video(),
+    ...FAL_MODELS.map((m) => falVideo(m.id)),
+    minimaxVideo(),
+    veoVideo("veo-3.1-lite-generate-preview"),
+    veoVideo("veo-3.1-fast-generate-preview"),
+    ltxVideo(),
+  ];
+}
+
+// id 는 앞뒤 접두 없이도 찾는다 — "wan-2.2-turbo" 와 "fal-wan-2.2-turbo" 가 같은 것.
+function find<T extends { id: string }>(list: T[], id: string): T | undefined {
+  return list.find((p) => p.id === id) ?? list.find((p) => p.id.endsWith(`-${id}`) || p.id.replace(/^[a-z]+-/, "") === id);
+}
+
+export function pickImage(id = DEFAULT_IMAGE): ImageProvider {
+  const p = find(imageProviders(), id);
+  if (!p) throw new Error(`그림 공급자 없음: ${id} (있는 것: ${imageProviders().map((x) => x.id).join(" ")})`);
+  return p;
+}
+
+// 이름을 안 주면 키가 있는 것 중 가장 싼 것. 끝 프레임이 필요하면 그걸 받는 것만.
+export function pickVideo(id: string | undefined, req: VideoRequest): VideoProvider {
+  const all = videoProviders();
+  if (id) {
+    const p = find(all, id);
+    if (!p) throw new Error(`영상 공급자 없음: ${id} (있는 것: ${all.map((x) => x.id).join(" ")})`);
+    return p;
+  }
+  const usable = all
+    .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/seam.ts

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { genVideo, type GenContext } from "./generate.ts";
+import { retime, run, snapEnds } from "./media.ts";
+import type { Asset } from "./types.ts";
+
+interface KfScene {
+  id: string;
+  from: number;
+  dur: number;
+  role?: string;
+}
+
+interface KfJson {
+  fps: number;
+  width: number;
+  height: number;
+  scenes: KfScene[];
+}
+
+export function aspectOf(w: number, h: number): string {
+  const r = w / h;
+  if (Math.abs(r - 16 / 9) < 0.05) return "16:9";
+  if (Math.abs(r - 9 / 16) < 0.05) return "9:16";
+  if (Math.abs(r - 1) < 0.05) return "1:1";
+  return r > 1 ? "16:9" : "9:16";
+}
+
+// 이음매 장면(role "seam")은 앞 장면의 마지막 프레임에서 시작해 뒤 장면의 첫 프레임에서 끝난다.
+// 프레임 번호로 다룬다 — 초를 소수로 넘기면 반올림에 따라 앞뒤 장면이 한 프레임씩 바뀐다.
+export function seamFrames(kf: KfJson, sceneId: string): { scene: KfScene; firstFrame?: number; lastFrame?: number } {
+  const i = kf.scenes.findIndex((s) => s.id === sceneId);
+  if (i < 0) throw new Error(`kf.json 에 장면 없음: ${sceneId}`);
+  const scene = kf.scenes[i];
+  const start = Math.round(scene.from * kf.fps);
+  return {
+    scene,
+    firstFrame: i > 0 ? Math.max(0, start - 1) : undefined,
+    lastFrame: i < kf.scenes.length - 1 ? Math.round((scene.from + scene.dur) * kf.fps) : undefined,
+  };
+}
+
+const KF = fileURLToPath(new URL("../../cli/src/kf.ts", import.meta.url));
+
+export async function still(project: string, frame: number, out: string): Promise<void> {
+  await run(process.execPath, [KF, "still", project, "--frame", String(frame), "--out", out]);
+  if (!existsSync(out)) throw new Error(`kf still 이 ${out} 을 안 만들었다`);
+}
+
+export interface SeamOptions {
+  project: string;
+  scene: string;
+  prompt: string;
+  provider?: string;
+  first?: string; // 주면 kf still 대신 이 그림
+  last?: string;
+  smooth?: boolean;
+  resolution?: string;
+  snapFrames?: number; // 양 끝을 진짜 앞뒤 프레임으로 녹이는 프레임 수. 기본 0.15초어치, 0 이면 끈다
+}
+
+// 받은 클립은 장면 길이·fps 에 맞춰 assets/gen/<장면>.mp4 로 둔다. 장면 파일은 media 어댑터로 seek 만 한다.
+export async function seam(o: SeamOptions, ctx: Omit<GenContext, "outDir"> & { outDir?: string }): Promise<Asset> {
+  const project = resolve(o.project);
+  const kf = JSON.parse(readFileSync(join(project, "kf.json"), "utf8")) as KfJson;
+  const { scene, firstFrame, lastFrame } = seamFrames(kf, o.scene);
+  const framesDir = join(project, "out", "seam");
+  mkdirSync(framesDir, { recursive: true });
+  let first = o.first;
+  let last = o.last;
+  if (!first && firstFrame !== undefined) {
+    first = join(framesDir, `${scene.id}-first.png`);
+    await still(project, firstFrame, first);
+  }
+  if (!last && lastFrame !== undefined) {
+    last = join(framesDir, `${scene.id}-last.png`);
+    await still(project, lastFrame, last);
+  }
+  const outDir = ctx.outDir ?? join(project, "assets", "gen");
+  const raw = await genVideo(
+    `${scene.id}.raw`,
+    { prompt: o.prompt, firstFrame: first, lastFrame: last, duration: scene.dur, aspect: aspectOf(kf.width, kf.height), resolution: o.resolution },
+    { ...ctx, outDir },
+    o.provider,
+  );
+  const fitted = join(outDir, `${scene.id}.mp4`);
+  await retime(raw.path, fitted, scene.dur, kf.fps, { smooth: o.smooth, size: { w: kf.width, h: kf.height } });
+  const snap = o.snapFrames ?? Math.round(kf.fps * 0.15);
+  if (snap > 0) await snapEnds(fitted, fitted, { first, last, frames: snap, fps: kf.fps, dur: scene.dur, w: kf.width, h: kf.height });
+  const meta = {
+    ...raw.meta,
+    id: scene.id,
+    file: `${scene.id}.mp4`,
+    width: kf.width,
+    height: kf.height,
+    duration: scene.dur,
+    fps: kf.fps,
+    notes: [...(raw.meta.notes ?? []), `retimed from ${raw.meta.file}`, ...(snap > 0 ? [`snap ${snap}f`] : []), ...(first ? [] : ["no-first-frame"]), ...(last ? [] : ["no-last-frame"])],
+  };
+  writeFileSync(join(outDir, `${scene.id}.json`), JSON.stringify(meta, null, 2) + "\n");
+  return { path: fitted, meta, cached: raw.cached };
+}

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