clipwise 0.9.0 → 0.10.0

package/README.ko.md

@@ -25,6 +25,20 @@ npx clipwise@latest record .clipwise/scenarios/demo.yaml
 **Zero footprint**: Clipwise가 남기는 모든 것(시나리오, 픽스처, 인증 상태, 출력물)은
 `.clipwise/` 디렉토리 하나에 담깁니다. `rm -rf .clipwise` 한 줄로 모든 흔적이 사라집니다.
 
+### 처음 5분 가이드
+
+1. `npx clipwise@latest init` — 바로 쓸 수 있는 시나리오 2개와 함께 `.clipwise/` 생성
+2. `npx clipwise@latest record .clipwise/scenarios/keynote.yaml` — **수정 없이** 키노트
+   런치 영상이 렌더됩니다 (호스팅 데모 대시보드를 녹화)
+3. `.clipwise/output/keynote.mp4` 열기 — 이것이 기본으로 제공되는 퀄리티 기준입니다
+4. `keynote.yaml` 수정: `url:`과 셀렉터를 **내 앱**으로 교체, 캡션 문구 조정
+5. `brand.yaml` 수정: accent 컬러·폰트 프리셋·캐치프레이즈 — 영상 전체가 따라옵니다
+
+자연어가 편하시면 `npx clipwise install-skill` 후 Claude Code에서 `/clipwise`로
+요청하세요 — 키노트 레시피가 내장된 스킬이 YAML을 대신 작성합니다. 런치 영상이
+아니라 단순 화면 녹화가 필요하면 `scenarios/demo.yaml`과 아래
+[YAML 시나리오 형식](#yaml-시나리오-형식)에서 시작하세요.
+
 ## 요구사항
 
 - **Node.js** >= 18

package/README.md

@@ -25,6 +25,20 @@ npx clipwise@latest record .clipwise/scenarios/demo.yaml
 **Zero footprint**: everything Clipwise touches lives in one `.clipwise/` directory —
 scenarios, fixtures, auth state, output. Remove every trace with `rm -rf .clipwise`.
 
+### Your first 5 minutes
+
+1. `npx clipwise@latest init` — scaffolds `.clipwise/` with two ready scenarios
+2. `npx clipwise@latest record .clipwise/scenarios/keynote.yaml` — renders a full
+   keynote-style launch video **with zero edits** (it records the hosted demo dashboard)
+3. Open `.clipwise/output/keynote.mp4` — this is the quality bar you get out of the box
+4. Edit `keynote.yaml`: swap the `url:` and selectors for **your** app, tweak the captions
+5. Edit `brand.yaml`: your accent color, font preset, catchphrases — the whole video follows
+
+Prefer natural language? `npx clipwise install-skill`, then ask `/clipwise` in
+Claude Code — it writes these YAMLs for you (the skill ships with the full
+keynote recipe). For a plain screen recording instead of a launch video, start
+from `scenarios/demo.yaml` and the [YAML Scenario Format](#yaml-scenario-format) below.
+
 ## Requirements
 
 - **Node.js** >= 18

package/dist/cli/index.js

@@ -293,7 +293,9 @@ var init_types = __esm({
       /** Fade-in duration in milliseconds. */
       fadeIn: z.number().min(0).default(0),
       /** Fade-out duration in milliseconds. */
-      fadeOut: z.number().min(0).default(0)
+      fadeOut: z.number().min(0).default(0),
+      /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+      bpm: z.number().min(40).max(220).optional()
     });
     AuthConfigSchema = z.object({
       /** Path to a Playwright storageState JSON file (cookies + localStorage). */
@@ -324,6 +326,8 @@ var init_types = __esm({
     PrepareConfigSchema = z.object({
       /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
       hide: z.array(z.string().min(1)).default([]),
+      /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+      mask: z.array(z.string().min(1)).default([]),
       /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
       freezeTime: z.string().optional(),
       /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -357,7 +361,7 @@ var init_types = __esm({
       steps: z.array(StepSchema).min(1)
     });
     SceneFxSchema = z.object({
-      kind: z.enum(["circle", "arrow"]),
+      kind: z.enum(["circle", "arrow", "spotlight"]),
       /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
       selector: z.string().optional(),
       /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -387,8 +391,14 @@ var init_types = __esm({
         /** 크롭 높이 상한 (px, 원본 기준) — 와이드 스트립 연출용. */
         maxH: z.number().optional()
       }).optional(),
-      /** 푸시인 카메라 (스케일 from→to). */
-      push: z.object({ from: z.number().default(1), to: z.number().default(1) }).optional(),
+      /** 푸시인 카메라 (스케일 from→to).
+       *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+       *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
+      push: z.object({
+        from: z.number().default(1),
+        to: z.number().default(1),
+        origin: z.string().optional()
+      }).optional(),
       /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
       start: z.union([z.number(), z.object({ step: z.number().int().min(0), offset: z.number().default(0) })]).default(0),
       /** 푸티지 재생 배속. */
@@ -571,6 +581,12 @@ function buildHideCss(selectors) {
   visibility: hidden !important;
 }`;
 }
+function buildMaskCss(selectors) {
+  return `${selectors.join(",\n")} {
+  filter: blur(10px) !important;
+  border-radius: 4px;
+}`;
+}
 function buildCssInjectionScript(css) {
   return `(() => {
   const apply = () => {
@@ -648,6 +664,9 @@ async function applyPrepare(context, prepare) {
   if (prepare.hide.length > 0) {
     cssChunks.push(buildHideCss(prepare.hide));
   }
+  if (prepare.mask.length > 0) {
+    cssChunks.push(buildMaskCss(prepare.mask));
+  }
   if (prepare.inject?.css) {
     const cssFiles = Array.isArray(prepare.inject.css) ? prepare.inject.css : [prepare.inject.css];
     for (const file of cssFiles) {
@@ -4144,7 +4163,7 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
   await browser.close();
   return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -4168,7 +4187,7 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
   const props = {
     accent: brand.accent,
     font: brand.font,
-    dur: scene.duration / 1e3,
+    dur: durMs / 1e3,
     layout: scene.layout,
     num: scene.num ?? "",
     label: scene.label ?? "",
@@ -4187,13 +4206,19 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
     pushTo: scene.push?.to ?? 1
   };
   if (scene.code?.length) props.code = scene.code.join("||");
+  if (scene.push?.origin) {
+    const box = take.boxes.get(scene.push.origin);
+    if (!box) throw new Error(`vignette push.origin selector "${scene.push.origin}" not found in footage "${scene.footage}"`);
+    props.pushOx = Math.max(0, Math.min(100, (box.x + box.width / 2 - crop.x) / crop.w * 100)).toFixed(1);
+    props.pushOy = Math.max(0, Math.min(100, (box.y + box.height / 2 - crop.y) / crop.h * 100)).toFixed(1);
+  }
   if (brand.annotations && scene.fx.length > 0) {
     props.fx = scene.fx.map((fx) => {
       let coords = fx.coords;
       if (fx.selector) {
         const box = take.boxes.get(fx.selector);
         if (!box) throw new Error(`vignette fx selector "${fx.selector}" not found in footage "${scene.footage}"`);
-        coords = fx.kind === "circle" ? [box.x, box.y, box.width, box.height] : [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2];
+        coords = fx.kind === "arrow" ? [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2] : [box.x, box.y, box.width, box.height];
       }
       return `${fx.kind}@${coords.join(",")}@${fx.delay}`;
     }).join(";");
@@ -4210,6 +4235,7 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     if (scene.type !== "vignette") continue;
     const set = selectorsByFootage.get(scene.footage) ?? /* @__PURE__ */ new Set();
     if (scene.crop?.selector) set.add(scene.crop.selector);
+    if (scene.push?.origin) set.add(scene.push.origin);
     for (const fx of scene.fx) if (fx.selector) set.add(fx.selector);
     selectorsByFootage.set(scene.footage, set);
   }
@@ -4235,27 +4261,32 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   });
   await new Promise((r) => server.listen(0, r));
   const port = server.address().port;
-  const totalMs = timeline.reduce((s, sc) => s + sc.duration, 0);
+  const beatMs = scenario.audio?.bpm ? 6e4 / scenario.audio.bpm : 0;
+  const durations = timeline.map(
+    (sc) => beatMs ? Math.max(beatMs, Math.round(sc.duration / beatMs) * beatMs) : sc.duration
+  );
+  const totalMs = durations.reduce((s, d) => s + d, 0);
   let elapsedMs = 0;
   const segments = [];
   const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
   try {
     for (let i = 0; i < timeline.length; i++) {
       const scene = timeline[i];
+      const dur = durations[i];
       const label = scene.type === "motion" ? scene.template : `vignette(${scene.footage})`;
       onProgress?.({ scene: i + 1, total: timeline.length, label });
       const thread = brand.annotations ? {
         threadFrom: (elapsedMs / totalMs).toFixed(4),
-        threadTo: ((elapsedMs + scene.duration) / totalMs).toFixed(4)
+        threadTo: ((elapsedMs + dur) / totalMs).toFixed(4)
       } : {};
-      elapsedMs += scene.duration;
+      elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
         const url = resolveMotionTemplate(scene.template, scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { accent: brand.accent, font: brand.font, dur: scene.duration / 1e3, ...scene.props, ...thread },
-          scene.duration,
+          { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
+          dur,
           scenario
         );
       } else {
@@ -4263,8 +4294,8 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand), ...thread },
-          scene.duration,
+          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          dur,
           scenario
         );
       }
@@ -4278,8 +4309,21 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
   const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
   const outPath = join2(tmp, "timeline.mp4");
+  let audioInput = "";
+  let audioMap = "";
+  if (scenario.audio) {
+    const a = scenario.audio;
+    const audioPath = isAbsolute2(a.file) ? a.file : resolve2(scenarioDir, a.file);
+    const totalSec = totalMs / 1e3;
+    const af = [];
+    if (a.volume !== 1) af.push(`volume=${a.volume}`);
+    if (a.fadeIn > 0) af.push(`afade=t=in:d=${a.fadeIn / 1e3}`);
+    if (a.fadeOut > 0) af.push(`afade=t=out:st=${Math.max(0, totalSec - a.fadeOut / 1e3)}:d=${a.fadeOut / 1e3}`);
+    audioInput = `-i "${audioPath}" `;
+    audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k -shortest `;
+  }
   execSync(
-    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} -filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" ${audioMap}-c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
     { stdio: ["ignore", "ignore", "pipe"] }
   );
   const buffer = await readFile4(outPath);
@@ -4522,7 +4566,7 @@ import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
-).version("0.9.0");
+).version("0.10.0");
 program.command("record").description("Record a demo from a YAML scenario file").argument("<scenario>", "Path to YAML scenario file").option("-o, --output <dir>", "Output directory (default: scenario outputDir or .clipwise/output)").option(
   "-f, --format <format>",
   "Output format (gif|mp4|png-sequence)"
@@ -4793,6 +4837,97 @@ steps:
     actions:
       - action: click
         selector: "#my-button"
+`;
+  const keynoteTemplate = `# Keynote-style launch video \u2014 runs AS-IS against the hosted demo.
+# Try it first:  clipwise record .clipwise/scenarios/keynote.yaml
+# Then replace the url + selectors with your own app.
+
+name: "My Launch Video"
+viewport: { width: 1280, height: 800, deviceScaleFactor: 2 }   # 2 = retina quality
+
+effects:
+  cursor: { enabled: true, clickEffect: true, highlight: false, trail: false }
+
+output:
+  format: mp4
+  fps: 30
+  preset: balanced
+  filename: keynote
+
+scenes:
+  # footage take \u2014 recorded once; vignettes below quote it by step
+  - type: screen
+    id: demo
+    steps:
+      - name: "Open"
+        captureDelay: 120
+        holdDuration: 1400
+        actions:
+          - action: navigate
+            url: "https://kwakseongjae.github.io/clipwise/demo/"   # \u2190 your app URL
+            waitUntil: networkidle
+      - name: "Stats"
+        captureDelay: 50
+        holdDuration: 700
+        actions:
+          - { action: hover, selector: "#stat-users" }             # \u2190 your selectors
+      - name: "Search"
+        captureDelay: 50
+        holdDuration: 500
+        actions:
+          - { action: type, selector: "#search-input", text: "growth report", delay: 28 }
+      - name: "Switch tab"
+        captureDelay: 50
+        holdDuration: 1100
+        actions:
+          - { action: click, selector: "#tab-daily" }
+      - name: "Table"
+        captureDelay: 80
+        holdDuration: 1300
+        actions:
+          - action: scroll
+            y: 420
+            smooth: true
+
+  # \u2500\u2500 timeline \u2500\u2500
+  - type: motion
+    template: kinetic-type
+    duration: 2200
+    props: { lines: "Ship *demos*,||not edits.", size: 86 }
+
+  - type: vignette
+    footage: demo
+    duration: 4200
+    layout: hero
+    num: "01"
+    label: "Cinematic camera"
+    caption: "Recorded from a real app \u2014 *zero code changes*"
+    push: { from: 1.02, to: 1.1 }
+    start: { step: 0, offset: 0.15 }
+    fx:
+      - { kind: circle, selector: "#stat-users", delay: 2700 }
+
+  - type: vignette
+    footage: demo
+    duration: 4000
+    layout: crop
+    num: "02"
+    label: "Close-up"
+    caption: "Selector-measured crop \u2014 *no pixel guessing*"
+    crop: { selector: "#chart-area", pad: 14 }
+    push: { from: 1.04, to: 1 }
+    start: { step: 3 }
+    rate: 1.1
+
+  - type: motion
+    template: kinetic-type
+    duration: 1900
+    props: { lines: "Your code,||*untouched.*", size: 80, fx: marker }
+
+  - type: motion
+    template: kinetic-type
+    duration: 2600
+    props: { lines: "*My Product*", size: 90, sub: "npx clipwise@latest init" }
 `;
   const gitignore = `# Clipwise local artifacts \u2014 safe to ignore
 auth/
@@ -4834,23 +4969,27 @@ catchphrases:
   await mkdir2(join3(baseDir, "fixtures"), { recursive: true });
   await mkdir2(join3(baseDir, "auth"), { recursive: true });
   await writeFile3(join3(baseDir, "scenarios", "demo.yaml"), template, "utf-8");
+  await writeFile3(join3(baseDir, "scenarios", "keynote.yaml"), keynoteTemplate, "utf-8");
   await writeFile3(join3(baseDir, "brand.yaml"), brandTemplate, "utf-8");
   await writeFile3(join3(baseDir, ".gitignore"), gitignore, "utf-8");
   console.log(chalk.green("Created .clipwise/\n"));
   console.log("  .clipwise/");
-  console.log("    scenarios/demo.yaml   \u2014 your first scenario (edit the URL)");
-  console.log("    brand.yaml            \u2014 tone & manner + catchphrases (Brand Kit)");
-  console.log("    prepare/              \u2014 CSS/JS injected only while recording");
-  console.log("    fixtures/             \u2014 mocked API responses (JSON)");
-  console.log("    auth/                 \u2014 storageState files (gitignored)");
-  console.log("    .gitignore            \u2014 keeps auth/, output/, cache/ out of git");
-  console.log("\nNext steps:");
-  console.log(`  1. Edit ${chalk.bold(".clipwise/scenarios/demo.yaml")} \u2014 change the URL to your site`);
-  console.log(`  2. Run ${chalk.bold("clipwise record .clipwise/scenarios/demo.yaml")}`);
-  console.log(`  3. Find your output in ${chalk.bold(".clipwise/output/")}`);
+  console.log("    scenarios/keynote.yaml \u2014 keynote launch video (runs as-is!)");
+  console.log("    scenarios/demo.yaml    \u2014 simple screen recording (edit the URL)");
+  console.log("    brand.yaml             \u2014 tone & font presets + catchphrases");
+  console.log("    prepare/               \u2014 CSS/JS injected only while recording");
+  console.log("    fixtures/              \u2014 mocked API responses (JSON)");
+  console.log("    auth/                  \u2014 storageState files (gitignored)");
+  console.log(`
+${chalk.bold("Try it right now")} (no edits needed \u2014 records the hosted demo):`);
+  console.log(`  ${chalk.bold("clipwise record .clipwise/scenarios/keynote.yaml")}`);
+  console.log("\nThen make it yours:");
+  console.log(`  1. Edit ${chalk.bold("keynote.yaml")} \u2014 swap the url + selectors for your app`);
+  console.log(`  2. Edit ${chalk.bold("brand.yaml")} \u2014 your accent color & catchphrases`);
+  console.log(`  3. Or let AI write scenarios: ${chalk.bold("clipwise install-skill")} \u2192 ask ${chalk.bold("/clipwise")} in Claude Code`);
   console.log(`
-Remove every trace anytime: ${chalk.bold("rm -rf .clipwise")}`);
-  console.log(`Or try the built-in demo: ${chalk.bold("clipwise demo")}
+Output lands in ${chalk.bold(".clipwise/output/")} \xB7 remove every trace: ${chalk.bold("rm -rf .clipwise")}`);
+  console.log(`Docs: ${chalk.bold("https://kwakseongjae.github.io/clipwise/")}
 `);
 });
 program.command("demo").description("Record a demo video of the Clipwise showcase dashboard").option("-o, --output <dir>", "Output directory", ".clipwise/output").option(

package/dist/index.d.ts

@@ -1934,16 +1934,20 @@ declare const AudioConfigSchema: z.ZodObject<{
     fadeIn: z.ZodDefault<z.ZodNumber>;
     /** Fade-out duration in milliseconds. */
     fadeOut: z.ZodDefault<z.ZodNumber>;
+    /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+    bpm: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     file: string;
     volume: number;
     fadeIn: number;
     fadeOut: number;
+    bpm?: number | undefined;
 }, {
     file: string;
     volume?: number | undefined;
     fadeIn?: number | undefined;
     fadeOut?: number | undefined;
+    bpm?: number | undefined;
 }>;
 type AudioConfig = z.infer<typeof AudioConfigSchema>;
 /**
@@ -2045,6 +2049,8 @@ type MockRoute = z.infer<typeof MockRouteSchema>;
 declare const PrepareConfigSchema: z.ZodObject<{
     /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
     hide: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+    mask: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
     freezeTime: z.ZodOptional<z.ZodString>;
     /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -2096,6 +2102,7 @@ declare const PrepareConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     hide: string[];
+    mask: string[];
     mock: {
         status: number;
         url: string;
@@ -2115,6 +2122,7 @@ declare const PrepareConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     hide?: string[] | undefined;
+    mask?: string[] | undefined;
     freezeTime?: string | undefined;
     seedRandom?: number | undefined;
     storage?: {
@@ -3374,9 +3382,10 @@ declare const ScreenSceneSchema: z.ZodObject<{
         } | undefined;
     }[];
 }>;
-/** 선 드로잉 주석 — 좌표는 셀렉터 실측(권장) 또는 푸티지 원본 px. */
+/** 푸티지 주석 — circle/arrow(선 드로잉), spotlight(주변 디밍).
+ *  좌표는 셀렉터 실측(권장) 또는 푸티지 원본 px. */
 declare const SceneFxSchema: z.ZodObject<{
-    kind: z.ZodEnum<["circle", "arrow"]>;
+    kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
     /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
     selector: z.ZodOptional<z.ZodString>;
     /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -3385,11 +3394,11 @@ declare const SceneFxSchema: z.ZodObject<{
     delay: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     delay: number;
-    kind: "circle" | "arrow";
+    kind: "circle" | "arrow" | "spotlight";
     selector?: string | undefined;
     coords?: number[] | undefined;
 }, {
-    kind: "circle" | "arrow";
+    kind: "circle" | "arrow" | "spotlight";
     selector?: string | undefined;
     delay?: number | undefined;
     coords?: number[] | undefined;
@@ -3433,16 +3442,21 @@ declare const VignetteSceneSchema: z.ZodObject<{
         h?: number | undefined;
         maxH?: number | undefined;
     }>>;
-    /** 푸시인 카메라 (스케일 from→to). */
+    /** 푸시인 카메라 (스케일 from→to).
+     *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+     *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
     push: z.ZodOptional<z.ZodObject<{
         from: z.ZodDefault<z.ZodNumber>;
         to: z.ZodDefault<z.ZodNumber>;
+        origin: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         from: number;
         to: number;
+        origin?: string | undefined;
     }, {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     }>>;
     /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
     start: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
@@ -3458,7 +3472,7 @@ declare const VignetteSceneSchema: z.ZodObject<{
     /** 푸티지 재생 배속. */
     rate: z.ZodDefault<z.ZodNumber>;
     fx: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        kind: z.ZodEnum<["circle", "arrow"]>;
+        kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
         /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
         selector: z.ZodOptional<z.ZodString>;
         /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -3467,11 +3481,11 @@ declare const VignetteSceneSchema: z.ZodObject<{
         delay: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }, {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -3488,13 +3502,14 @@ declare const VignetteSceneSchema: z.ZodObject<{
     rate: number;
     fx: {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }[];
     push?: {
         from: number;
         to: number;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -3516,6 +3531,7 @@ declare const VignetteSceneSchema: z.ZodObject<{
     push?: {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -3537,7 +3553,7 @@ declare const VignetteSceneSchema: z.ZodObject<{
     } | undefined;
     rate?: number | undefined;
     fx?: {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -4817,16 +4833,21 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         h?: number | undefined;
         maxH?: number | undefined;
     }>>;
-    /** 푸시인 카메라 (스케일 from→to). */
+    /** 푸시인 카메라 (스케일 from→to).
+     *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+     *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
     push: z.ZodOptional<z.ZodObject<{
         from: z.ZodDefault<z.ZodNumber>;
         to: z.ZodDefault<z.ZodNumber>;
+        origin: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         from: number;
         to: number;
+        origin?: string | undefined;
     }, {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     }>>;
     /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
     start: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
@@ -4842,7 +4863,7 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     /** 푸티지 재생 배속. */
     rate: z.ZodDefault<z.ZodNumber>;
     fx: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        kind: z.ZodEnum<["circle", "arrow"]>;
+        kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
         /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
         selector: z.ZodOptional<z.ZodString>;
         /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -4851,11 +4872,11 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         delay: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }, {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -4872,13 +4893,14 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     rate: number;
     fx: {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }[];
     push?: {
         from: number;
         to: number;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -4900,6 +4922,7 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     push?: {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -4921,7 +4944,7 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     } | undefined;
     rate?: number | undefined;
     fx?: {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -5006,6 +5029,8 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     prepare: z.ZodOptional<z.ZodObject<{
         /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
         hide: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+        mask: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
         freezeTime: z.ZodOptional<z.ZodString>;
         /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -5057,6 +5082,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         }>>;
     }, "strip", z.ZodTypeAny, {
         hide: string[];
+        mask: string[];
         mock: {
             status: number;
             url: string;
@@ -5076,6 +5102,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
     }, {
         hide?: string[] | undefined;
+        mask?: string[] | undefined;
         freezeTime?: string | undefined;
         seedRandom?: number | undefined;
         storage?: {
@@ -5525,16 +5552,20 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         fadeIn: z.ZodDefault<z.ZodNumber>;
         /** Fade-out duration in milliseconds. */
         fadeOut: z.ZodDefault<z.ZodNumber>;
+        /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+        bpm: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         file: string;
         volume: number;
         fadeIn: number;
         fadeOut: number;
+        bpm?: number | undefined;
     }, {
         file: string;
         volume?: number | undefined;
         fadeIn?: number | undefined;
         fadeOut?: number | undefined;
+        bpm?: number | undefined;
     }>>;
     /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
     steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -7712,16 +7743,21 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             h?: number | undefined;
             maxH?: number | undefined;
         }>>;
-        /** 푸시인 카메라 (스케일 from→to). */
+        /** 푸시인 카메라 (스케일 from→to).
+         *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+         *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
         push: z.ZodOptional<z.ZodObject<{
             from: z.ZodDefault<z.ZodNumber>;
             to: z.ZodDefault<z.ZodNumber>;
+            origin: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             from: number;
             to: number;
+            origin?: string | undefined;
         }, {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         }>>;
         /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
         start: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
@@ -7737,7 +7773,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         /** 푸티지 재생 배속. */
         rate: z.ZodDefault<z.ZodNumber>;
         fx: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            kind: z.ZodEnum<["circle", "arrow"]>;
+            kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
             /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
             selector: z.ZodOptional<z.ZodString>;
             /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -7746,11 +7782,11 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             delay: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }, {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;
@@ -7767,13 +7803,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         rate: number;
         fx: {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }[];
         push?: {
             from: number;
             to: number;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -7795,6 +7832,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         push?: {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -7816,7 +7854,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
         rate?: number | undefined;
         fx?: {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;
@@ -8084,6 +8122,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide: string[];
+        mask: string[];
         mock: {
             status: number;
             url: string;
@@ -8107,6 +8146,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume: number;
         fadeIn: number;
         fadeOut: number;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -8282,13 +8322,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         rate: number;
         fx: {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }[];
         push?: {
             from: number;
             to: number;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -8555,6 +8596,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide?: string[] | undefined;
+        mask?: string[] | undefined;
         freezeTime?: string | undefined;
         seedRandom?: number | undefined;
         storage?: {
@@ -8589,6 +8631,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume?: number | undefined;
         fadeIn?: number | undefined;
         fadeOut?: number | undefined;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -8759,6 +8802,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         push?: {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -8780,7 +8824,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
         rate?: number | undefined;
         fx?: {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;
@@ -9048,6 +9092,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide: string[];
+        mask: string[];
         mock: {
             status: number;
             url: string;
@@ -9071,6 +9116,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume: number;
         fadeIn: number;
         fadeOut: number;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -9246,13 +9292,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         rate: number;
         fx: {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }[];
         push?: {
             from: number;
             to: number;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -9519,6 +9566,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide?: string[] | undefined;
+        mask?: string[] | undefined;
         freezeTime?: string | undefined;
         seedRandom?: number | undefined;
         storage?: {
@@ -9553,6 +9601,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume?: number | undefined;
         fadeIn?: number | undefined;
         fadeOut?: number | undefined;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -9723,6 +9772,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         push?: {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -9744,7 +9794,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
         rate?: number | undefined;
         fx?: {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;

package/dist/index.js

@@ -62,6 +62,12 @@ function buildHideCss(selectors) {
   visibility: hidden !important;
 }`;
 }
+function buildMaskCss(selectors) {
+  return `${selectors.join(",\n")} {
+  filter: blur(10px) !important;
+  border-radius: 4px;
+}`;
+}
 function buildCssInjectionScript(css) {
   return `(() => {
   const apply = () => {
@@ -139,6 +145,9 @@ async function applyPrepare(context, prepare) {
   if (prepare.hide.length > 0) {
     cssChunks.push(buildHideCss(prepare.hide));
   }
+  if (prepare.mask.length > 0) {
+    cssChunks.push(buildMaskCss(prepare.mask));
+  }
   if (prepare.inject?.css) {
     const cssFiles = Array.isArray(prepare.inject.css) ? prepare.inject.css : [prepare.inject.css];
     for (const file of cssFiles) {
@@ -3700,7 +3709,7 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
   await browser.close();
   return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -3724,7 +3733,7 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
   const props = {
     accent: brand.accent,
     font: brand.font,
-    dur: scene.duration / 1e3,
+    dur: durMs / 1e3,
     layout: scene.layout,
     num: scene.num ?? "",
     label: scene.label ?? "",
@@ -3743,13 +3752,19 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
     pushTo: scene.push?.to ?? 1
   };
   if (scene.code?.length) props.code = scene.code.join("||");
+  if (scene.push?.origin) {
+    const box = take.boxes.get(scene.push.origin);
+    if (!box) throw new Error(`vignette push.origin selector "${scene.push.origin}" not found in footage "${scene.footage}"`);
+    props.pushOx = Math.max(0, Math.min(100, (box.x + box.width / 2 - crop.x) / crop.w * 100)).toFixed(1);
+    props.pushOy = Math.max(0, Math.min(100, (box.y + box.height / 2 - crop.y) / crop.h * 100)).toFixed(1);
+  }
   if (brand.annotations && scene.fx.length > 0) {
     props.fx = scene.fx.map((fx) => {
       let coords = fx.coords;
       if (fx.selector) {
         const box = take.boxes.get(fx.selector);
         if (!box) throw new Error(`vignette fx selector "${fx.selector}" not found in footage "${scene.footage}"`);
-        coords = fx.kind === "circle" ? [box.x, box.y, box.width, box.height] : [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2];
+        coords = fx.kind === "arrow" ? [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2] : [box.x, box.y, box.width, box.height];
       }
       return `${fx.kind}@${coords.join(",")}@${fx.delay}`;
     }).join(";");
@@ -3766,6 +3781,7 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     if (scene.type !== "vignette") continue;
     const set = selectorsByFootage.get(scene.footage) ?? /* @__PURE__ */ new Set();
     if (scene.crop?.selector) set.add(scene.crop.selector);
+    if (scene.push?.origin) set.add(scene.push.origin);
     for (const fx of scene.fx) if (fx.selector) set.add(fx.selector);
     selectorsByFootage.set(scene.footage, set);
   }
@@ -3791,27 +3807,32 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   });
   await new Promise((r) => server.listen(0, r));
   const port = server.address().port;
-  const totalMs = timeline.reduce((s, sc) => s + sc.duration, 0);
+  const beatMs = scenario.audio?.bpm ? 6e4 / scenario.audio.bpm : 0;
+  const durations = timeline.map(
+    (sc) => beatMs ? Math.max(beatMs, Math.round(sc.duration / beatMs) * beatMs) : sc.duration
+  );
+  const totalMs = durations.reduce((s, d) => s + d, 0);
   let elapsedMs = 0;
   const segments = [];
   const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
   try {
     for (let i = 0; i < timeline.length; i++) {
       const scene = timeline[i];
+      const dur = durations[i];
       const label = scene.type === "motion" ? scene.template : `vignette(${scene.footage})`;
       onProgress?.({ scene: i + 1, total: timeline.length, label });
       const thread = brand.annotations ? {
         threadFrom: (elapsedMs / totalMs).toFixed(4),
-        threadTo: ((elapsedMs + scene.duration) / totalMs).toFixed(4)
+        threadTo: ((elapsedMs + dur) / totalMs).toFixed(4)
       } : {};
-      elapsedMs += scene.duration;
+      elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
         const url = resolveMotionTemplate(scene.template, scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { accent: brand.accent, font: brand.font, dur: scene.duration / 1e3, ...scene.props, ...thread },
-          scene.duration,
+          { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
+          dur,
           scenario
         );
       } else {
@@ -3819,8 +3840,8 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand), ...thread },
-          scene.duration,
+          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          dur,
           scenario
         );
       }
@@ -3834,8 +3855,21 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
   const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
   const outPath = join2(tmp, "timeline.mp4");
+  let audioInput = "";
+  let audioMap = "";
+  if (scenario.audio) {
+    const a = scenario.audio;
+    const audioPath = isAbsolute(a.file) ? a.file : resolve(scenarioDir, a.file);
+    const totalSec = totalMs / 1e3;
+    const af = [];
+    if (a.volume !== 1) af.push(`volume=${a.volume}`);
+    if (a.fadeIn > 0) af.push(`afade=t=in:d=${a.fadeIn / 1e3}`);
+    if (a.fadeOut > 0) af.push(`afade=t=out:st=${Math.max(0, totalSec - a.fadeOut / 1e3)}:d=${a.fadeOut / 1e3}`);
+    audioInput = `-i "${audioPath}" `;
+    audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k -shortest `;
+  }
   execSync(
-    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} -filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" ${audioMap}-c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
     { stdio: ["ignore", "ignore", "pipe"] }
   );
   const buffer = await readFile3(outPath);
@@ -4129,7 +4163,9 @@ var AudioConfigSchema = z.object({
   /** Fade-in duration in milliseconds. */
   fadeIn: z.number().min(0).default(0),
   /** Fade-out duration in milliseconds. */
-  fadeOut: z.number().min(0).default(0)
+  fadeOut: z.number().min(0).default(0),
+  /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+  bpm: z.number().min(40).max(220).optional()
 });
 var AuthConfigSchema = z.object({
   /** Path to a Playwright storageState JSON file (cookies + localStorage). */
@@ -4160,6 +4196,8 @@ var MockRouteSchema = z.object({
 var PrepareConfigSchema = z.object({
   /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
   hide: z.array(z.string().min(1)).default([]),
+  /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+  mask: z.array(z.string().min(1)).default([]),
   /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
   freezeTime: z.string().optional(),
   /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -4193,7 +4231,7 @@ var ScreenSceneSchema = z.object({
   steps: z.array(StepSchema).min(1)
 });
 var SceneFxSchema = z.object({
-  kind: z.enum(["circle", "arrow"]),
+  kind: z.enum(["circle", "arrow", "spotlight"]),
   /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
   selector: z.string().optional(),
   /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -4223,8 +4261,14 @@ var VignetteSceneSchema = z.object({
     /** 크롭 높이 상한 (px, 원본 기준) — 와이드 스트립 연출용. */
     maxH: z.number().optional()
   }).optional(),
-  /** 푸시인 카메라 (스케일 from→to). */
-  push: z.object({ from: z.number().default(1), to: z.number().default(1) }).optional(),
+  /** 푸시인 카메라 (스케일 from→to).
+   *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+   *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
+  push: z.object({
+    from: z.number().default(1),
+    to: z.number().default(1),
+    origin: z.string().optional()
+  }).optional(),
   /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
   start: z.union([z.number(), z.object({ step: z.number().int().min(0), offset: z.number().default(0) })]).default(0),
   /** 푸티지 재생 배속. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clipwise",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Scriptable cinematic screen recorder for product demos — YAML in, polished MP4 out",
   "type": "module",
   "main": "dist/index.js",

package/skills/clipwise.md

@@ -375,12 +375,14 @@ scenes:
     label: "Smart Speed"
     caption: "Loading compressed, *results crisp*"
     crop: { selector: ".panel", pad: 14, maxH: 250 }   # selector-measured, never guess pixels
-    push: { from: 1.05, to: 1 }        # push-in/out camera
+    push: { from: 1.05, to: 1, origin: ".panel" }  # origin: match-cut — push toward
+                                       # a selector so the NEXT scene's crop continues the move
     start: { step: 3, offset: 0 }      # quote footage from a step boundary (or seconds)
     rate: 1.15                         # playback speed of the quoted footage
-    fx:                                # line-draw annotations on the footage
-      - { kind: circle, selector: "#revenue", delay: 2500 }
-      - { kind: arrow, selector: ".panel", delay: 2900 }
+    fx:                                # annotations on the footage
+      - { kind: circle, selector: "#revenue", delay: 2500 }    # hand-drawn circle
+      - { kind: arrow, selector: ".panel", delay: 2900 }       # drawn arrow
+      - { kind: spotlight, selector: "#revenue", delay: 2400 } # dim everything else
     # code: ["prepare:", "  hide: [...]"]   # split layout left code card
 ```
 
@@ -395,6 +397,10 @@ scenes:
 5. **Footage effects**: in scenes mode set only `cursor:` (highlight: false) — zoom/frame/background
    are handled by the vignette compositor, not the recorder
 6. Keep one screen take (~12-15s) and let vignettes quote segments via `start: { step: N }`
+7. **Sensitive data**: `prepare.mask: [".email", ".amount"]` blurs elements at record time
+   (follows scrolling — never ask the user to fake their data)
+8. **Music**: `audio: { file: bgm.mp3, bpm: 122, fadeOut: 1500 }` muxes BGM into the final
+   video AND snaps every scene cut onto the beat grid (beat-synced cuts)
 
 ## Critical Rules
 

package/templates/motion/vignette.html

@@ -113,6 +113,15 @@
   /* ── 선 드로잉 주석 레이어 (fx=circle@…;arrow@…) — 카드 위에 그려짐 ── */
   .annotations { position: absolute; inset: 0; z-index: 5; pointer-events: none;
     overflow: visible; }
+  /* 스포트라이트 — 대상만 남기고 주변을 디밍 (fx kind: spotlight) */
+  .spotlight { position: absolute; z-index: 4; pointer-events: none;
+    /* spread가 너무 크면 Chromium이 그림자를 클램프하므로 카드 크기 수준으로 */
+    box-shadow: 0 0 0 1400px rgba(12, 12, 16, 0.52); border-radius: 10px;
+    /* 다크 UI에서도 컷아웃이 인지되도록 은은한 악센트 림 */
+    outline: 1.5px solid color-mix(in srgb, var(--accent) 55%, transparent);
+    outline-offset: 3px;
+    opacity: 0; animation: spot-in 550ms cubic-bezier(0.4, 0, 0.2, 1) both; }
+  @keyframes spot-in { to { opacity: 1; } }
   .annotations .stroke { stroke: var(--accent); fill: none; stroke-width: 3.5;
     stroke-linecap: round; stroke-linejoin: round;
     stroke-dasharray: 1; stroke-dashoffset: 1;
@@ -178,9 +187,12 @@
     card.style.setProperty("--push-from", P.get("pushFrom") || "1");
     card.style.setProperty("--push-to", P.get("pushTo") || "1");
     const fullCrop = cw >= SRC_W;
+    // push origin — 매치컷: 다음 신의 크롭 중심을 향해 밀어 들어가도록 중심점 지정
+    const pushOx = num("pushOx", 50), pushOy = num("pushOy", 42);
     card.innerHTML = `
       ${fullCrop ? '<div class="titlebar"><i></i><i></i><i></i></div>' : ""}
-      <div class="viewport"><div class="pusher" style="animation-duration:${num("dur", 4)}s">
+      <div class="viewport"><div class="pusher"
+        style="animation-duration:${num("dur", 4)}s; transform-origin:${pushOx}% ${pushOy}%">
         <img class="footage" id="footage"
              style="width:${SRC_W * scale}px;height:${SRC_H * scale}px;left:${-cx * scale}px;top:${-cy * scale}px" />
       </div></div>`;
@@ -224,6 +236,15 @@
       for (const spec of fxSpecs) {
         const [kind, coords, delay = "0"] = spec.split("@");
         const n = coords.split(",").map(Number);
+        if (kind === "spotlight") {
+          // 푸시 레이어 안에 디밍 컷아웃 — 푸티지에 앵커링되어 카메라를 따라간다
+          const [sx, sy] = toCard(n[0], n[1]);
+          const spot = document.createElement("div");
+          spot.className = "spotlight";
+          spot.style.cssText = `left:${sx - 6}px;top:${sy - 6}px;width:${n[2] * effScale + 12}px;height:${n[3] * effScale + 12}px;animation-delay:${delay}ms`;
+          card.querySelector(".pusher").appendChild(spot);
+          continue;
+        }
         if (kind === "circle") {
           // 손그림 느낌: 살짝 큰 타원 + 미세 회전
           const [x0, y0] = toCard(n[0], n[1]);