kasaframe 0.0.0-stage → 0.1.3

package/packages/check/src/types.ts

@@ -0,0 +1,80 @@
+import type { KfMotionEvent, MotionRules as CoreMotionRules, SafeArea } from "@kasaframe/core";
+
+export type Severity = "error" | "warn";
+
+export interface Finding {
+  rule: string;
+  severity: Severity;
+  from: number;
+  to: number;
+  message: string;
+  // 고치는 쪽(사람이든 모델이든)이 곧장 손댈 자리를 찾도록 원자료를 붙인다.
+  detail?: Record<string, unknown>;
+}
+
+export interface Report {
+  target: string;
+  kind: "page" | "video";
+  // 페이지만 — step 이면 「같은 프레임 두 번」을 못 본다
+  mode?: "seek" | "step";
+  ok: boolean;
+  meta: { fps: number; width: number; height: number; duration: number };
+  sampled: { frames: number; textFrames: number; thumbFps: number };
+  counts: { error: number; warn: number };
+  findings: Finding[];
+  skipped: string[];
+  elapsedSec: number;
+}
+
+export interface Box {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+export interface TextHit {
+  text: string;
+  // canvas 는 fillText·strokeText, DOM 은 text node
+  // caption — 엔진이 장면 위에 얹은 자막 판(data-kf-captions). 장면 글과 한 줄로 잇지 않는다
+  via: "canvas" | "dom" | "caption";
+  // 가사 층(data-kf-lyrics — JIZURA 같은 키네틱 가사) 안의 글. 띠로 흘리는 마퀴·배경 큰 글자처럼 일부러 화면 끝을 넘겨 그린다
+  lyrics?: boolean;
+  // fillText 에 문자열이 아닌 값(undefined·숫자·객체)이 들어왔을 때 그 typeof
+  argType?: string;
+  font: string;
+  sizePx: number;
+  alpha: number;
+  // 화면(뷰포트) 좌표. 화면에 붙지 않은 오프스크린 canvas 면 없다.
+  box?: Box;
+  where?: string;
+}
+
+export interface FrameText {
+  t: number;
+  hits: TextHit[];
+}
+
+export type MotionEvent = KfMotionEvent;
+
+export interface Marker {
+  t: number;
+  label: string;
+  kind: "scene" | "beat" | "drop" | "section";
+}
+
+export interface Beats {
+  duration?: number;
+  bpm?: number;
+  beats: number[];
+  downbeats?: number[];
+  bars?: number[];
+  phrases?: number[];
+  sections?: { t: number; kind: string; strength?: number }[];
+  drops?: number[];
+}
+
+// style.json 은 손으로 고치는 파일이라 빠진 칸이 있어도 검사는 돈다.
+export type MotionRules = Partial<CoreMotionRules>;
+
+export type { SafeArea };

package/packages/check/src/video.ts

@@ -0,0 +1,137 @@
+import { spawn, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { colorThumb, type Thumb } from "./image.ts";
+import type { FrameText, TextHit } from "./types.ts";
+
+export interface VideoInfo {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+}
+
+export function probeVideo(file: string): VideoInfo {
+  const out = execFileSync("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,r_frame_rate:format=duration", "-of", "json", file], {
+    encoding: "utf8",
+  });
+  const j = JSON.parse(out);
+  const s = j.streams?.[0];
+  if (!s) throw new Error(`영상 스트림이 없다: ${file}`);
+  const [n, d] = String(s.r_frame_rate).split("/").map(Number);
+  return { fps: d ? n / d : n, width: s.width, height: s.height, duration: Number(j.format.duration) };
+}
+
+const TW = 160;
+
+// 모든 프레임을 160×90 회색조로 받아 멈춤·빈 화면·컷을 잰다. 60초 60fps 면 52MB 남짓.
+export async function videoThumbs(file: string, info: VideoInfo, from = 0, to = info.duration): Promise<Thumb[]> {
+  // 페이지 검사의 썸네일처럼 화면비를 지킨다 — 160×90 으로 누르면 세로 영상의 안전 영역이 뒤집혀 layout.fill 이 늘 0% 였다
+  const TH = Math.max(2, Math.round((TW * info.height) / info.width));
+  // 색을 받아 섬광 검사의 빨강도 본다 — 밝기는 페이지 검사와 같은 식으로 여기서 만든다
+  const args = ["-v", "error", "-ss", String(from), "-t", String(to - from), "-i", file, "-vf", `scale=${TW}:${TH}:flags=area,format=rgb24`, "-f", "rawvideo", "-"];
+  const proc = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+  const size = TW * TH * 3;
+  const thumbs: Thumb[] = [];
+  let buf = Buffer.alloc(0);
+  let err = "";
+  proc.stderr.on("data", (d) => (err += d));
+  for await (const chunk of proc.stdout) {
+    buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+    while (buf.length >= size) {
+      const data = new Uint8Array(TW * TH * 4);
+      for (let i = 0, j = 0; i < size; i += 3, j += 4) {
+        data[j] = buf[i];
+        data[j + 1] = buf[i + 1];
+        data[j + 2] = buf[i + 2];
+      }
+      thumbs.push(colorThumb(from + thumbs.length / info.fps, { width: TW, height: TH, data }));
+      buf = buf.subarray(size);
+    }
+  }
+  const code = await new Promise<number>((r) => proc.on("close", r));
+  if (code !== 0) throw new Error(`ffmpeg 실패: ${err.slice(0, 300)}`);
+  return thumbs;
+}
+
+function ocrBinary(): string | null {
+  if (process.platform !== "darwin") return null;
+  const src = fileURLToPath(new URL("./ocr.swift", import.meta.url));
+  const hash = createHash("sha1").update(readFileSync(src)).digest("hex").slice(0, 10);
+  const dir = join(homedir(), ".cache", "kasaframe");
+  const bin = join(dir, `kf-ocr-${hash}`);
+  if (existsSync(bin)) return bin;
+  mkdirSync(dir, { recursive: true });
+  try {
+    const tmp = `${bin}.${process.pid}`;
+    execFileSync("swiftc", ["-O", src, "-o", tmp], { stdio: "ignore" });
+    renameSync(tmp, bin);
+    return bin;
+  } catch {
+    return null;
+  }
+}
+
+function runOcr(bin: string, dir: string): Promise<{ file: string; items: { s: string; c: number; x0: number; y0: number; x1: number; y1: number }[] }[]> {
+  return new Promise((resolve, reject) => {
+    const p = spawn(bin, [dir], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    p.stdout.on("data", (d) => (out += d));
+    p.on("close", (code) =>
+      code === 0
+        ? resolve(
+            out
+              .split("\n")
+              .filter(Boolean)
+              .map((l) => JSON.parse(l)),
+          )
+        : reject(new Error(`OCR 실패 (${code})`)),
+    );
+  });
+}
+
+// mp4 에는 글자 정보가 없다. macOS Vision 으로 읽어 페이지 검사와 같은 꼴(FrameText)로 돌려준다.
+// 다른 OS 거나 swiftc 가 없으면 null — 그때 글 검사는 건너뛰었다고 보고서에 적는다.
+export async function videoText(file: string, info: VideoInfo, o: { fps: number; from?: number; to?: number; workers?: number }): Promise<FrameText[] | null> {
+  const bin = ocrBinary();
+  if (!bin) return null;
+  const from = o.from ?? 0;
+  const to = o.to ?? info.duration;
+  const root = mkdtempSync(join(tmpdir(), "kf-check-"));
+  try {
+    execFileSync("ffmpeg", ["-v", "error", "-ss", String(from), "-t", String(to - from), "-i", file, "-vf", `fps=${o.fps}`, join(root, "%06d.png")]);
+    const files = readdirSync(root).filter((f) => f.endsWith(".png")).sort();
+    const workers = Math.max(1, Math.min(o.workers ?? 4, files.length));
+    const dirs = Array.from({ length: workers }, (_, i) => {
+      const d = join(root, `w${i}`);
+      mkdirSync(d);
+      return d;
+    });
+    files.forEach((f, i) => renameSync(join(root, f), join(dirs[i % workers], f)));
+    const parts = await Promise.all(dirs.map((d) => runOcr(bin, d)));
+    const frames: FrameText[] = [];
+    for (const r of parts.flat()) {
+      const idx = Number(r.file.replace(/\D/g, "")) - 1;
+      const t = from + idx / o.fps;
+      const hits: TextHit[] = r.items.map((it) => {
+        const h = (it.y1 - it.y0) * info.height;
+        return {
+          text: it.s,
+          via: "dom",
+          font: "ocr",
+          sizePx: h * 0.8,
+          alpha: 1,
+          box: { x0: it.x0 * info.width, y0: it.y0 * info.height, x1: it.x1 * info.width, y1: it.y1 * info.height },
+          where: `ocr ${Math.round(it.c * 100)}%`,
+        };
+      });
+      if (hits.length) frames.push({ t, hits });
+    }
+    return frames.sort((a, b) => a.t - b.t);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kasaframe/cli",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "kf": "./src/kf.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@kasaframe/adapters": "^0.0.0",
+    "@kasaframe/clock": "^0.0.0",
+    "esbuild": "^0.28.2",
+    "playwright": "^1.64.0",
+    "vite": "^8.3.3",
+    "@kasaframe/motion": "0.0.0",
+    "pngjs": "^7.0.0",
+    "@kasaframe/jizura": "^0.0.0",
+    "@kasaframe/director": "^0.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "gsap": "^3.15.0",
+    "lottie-web": "^5.13.0",
+    "three": "^0.186.1",
+    "@types/pngjs": "^6.0.5"
+  }
+}

package/packages/cli/src/blur.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PNG } from "pngjs";
+import type { PageInfo, Tab } from "./browser.ts";
+
+export interface BlurOpts {
+  /** 하위 프레임 수 — 2 이상이면 켠다 */
+  count: number;
+  /** 셔터 각도(도). 180 이면 프레임 간격의 절반 동안 열려 있다 */
+  shutter: number;
+}
+
+/** kf.json 의 render — 빠른 움직임이 많은 용도(쇼츠·홍보)는 틀이 모션 블러를 기본으로 켜 둔다 */
+export function projectBlur(dir: string): { motionBlur?: number; shutter?: number } | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")).render;
+  } catch {
+    return undefined;
+  }
+}
+
+/** 플래그가 프로젝트 기본(kf.json render)을 이긴다 — --motion-blur 0 이면 끈다 */
+export function blurOpts(opts: Record<string, string | boolean | undefined>, base?: { motionBlur?: number; shutter?: number }): BlurOpts | null {
+  const count = Math.round(Number(opts["motion-blur"] ?? base?.motionBlur ?? 0));
+  if (!(count > 1)) return null;
+  const shutter = Number(opts.shutter ?? base?.shutter ?? 180);
+  return { count, shutter: Number.isFinite(shutter) ? Math.min(360, Math.max(1, shutter)) : 180 };
+}
+
+// 하위 프레임은 그 프레임이 속한 장면 안에서만 — 셔터가 컷을 넘으면 두 장면이 겹쳐 찍힌다
+function sceneSpan(info: PageInfo, t: number): [number, number] {
+  const starts = info.markers.filter((m) => m.kind === "scene").map((m) => m.t).sort((a, b) => a - b);
+  let a = 0;
+  let b = info.meta.duration;
+  for (const s of starts) {
+    if (s <= t + 1e-9) a = s;
+    else {
+      b = s;
+      break;
+    }
+  }
+  return [a, b];
+}
+
+/** 프레임 시각 t 둘레(가운데 맞춤 셔터)의 하위 시각들 */
+export function subTimes(info: PageInfo, t: number, o: BlurOpts): number[] {
+  const [a, b] = sceneSpan(info, t);
+  const open = o.shutter / 360 / info.meta.fps;
+  const last = b - 1 / (info.meta.fps * 1000);
+  return Array.from({ length: o.count }, (_, i) => Math.min(last, Math.max(a, t + ((i + 0.5) / o.count - 0.5) * open)));
+}
+
+/**
+ * 한 프레임을 하위 프레임 count 장으로 찍어 평균한 RGBA. 빨리 움직이는 것만 번지고 서 있는 것은 그대로다.
+ * 하위 프레임 번호를 페이지에 넘겨, 3D 전환이 같은 평균으로 피사계 심도를 얻는다. 같은 t 면 같은 그림
+ */
+export async function captureBlurred(tab: Tab, info: PageInfo, t: number, o: BlurOpts): Promise<{ data: Buffer; width: number; height: number }> {
+  let acc: Uint32Array | null = null;
+  let width = 0;
+  let height = 0;
+  const times = subTimes(info, t, o);
+  for (const [index, ts] of times.entries()) {
+    await tab.seek(ts, { index, count: o.count });
+    const img = PNG.sync.read(await tab.capture());
+    width = img.width;
+    height = img.height;
+    acc ??= new Uint32Array(img.data.length);
+    for (let j = 0; j < img.data.length; j++) acc[j] += img.data[j];
+  }
+  const n = times.length;
+  const data = Buffer.alloc(acc!.length);
+  for (let j = 0; j < acc!.length; j++) data[j] = Math.round(acc![j] / n);
+  return { data, width, height };
+}
+
+export function rgbaToPng(img: { data: Buffer; width: number; height: number }): Buffer {
+  const png = new PNG({ width: img.width, height: img.height });
+  img.data.copy(png.data);
+  return PNG.sync.write(png, { deflateLevel: 1 });
+}

package/packages/cli/src/browser.ts

@@ -0,0 +1,203 @@
+// window.__kf 전역 타입은 adapters 의 페이지 계약에 있다. cli 만 따로 타입 검사해도 보이게 끌어온다.
+import type {} from "@kasaframe/adapters";
+import { chromium, type Browser, type BrowserContext, type CDPSession, type Page } from "playwright";
+import { clockScript, type ClockOptions } from "@kasaframe/clock";
+import { openProject, type OpenProject } from "./serve.ts";
+
+export interface PageMeta {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  music?: string;
+}
+
+export interface PageInfo {
+  meta: PageMeta;
+  mode: "seek" | "step";
+  markers: { t: number; label: string; kind: string }[];
+}
+
+// 같은 프레임을 두 번 찍어 같아야 하므로 GPU 래스터·LCD 글자 다듬기처럼 흔들리는 것을 끈다.
+// partial raster 는 바뀐 조각만 다시 그려, 앞서 몇 번 찍었느냐에 따라 안티에일리어싱 가장자리가 갈린다(탭 이음매가 어긋남).
+const ARGS = [
+  "--disable-partial-raster",
+  // 합성기 쓰레드가 opacity·transform 애니메이션을 따로 돌리면, 일시정지가 닿기 전 자기 진행값으로 한 번 그린다.
+  "--disable-threaded-animation",
+  "--font-render-hinting=none",
+  "--disable-lcd-text",
+  "--disable-skia-runtime-opts",
+  "--force-color-profile=srgb",
+  "--hide-scrollbars",
+  "--mute-audio",
+  "--autoplay-policy=no-user-gesture-required",
+  // HTML-in-Canvas — 3D 전환이 살아 있는 장면 DOM 을 시각마다 WebGL 텍스처로 올린다(texElementImage2D)
+  "--enable-features=CanvasDrawElement",
+  "--disable-background-timer-throttling",
+  "--disable-renderer-backgrounding",
+  "--disable-backgrounding-occluded-windows",
+];
+
+export async function launch(): Promise<Browser> {
+  try {
+    return await chromium.launch({ headless: true, args: ARGS });
+  } catch (err) {
+    if (!String(err).includes("Executable doesn't exist")) throw err;
+    return chromium.launch({ headless: true, channel: "chrome", args: ARGS });
+  }
+}
+
+export class Tab {
+  readonly page: Page;
+  private cdp: CDPSession;
+  info!: PageInfo;
+
+  private constructor(page: Page, cdp: CDPSession) {
+    this.page = page;
+    this.cdp = cdp;
+  }
+
+  static async open(context: BrowserContext, url: string): Promise<Tab> {
+    const page = await context.newPage();
+    const errors: string[] = [];
+    page.on("pageerror", (e) => errors.push(e.message));
+    page.on("console", (m) => {
+      if (m.type() === "error") errors.push(m.text());
+    });
+    const tab = new Tab(page, await context.newCDPSession(page));
+    await page.goto(url, { waitUntil: "load" });
+    try {
+      await page.waitForFunction(() => typeof window.__kf?.seek === "function", null, { timeout: 15000 });
+    } catch {
+      throw new Error(`페이지가 window.__kf 를 걸지 않았다 (${url})${errors.length ? `\n  페이지 오류: ${errors.join("\n  ")}` : ""}`);
+    }
+    await page.evaluate(() => window.__kf!.ready!());
+    tab.info = await page.evaluate(() => {
+      const k = window.__kf!;
+      return {
+        meta: { ...k.meta! },
+        mode: k.mode ?? "seek",
+        markers: (k.markers ?? []).map((m) => ({ t: m.t, label: m.label, kind: m.kind })),
+      };
+    });
+    const { width, height } = tab.info.meta;
+    const vp = page.viewportSize();
+    if (!vp || vp.width !== width || vp.height !== height) await page.setViewportSize({ width, height });
+    return tab;
+  }
+
+  async seek(t: number, sample?: { index: number; count: number }): Promise<void> {
+    await this.page.evaluate(([t, s]) => window.__kf!.seek!(t, s ?? undefined), [t, sample ?? null] as const);
+  }
+
+  // Playwright screenshot 보다 빠르다. optimizeForSpeed 는 PNG 압축만 줄이고 픽셀은 같다.
+  private async shot(): Promise<Buffer> {
+    const { data } = await this.cdp.send("Page.captureScreenshot", {
+      format: "png",
+      optimizeForSpeed: true,
+      captureBeyondViewport: false,
+    });
+    return Buffer.from(data, "base64");
+  }
+
+  // 이번 seek 에서 <video> 를 옮겼으면 합성기가 새 프레임을 받을 때까지 두 번 연속 같은 그림이 나오게 다시 찍는다.
+  async capture(): Promise<Buffer> {
+    let png = await this.shot();
+    const moved = await this.page.evaluate(() => {
+      const m = !!window.__kfMediaMoved;
+      window.__kfMediaMoved = false;
+      return m;
+    });
+    if (!moved) return png;
+    for (let i = 0; i < 8; i++) {
+      await this.page.evaluate(
+        () => new Promise<void>((r) => (window.__kfClock?.real.requestAnimationFrame ?? requestAnimationFrame)(() => r())),
+      );
+      const again = await this.shot();
+      if (again.equals(png)) return png;
+      png = again;
+    }
+    return png;
+  }
+
+  async close(): Promise<void> {
+    await this.page.close().catch(() => {});
+  }
+}
+
+export interface Session {
+  project: OpenProject;
+  browser: Browser;
+  context: BrowserContext;
+  first: Tab;
+  info: PageInfo;
+  tab(): Promise<Tab>;
+  close(): Promise<void>;
+}
+
+export interface SessionOptions {
+  clock?: boolean | ClockOptions;
+  width?: number;
+  height?: number;
+  // 페이지 주소 뒤에 붙일 질의 — captions=on 처럼 kf.json 을 그 판만 덮는 값
+  query?: string;
+}
+
+// 프로젝트를 띄우고 탭 하나를 준비한다. 렌더는 tab() 으로 더 연다.
+export async function openSession(dir: string, o: SessionOptions = {}): Promise<Session> {
+  const project = await openProject(dir);
+  const browser = await launch();
+  try {
+    const context = await browser.newContext({
+      viewport: { width: o.width ?? 1920, height: o.height ?? 1080 },
+      deviceScaleFactor: 1,
+    });
+    if (o.clock !== false) {
+      await context.addInitScript({ content: await clockScript(o.clock === true || !o.clock ? {} : o.clock) });
+    }
+    const url = o.query ? `${project.url}${project.url.includes("?") ? "&" : "?"}${o.query.replace(/^\?/, "")}` : project.url;
+    const first = await Tab.open(context, url);
+    return {
+      project,
+      browser,
+      context,
+      first,
+      info: first.info,
+      tab: () => Tab.open(context, url),
+      async close() {
+        await browser.close().catch(() => {});
+        await project.close();
+      },
+    };
+  } catch (err) {
+    await browser.close().catch(() => {});
+    await project.close();
+    throw err;
+  }
+}
+
+export interface OpenPage {
+  page: Page;
+  meta: PageMeta;
+  mode: "seek" | "step";
+  markers: PageInfo["markers"];
+  url: string;
+  seek(t: number): Promise<void>;
+  capture(): Promise<Buffer>;
+  close(): Promise<void>;
+}
+
+// 검사·생성처럼 엔진 밖에서 렌더와 같은 길로 페이지를 열 때.
+export async function openPage(dir: string, o: SessionOptions = {}): Promise<OpenPage> {
+  const s = await openSession(dir, o);
+  return {
+    page: s.first.page,
+    meta: s.info.meta,
+    mode: s.info.mode,
+    markers: s.info.markers,
+    url: s.project.url,
+    seek: (t) => s.first.seek(t),
+    capture: () => s.first.capture(),
+    close: () => s.close(),
+  };
+}

package/packages/cli/src/command.ts

@@ -0,0 +1,44 @@
+// 명령 파일 하나 = commands/<이름>.ts 의 default export.
+export interface Command {
+  summary: string;
+  usage?: string;
+  // 반환값이 종료 코드. 없으면 0.
+  run(argv: string[]): Promise<number | void>;
+}
+
+export interface Flags {
+  args: string[];
+  opts: Record<string, string | boolean | undefined>;
+}
+
+// --key value · --key=value · --flag(값 없으면 true). 짧은 옵션은 쓰지 않는다.
+export function parseFlags(argv: string[]): Flags {
+  const out: Flags = { args: [], opts: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      out.args.push(a);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    if (eq > 0) {
+      out.opts[a.slice(2, eq)] = a.slice(eq + 1);
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      out.opts[a.slice(2)] = next;
+      i++;
+    } else {
+      out.opts[a.slice(2)] = true;
+    }
+  }
+  return out;
+}
+
+export function num(v: string | boolean | undefined, fallback: number): number {
+  if (typeof v !== "string") return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n)) throw new Error(`숫자가 아니다: ${v}`);
+  return n;
+}

package/packages/cli/src/commands/app.ts

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type Command, parseFlags } from "../command.ts";
+import { installed } from "../serve.ts";
+
+const cmd: Command = {
+  summary: "작업실 — 요청 칸·실시간 미리보기·렌더·검사 보고를 브라우저 화면으로",
+  usage: `kf app [--port 5150] [--host 127.0.0.1] [--dir 일 폴더]
+  --host 0.0.0.0 이면 같은 망의 폰에서도 연다. 일 폴더 기본은 레포 out/app, 설치된 패키지는 ~/.kasaframe/app
+  곡 모음은 KF_MUSIC_DIR. 말로 시작한 kf make 도 작업실이 떠 있으면 스스로 붙는다(KF_APP_URL)`,
+  async run(argv) {
+    const { opts } = parseFlags(argv);
+    const set = (flag: string, env: string) => {
+      if (typeof opts[flag] === "string") process.env[env] = opts[flag] as string;
+    };
+    set("port", "KF_APP_PORT");
+    set("host", "KF_APP_HOST");
+    set("dir", "KF_APP_DIR");
+    if (installed) process.env.KF_APP_DIR ??= join(homedir(), ".kasaframe", "app");
+    await import("../../../../app/server/main.ts");
+    // 서버가 멈출 때까지 돌려 둔다 — 끝내기는 main.ts 의 SIGINT 처리가 맡는다
+    return new Promise<never>(() => {});
+  },
+};
+export default cmd;

package/packages/cli/src/commands/beats.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { type Command, parseFlags } from "../command.ts";
+import { python as pythonBin, requirements } from "../deps.ts";
+
+const script = fileURLToPath(new URL("../../../../tools/beats/beats.py", import.meta.url));
+
+const cmd: Command = {
+  summary: "곡을 재서 beats.json — 박·마디·프레이즈·구간·드롭·대역 에너지",
+  usage: `kf beats <곡> [--out beats.json] [--from 초] [--duration 초] [--hz 20] [--bpm 힌트]
+
+  --from·--duration  곡의 일부만 쓸 때. 모든 시각은 --from 을 0 으로 센다
+  --bpm              반박·두 배 박으로 잡힐 때만 박 추적 시작값으로 준다(시각을 곱해 만들지 않는다)
+  요약은 stderr 로 나온다. python3 + librosa 가 필요하다 — kf setup beats 가 ~/.cache/kasaframe/py/beats 에 깐다(KF_PYTHON 으로 바꿀 수 있다).`,
+  async run(argv) {
+    const { args } = parseFlags(argv);
+    if (args.length === 0) {
+      console.error("kf beats: 곡 경로가 필요하다. kf beats --help");
+      return 2;
+    }
+    if (!existsSync(args[0])) {
+      console.error(`kf beats: 곡이 없다: ${args[0]}`);
+      return 2;
+    }
+    const python = pythonBin();
+    const probe = spawnSync(python, ["-c", "import librosa"], { stdio: "ignore" });
+    if (probe.status !== 0) {
+      console.error(`kf beats: ${python} 에 librosa 가 없다 — kf setup beats (또는 ${python} -m pip install -r ${requirements})`);
+      return 1;
+    }
+    const r = spawnSync(python, [script, ...argv], { stdio: "inherit" });
+    return r.status ?? 1;
+  },
+};
+export default cmd;