clipwise 0.10.1 → 0.11.1

package/README.ko.md

@@ -294,6 +294,7 @@ prepare:
 | 시드 데이터를 가진 "데모 모드" 구현 | `mock:` |
 | 일관된 데모를 위한 날짜/랜덤 스텁 | `freezeTime:` + `seedRandom:` |
 | 녹화용 온보딩 사전 완료 분기 | `storage:` |
+| 민감 정보(이메일·금액) 블러 | `mask:` — 요소 단위, 스크롤 추적 |
 
 `freezeTime` + `seedRandom`을 함께 쓰면 녹화가 **결정론적**이 됩니다 —
 같은 시나리오는 몇 번을 돌려도 바이트 단위로 동일한 프레임을 만듭니다.
@@ -327,11 +328,22 @@ scenes:
     push: { from: 1.05, to: 1 }
     start: { step: 3 }                             # step 경계에서 인용 시작
     rate: 1.15
-    fx: [{ kind: circle, selector: "#revenue", delay: 2500 }]
+    fx:
+      - { kind: circle, selector: "#revenue", delay: 2500 }     # 손그림 동그라미
+      - { kind: spotlight, selector: "#revenue", delay: 2500 }  # 주변 디밍
+    # push: { from: 1.0, to: 1.2, origin: ".panel" }            # 셀렉터를 향한 매치컷
+
+# 선택 — 무료 BGM을 URL로 (사용자 머신에서 다운로드) + 비트 싱크 컷
+audio: { file: "https://assets.mixkit.co/music/132/132.mp3", bpm: 120, volume: 0.32, fadeOut: 2000 }
+
+# 선택 — 캡션 필 (타임라인 절대 초), 모든 비율에 번인
+captions:
+  - { text: "실제 앱을 그대로 녹화했습니다", start: 0.4, end: 2.4 }
 ```
 
 **고퀄리티 레시피** (쇼케이스 영상이 이렇게 나오는 이유):
 1. `viewport.deviceScaleFactor: 2` — 레티나 해상도 캡처 (푸티지·타이포 전부)
+0. `output.aspects: ["9:16", "1:1"]` — 같은 실행에서 릴스/피드 파일까지 (푸티지는 1회 녹화)
 2. `prepare:` — 배너 숨김, 시간 동결, 랜덤 시드, API 목킹
 3. `.clipwise/brand.yaml` — 톤 프리셋, accent, 폰트 프리셋(`editorial` = Inter + Fraunces),
    캐치프레이즈. 선 드로잉 주석 + 연결 스레드는 자동 적용

package/README.md

@@ -296,6 +296,7 @@ prepare:
 | Build a "demo mode" with seeded data | `mock:` |
 | Stub dates and randomness for consistent demos | `freezeTime:` + `seedRandom:` |
 | Pre-complete onboarding for recordings | `storage:` |
+| Blur sensitive data (emails, amounts) | `mask:` — element-level, follows scrolling |
 
 Combined with `freezeTime` + `seedRandom`, recordings become **deterministic** —
 the same scenario produces byte-identical frames run after run.
@@ -330,11 +331,22 @@ scenes:
     push: { from: 1.05, to: 1 }
     start: { step: 3 }                             # quote from a step boundary
     rate: 1.15
-    fx: [{ kind: circle, selector: "#revenue", delay: 2500 }]
+    fx:
+      - { kind: circle, selector: "#revenue", delay: 2500 }     # hand-drawn circle
+      - { kind: spotlight, selector: "#revenue", delay: 2500 }  # dim everything else
+    # push: { from: 1.0, to: 1.2, origin: ".panel" }            # match-cut toward a selector
+
+# Optional — free BGM by URL (downloaded on your machine) + beat-synced cuts
+audio: { file: "https://assets.mixkit.co/music/132/132.mp3", bpm: 120, volume: 0.32, fadeOut: 2000 }
+
+# Optional — caption pills (timeline-absolute seconds), burned into every aspect
+captions:
+  - { text: "Recorded from a real app", start: 0.4, end: 2.4 }
 ```
 
 **Quality recipe** (what makes the showcase videos look the way they do):
 1. `viewport.deviceScaleFactor: 2` — retina-resolution capture (footage, type, everything)
+0. `output.aspects: ["9:16", "1:1"]` — reels/feed files from the same run (footage recorded once)
 2. `prepare:` — hide banners, freeze time, seed randomness, mock APIs
 3. `.clipwise/brand.yaml` — tone preset, accent, font preset (`editorial` = Inter + Fraunces), catchphrases; line annotations + the connecting thread switch on automatically
 4. Structure: kinetic hook → hero push-in → close-up vignettes → interstitial → split (YAML × footage) → outro

package/dist/cli/index.js

@@ -11,7 +11,7 @@ var __export = (target, all) => {
 
 // src/script/types.ts
 import { z } from "zod";
-var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, SmartWaitActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, SmartSpeedConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, AuthConfigSchema, MockRouteSchema, PrepareConfigSchema, MotionSceneSchema, ScreenSceneSchema, SceneFxSchema, VignetteSceneSchema, SceneSchema, ScenarioSchema;
+var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, SmartWaitActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, SmartSpeedConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, AuthConfigSchema, MockRouteSchema, PrepareConfigSchema, MotionSceneSchema, ScreenSceneSchema, SceneFxSchema, VignetteSceneSchema, SceneSchema, CaptionSchema, ScenarioSchema;
 var init_types = __esm({
   "src/script/types.ts"() {
     "use strict";
@@ -257,7 +257,10 @@ var init_types = __esm({
       codec: z.enum(["auto", "h264", "hevc", "av1"]).default("auto"),
       // Zero-Footprint 계약 (v0.8): 모든 산출물은 .clipwise/ 아래로.
       outputDir: z.string().default(".clipwise/output"),
-      filename: z.string().default("clipwise-recording")
+      filename: z.string().default("clipwise-recording"),
+      /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+       *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+      aspects: z.array(z.enum(["16:9", "9:16", "1:1"])).default([])
     });
     StepEffectsOverrideSchema = z.object({
       zoom: ZoomEffectSchema.partial().optional(),
@@ -410,6 +413,11 @@ var init_types = __esm({
       ScreenSceneSchema,
       VignetteSceneSchema
     ]);
+    CaptionSchema = z.object({
+      text: z.string().min(1),
+      start: z.number().min(0),
+      end: z.number().min(0)
+    });
     ScenarioSchema = z.object({
       name: z.string(),
       description: z.string().optional(),
@@ -430,7 +438,9 @@ var init_types = __esm({
       /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
       steps: z.array(StepSchema).default([]),
       /** Scene System (v0.9 preview) — motion/screen/vignette 타임라인. */
-      scenes: z.array(SceneSchema).optional()
+      scenes: z.array(SceneSchema).optional(),
+      /** scenes 전용 — 선언형 캡션 트랙 (스타일은 brand accent를 따른다). */
+      captions: z.array(CaptionSchema).default([])
     }).superRefine((s, ctx) => {
       if (s.steps.length === 0 && !s.scenes?.length) {
         ctx.addIssue({
@@ -4085,12 +4095,12 @@ async function executeStepsForProbe(page, scene) {
     }
   }
 }
-function segmentOutput(scenario) {
+function segmentOutput(scenario, stageW, stageH) {
   const dpr = scenario.viewport.deviceScaleFactor ?? 1;
   return {
     ...scenario.output,
-    width: scenario.output.width * dpr,
-    height: scenario.output.height * dpr,
+    width: stageW * dpr,
+    height: stageH * dpr,
     preset: "archive"
   };
 }
@@ -4119,7 +4129,11 @@ async function recordFootageTake(scenario, scene, selectors) {
   };
   const recorder = new ClipwiseRecorder();
   const session = await recorder.record(takeScenario);
-  const renderer = new CanvasRenderer(takeScenario.effects, segmentOutput(scenario), scene.steps);
+  const renderer = new CanvasRenderer(
+    takeScenario.effects,
+    segmentOutput(scenario, scenario.viewport.width, scenario.viewport.height),
+    scene.steps
+  );
   const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
   let count = 0;
   for await (const f of renderer.composeStream(session.frames)) {
@@ -4139,12 +4153,12 @@ async function recordFootageTake(scenario, scene, selectors) {
 function fitCardW(cw, ch, maxW = 940, maxH = 540) {
   return Math.round(Math.min(maxW, maxH * cw / ch));
 }
-async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
+async function captureMotionSegment(templateUrl, props, durationMs, scenario, stageW, stageH) {
   const fps = scenario.output.fps;
   const totalFrames = Math.round(durationMs / 1e3 * fps);
   const browser = await chromium2.launch();
   const page = await browser.newPage({
-    viewport: { width: scenario.output.width, height: scenario.output.height },
+    viewport: { width: stageW, height: stageH },
     deviceScaleFactor: scenario.viewport.deviceScaleFactor ?? 1
   });
   const params = new URLSearchParams(
@@ -4162,9 +4176,12 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
     frames.push({ index: i, buffer: await page.screenshot({ type: "png" }), timestamp: t });
   }
   await browser.close();
-  return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
+  return {
+    buffer: await encodeMp4(frames, segmentOutput(scenario, stageW, stageH)),
+    seconds: totalFrames / fps
+  };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs, stageW, stageH) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -4202,7 +4219,8 @@ function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
     cropY: crop.y,
     cropW: crop.w,
     cropH: crop.h,
-    cardW: fitCardW(crop.w, crop.h),
+    // 카드 크기 상한은 무대(stage) 크기 비례 — 어떤 출력 비율에서도 일관된 여백
+    cardW: fitCardW(crop.w, crop.h, Math.round(stageW * 0.735), Math.round(stageH * 0.675)),
     pushFrom: scene.push?.from ?? 1,
     pushTo: scene.push?.to ?? 1
   };
@@ -4272,19 +4290,37 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     (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 totalSec = totalMs / 1e3;
+  let audioPath = null;
+  if (scenario.audio) {
+    const a = scenario.audio;
+    if (/^https?:\/\//.test(a.file)) {
+      const hash = createHash("sha256").update(a.file).digest("hex").slice(0, 16);
+      audioPath = join2(tmpdir2(), `clipwise-audio-${hash}${a.file.match(/\.\w{2,4}$/)?.[0] ?? ".mp3"}`);
+      if (!existsSync2(audioPath)) {
+        execSync(`curl -sL -o "${audioPath}" "${a.file}"`, { stdio: ["ignore", "ignore", "pipe"] });
+      }
+    } else {
+      audioPath = isAbsolute2(a.file) ? a.file : resolve2(scenarioDir, a.file);
+    }
+  }
   const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
-  try {
+  const renderPass = async (stageW, stageH, passLabel) => {
+    let elapsedMs = 0;
+    const segments = [];
     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})`;
+      const label = `${passLabel}${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 + dur) / totalMs).toFixed(4)
       } : {};
+      if (scenario.captions.length > 0) {
+        thread.capsJson = JSON.stringify(scenario.captions);
+        thread.capsOffset = (elapsedMs / 1e3).toFixed(3);
+      }
       elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
@@ -4293,63 +4329,70 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
           url,
           { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       } else {
         const take = takes.get(scene.footage);
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          {
+            ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur, stageW, stageH),
+            ...thread
+          },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       }
-      const segPath = join2(tmp, `s${i}.mp4`);
+      const segPath = join2(tmp, `${passLabel.replace(/\W/g, "")}s${i}.mp4`);
       await writeFile2(segPath, segment.buffer);
       segments.push({ path: segPath, seconds: segment.seconds });
     }
+    const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
+    const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
+    const vChain = `${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]`;
+    const finalLabel = "[v]";
+    let audioInput = "";
+    let audioMap = "";
+    if (scenario.audio && audioPath) {
+      const a = scenario.audio;
+      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 = `-stream_loop -1 -i "${audioPath}" `;
+      audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k `;
+    }
+    const outPath = join2(tmp, `${passLabel.replace(/\W/g, "")}timeline.mp4`);
+    execSync(
+      `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${vChain}" -map "${finalLabel}" ${audioMap}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    return readFile4(outPath);
+  };
+  try {
+    const buffer = await renderPass(scenario.viewport.width, scenario.viewport.height, "");
+    const extras = [];
+    for (const aspect of scenario.output.aspects) {
+      const [w, h] = ASPECT_DIMS[aspect];
+      extras.push({ label: aspect.replace(":", "x"), buffer: await renderPass(w, h, `${aspect} \xB7 `) });
+    }
+    return { buffer, extras };
   } finally {
     server.close();
-  }
-  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 = "";
-  const totalSec = totalMs / 1e3;
-  if (scenario.audio) {
-    const a = scenario.audio;
-    let audioPath;
-    if (/^https?:\/\//.test(a.file)) {
-      const hash = createHash("sha256").update(a.file).digest("hex").slice(0, 16);
-      audioPath = join2(tmpdir2(), `clipwise-audio-${hash}${a.file.match(/\.\w{2,4}$/)?.[0] ?? ".mp3"}`);
-      if (!existsSync2(audioPath)) {
-        execSync(`curl -sL -o "${audioPath}" "${a.file}"`, { stdio: ["ignore", "ignore", "pipe"] });
-      }
-    } else {
-      audioPath = isAbsolute2(a.file) ? a.file : resolve2(scenarioDir, a.file);
-    }
-    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 = `-stream_loop -1 -i "${audioPath}" `;
-    audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k `;
-  }
-  execSync(
-    `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}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
-    { stdio: ["ignore", "ignore", "pipe"] }
-  );
-  const buffer = await readFile4(outPath);
-  await rm2(tmp, { recursive: true, force: true }).catch(() => {
-  });
-  for (const take of takes.values()) {
-    await rm2(take.framesDir, { recursive: true, force: true }).catch(() => {
+    await rm2(tmp, { recursive: true, force: true }).catch(() => {
     });
+    for (const take of takes.values()) {
+      await rm2(take.framesDir, { recursive: true, force: true }).catch(() => {
+      });
+    }
   }
-  return buffer;
 }
+var ASPECT_DIMS;
 var init_runner = __esm({
   "src/scenes/runner.ts"() {
     "use strict";
@@ -4357,6 +4400,11 @@ var init_runner = __esm({
     init_prepare();
     init_canvas_renderer();
     init_video_encoder();
+    ASPECT_DIMS = {
+      "16:9": [1280, 720],
+      "9:16": [720, 1280],
+      "1:1": [960, 960]
+    };
   }
 });
 
@@ -4402,6 +4450,15 @@ function validateScenario(scenario) {
       }
     }
   }
+  for (let i = 0; i < scenario.captions.length; i++) {
+    const c = scenario.captions[i];
+    if (c.end <= c.start) {
+      errors.push(`captions #${i + 1} ("${c.text.slice(0, 20)}"): end must be greater than start`);
+    }
+  }
+  if (scenario.captions.length > 0 && !scenario.scenes?.length) {
+    warnings.push("captions are only rendered in scenes timelines (ignored for classic steps recordings)");
+  }
   if (scenario.steps.length > 0) {
     const firstStep = scenario.steps[0];
     const hasNavigate = firstStep.actions.some(
@@ -4585,7 +4642,7 @@ import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
-).version("0.10.1");
+).version("0.11.1");
 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)"
@@ -4649,12 +4706,17 @@ program.command("record").description("Record a demo from a YAML scenario file")
       const outDir2 = scenario.output.outputDir;
       await mkdir2(outDir2, { recursive: true });
       spinner.start(`Rendering ${scenario.scenes.length}-scene timeline...`);
-      const buf = await renderScenesTimeline2(scenario, scenarioDir, ({ scene, total, label }) => {
+      const { buffer: buf, extras } = await renderScenesTimeline2(scenario, scenarioDir, ({ scene, total, label }) => {
         spinner.text = scene === 0 ? `Recording footage \u2014 ${label}...` : `Rendering scene ${scene}/${total} \u2014 ${label}...`;
       });
       const outputPath = join3(outDir2, `${scenario.output.filename}.mp4`);
       await writeFile3(outputPath, buf);
       spinner.succeed(`Timeline saved to ${chalk.bold(outputPath)} (${(buf.length / 1048576).toFixed(2)} MB)`);
+      for (const extra of extras) {
+        const extraPath = join3(outDir2, `${scenario.output.filename}-${extra.label}.mp4`);
+        await writeFile3(extraPath, extra.buffer);
+        spinner.succeed(`  + ${chalk.bold(extraPath)} (${(extra.buffer.length / 1048576).toFixed(2)} MB)`);
+      }
       console.log(chalk.green("\nDone! \u{1F3AC}"));
       return;
     }
@@ -4864,6 +4926,11 @@ steps:
 name: "My Launch Video"
 viewport: { width: 1280, height: 800, deviceScaleFactor: 2 }   # 2 = retina quality
 
+# Optional extras (uncomment to use):
+# audio: { file: "https://assets.mixkit.co/music/132/132.mp3", bpm: 120, volume: 0.32, fadeOut: 2000 }
+# captions:
+#   - { text: "Recorded from a real app", start: 0.4, end: 2.4 }
+
 effects:
   cursor: { enabled: true, clickEffect: true, highlight: false, trail: false }
 
@@ -4872,6 +4939,7 @@ output:
   fps: 30
   preset: balanced
   filename: keynote
+  # aspects: ["9:16"]        # also render a reels-format file in the same run
 
 scenes:
   # footage take \u2014 recorded once; vignettes below quote it by step

package/dist/index.d.ts

@@ -627,6 +627,9 @@ declare const OutputConfigSchema: z.ZodObject<{
     codec: z.ZodDefault<z.ZodEnum<["auto", "h264", "hevc", "av1"]>>;
     outputDir: z.ZodDefault<z.ZodString>;
     filename: z.ZodDefault<z.ZodString>;
+    /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+     *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+    aspects: z.ZodDefault<z.ZodArray<z.ZodEnum<["16:9", "9:16", "1:1"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     format: "gif" | "mp4" | "webm" | "png-sequence";
     width: number;
@@ -636,6 +639,7 @@ declare const OutputConfigSchema: z.ZodObject<{
     codec: "auto" | "h264" | "hevc" | "av1";
     outputDir: string;
     filename: string;
+    aspects: ("16:9" | "9:16" | "1:1")[];
     preset?: "social" | "balanced" | "archive" | undefined;
 }, {
     format?: "gif" | "mp4" | "webm" | "png-sequence" | undefined;
@@ -647,6 +651,7 @@ declare const OutputConfigSchema: z.ZodObject<{
     codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
     outputDir?: string | undefined;
     filename?: string | undefined;
+    aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
 }>;
 type OutputConfig = z.infer<typeof OutputConfigSchema>;
 /**
@@ -5521,6 +5526,9 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: z.ZodDefault<z.ZodEnum<["auto", "h264", "hevc", "av1"]>>;
         outputDir: z.ZodDefault<z.ZodString>;
         filename: z.ZodDefault<z.ZodString>;
+        /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+         *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+        aspects: z.ZodDefault<z.ZodArray<z.ZodEnum<["16:9", "9:16", "1:1"]>, "many">>;
     }, "strip", z.ZodTypeAny, {
         format: "gif" | "mp4" | "webm" | "png-sequence";
         width: number;
@@ -5530,6 +5538,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: "auto" | "h264" | "hevc" | "av1";
         outputDir: string;
         filename: string;
+        aspects: ("16:9" | "9:16" | "1:1")[];
         preset?: "social" | "balanced" | "archive" | undefined;
     }, {
         format?: "gif" | "mp4" | "webm" | "png-sequence" | undefined;
@@ -5541,6 +5550,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
+        aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
     }>>;
     /** Optional audio narration — muxed into MP4 output. */
     audio: z.ZodOptional<z.ZodObject<{
@@ -7860,6 +7870,20 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             coords?: number[] | undefined;
         }[] | undefined;
     }>]>, "many">>;
+    /** scenes 전용 — 선언형 캡션 트랙 (스타일은 brand accent를 따른다). */
+    captions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        start: number;
+        end: number;
+    }, {
+        text: string;
+        start: number;
+        end: number;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     effects: {
@@ -8105,8 +8129,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: "auto" | "h264" | "hevc" | "av1";
         outputDir: string;
         filename: string;
+        aspects: ("16:9" | "9:16" | "1:1")[];
         preset?: "social" | "balanced" | "archive" | undefined;
     };
+    captions: {
+        text: string;
+        start: number;
+        end: number;
+    }[];
     description?: string | undefined;
     auth?: {
         storageState?: string | undefined;
@@ -8625,6 +8655,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
+        aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
     } | undefined;
     audio?: {
         file: string;
@@ -8830,6 +8861,11 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             coords?: number[] | undefined;
         }[] | undefined;
     })[] | undefined;
+    captions?: {
+        text: string;
+        start: number;
+        end: number;
+    }[] | undefined;
 }>, {
     name: string;
     effects: {
@@ -9075,8 +9111,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: "auto" | "h264" | "hevc" | "av1";
         outputDir: string;
         filename: string;
+        aspects: ("16:9" | "9:16" | "1:1")[];
         preset?: "social" | "balanced" | "archive" | undefined;
     };
+    captions: {
+        text: string;
+        start: number;
+        end: number;
+    }[];
     description?: string | undefined;
     auth?: {
         storageState?: string | undefined;
@@ -9595,6 +9637,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
+        aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
     } | undefined;
     audio?: {
         file: string;
@@ -9800,6 +9843,11 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             coords?: number[] | undefined;
         }[] | undefined;
     })[] | undefined;
+    captions?: {
+        text: string;
+        start: number;
+        end: number;
+    }[] | undefined;
 }>;
 type Scenario = z.infer<typeof ScenarioSchema>;
 interface KeystrokeEvent {
@@ -10628,10 +10676,19 @@ interface SceneProgress {
     total: number;
     label: string;
 }
+interface ScenesRenderResult {
+    /** 기본 비율(viewport 크기) 렌더. */
+    buffer: Buffer;
+    /** output.aspects로 요청된 추가 비율 렌더 (label 예: "9x16"). */
+    extras: {
+        label: string;
+        buffer: Buffer;
+    }[];
+}
 /**
- * scenes 타임라인을 렌더해 MP4 버퍼를 반환한다.
+ * scenes 타임라인을 렌더한다 — 기본 비율 + output.aspects 추가 비율.
  */
-declare function renderScenesTimeline(scenario: Scenario, scenarioDir: string, onProgress?: (p: SceneProgress) => void): Promise<Buffer>;
+declare function renderScenesTimeline(scenario: Scenario, scenarioDir: string, onProgress?: (p: SceneProgress) => void): Promise<ScenesRenderResult>;
 
 /**
  * Parse a YAML string and return a validated Scenario object.

package/dist/index.js

@@ -3631,15 +3631,20 @@ async function executeStepsForProbe(page, scene) {
     }
   }
 }
-function segmentOutput(scenario) {
+function segmentOutput(scenario, stageW, stageH) {
   const dpr = scenario.viewport.deviceScaleFactor ?? 1;
   return {
     ...scenario.output,
-    width: scenario.output.width * dpr,
-    height: scenario.output.height * dpr,
+    width: stageW * dpr,
+    height: stageH * dpr,
     preset: "archive"
   };
 }
+var ASPECT_DIMS = {
+  "16:9": [1280, 720],
+  "9:16": [720, 1280],
+  "1:1": [960, 960]
+};
 async function recordFootageTake(scenario, scene, selectors) {
   const boxes = /* @__PURE__ */ new Map();
   if (selectors.length > 0) {
@@ -3665,7 +3670,11 @@ async function recordFootageTake(scenario, scene, selectors) {
   };
   const recorder = new ClipwiseRecorder();
   const session = await recorder.record(takeScenario);
-  const renderer = new CanvasRenderer(takeScenario.effects, segmentOutput(scenario), scene.steps);
+  const renderer = new CanvasRenderer(
+    takeScenario.effects,
+    segmentOutput(scenario, scenario.viewport.width, scenario.viewport.height),
+    scene.steps
+  );
   const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
   let count = 0;
   for await (const f of renderer.composeStream(session.frames)) {
@@ -3685,12 +3694,12 @@ async function recordFootageTake(scenario, scene, selectors) {
 function fitCardW(cw, ch, maxW = 940, maxH = 540) {
   return Math.round(Math.min(maxW, maxH * cw / ch));
 }
-async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
+async function captureMotionSegment(templateUrl, props, durationMs, scenario, stageW, stageH) {
   const fps = scenario.output.fps;
   const totalFrames = Math.round(durationMs / 1e3 * fps);
   const browser = await chromium2.launch();
   const page = await browser.newPage({
-    viewport: { width: scenario.output.width, height: scenario.output.height },
+    viewport: { width: stageW, height: stageH },
     deviceScaleFactor: scenario.viewport.deviceScaleFactor ?? 1
   });
   const params = new URLSearchParams(
@@ -3708,9 +3717,12 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
     frames.push({ index: i, buffer: await page.screenshot({ type: "png" }), timestamp: t });
   }
   await browser.close();
-  return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
+  return {
+    buffer: await encodeMp4(frames, segmentOutput(scenario, stageW, stageH)),
+    seconds: totalFrames / fps
+  };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs, stageW, stageH) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -3748,7 +3760,8 @@ function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
     cropY: crop.y,
     cropW: crop.w,
     cropH: crop.h,
-    cardW: fitCardW(crop.w, crop.h),
+    // 카드 크기 상한은 무대(stage) 크기 비례 — 어떤 출력 비율에서도 일관된 여백
+    cardW: fitCardW(crop.w, crop.h, Math.round(stageW * 0.735), Math.round(stageH * 0.675)),
     pushFrom: scene.push?.from ?? 1,
     pushTo: scene.push?.to ?? 1
   };
@@ -3818,19 +3831,37 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     (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 totalSec = totalMs / 1e3;
+  let audioPath = null;
+  if (scenario.audio) {
+    const a = scenario.audio;
+    if (/^https?:\/\//.test(a.file)) {
+      const hash = createHash("sha256").update(a.file).digest("hex").slice(0, 16);
+      audioPath = join2(tmpdir2(), `clipwise-audio-${hash}${a.file.match(/\.\w{2,4}$/)?.[0] ?? ".mp3"}`);
+      if (!existsSync2(audioPath)) {
+        execSync(`curl -sL -o "${audioPath}" "${a.file}"`, { stdio: ["ignore", "ignore", "pipe"] });
+      }
+    } else {
+      audioPath = isAbsolute(a.file) ? a.file : resolve(scenarioDir, a.file);
+    }
+  }
   const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
-  try {
+  const renderPass = async (stageW, stageH, passLabel) => {
+    let elapsedMs = 0;
+    const segments = [];
     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})`;
+      const label = `${passLabel}${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 + dur) / totalMs).toFixed(4)
       } : {};
+      if (scenario.captions.length > 0) {
+        thread.capsJson = JSON.stringify(scenario.captions);
+        thread.capsOffset = (elapsedMs / 1e3).toFixed(3);
+      }
       elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
@@ -3839,62 +3870,68 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
           url,
           { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       } else {
         const take = takes.get(scene.footage);
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          {
+            ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur, stageW, stageH),
+            ...thread
+          },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       }
-      const segPath = join2(tmp, `s${i}.mp4`);
+      const segPath = join2(tmp, `${passLabel.replace(/\W/g, "")}s${i}.mp4`);
       await writeFile2(segPath, segment.buffer);
       segments.push({ path: segPath, seconds: segment.seconds });
     }
+    const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
+    const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
+    const vChain = `${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]`;
+    const finalLabel = "[v]";
+    let audioInput = "";
+    let audioMap = "";
+    if (scenario.audio && audioPath) {
+      const a = scenario.audio;
+      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 = `-stream_loop -1 -i "${audioPath}" `;
+      audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k `;
+    }
+    const outPath = join2(tmp, `${passLabel.replace(/\W/g, "")}timeline.mp4`);
+    execSync(
+      `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${vChain}" -map "${finalLabel}" ${audioMap}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    return readFile3(outPath);
+  };
+  try {
+    const buffer = await renderPass(scenario.viewport.width, scenario.viewport.height, "");
+    const extras = [];
+    for (const aspect of scenario.output.aspects) {
+      const [w, h] = ASPECT_DIMS[aspect];
+      extras.push({ label: aspect.replace(":", "x"), buffer: await renderPass(w, h, `${aspect} \xB7 `) });
+    }
+    return { buffer, extras };
   } finally {
     server.close();
-  }
-  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 = "";
-  const totalSec = totalMs / 1e3;
-  if (scenario.audio) {
-    const a = scenario.audio;
-    let audioPath;
-    if (/^https?:\/\//.test(a.file)) {
-      const hash = createHash("sha256").update(a.file).digest("hex").slice(0, 16);
-      audioPath = join2(tmpdir2(), `clipwise-audio-${hash}${a.file.match(/\.\w{2,4}$/)?.[0] ?? ".mp3"}`);
-      if (!existsSync2(audioPath)) {
-        execSync(`curl -sL -o "${audioPath}" "${a.file}"`, { stdio: ["ignore", "ignore", "pipe"] });
-      }
-    } else {
-      audioPath = isAbsolute(a.file) ? a.file : resolve(scenarioDir, a.file);
-    }
-    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 = `-stream_loop -1 -i "${audioPath}" `;
-    audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k `;
-  }
-  execSync(
-    `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}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
-    { stdio: ["ignore", "ignore", "pipe"] }
-  );
-  const buffer = await readFile3(outPath);
-  await rm2(tmp, { recursive: true, force: true }).catch(() => {
-  });
-  for (const take of takes.values()) {
-    await rm2(take.framesDir, { recursive: true, force: true }).catch(() => {
+    await rm2(tmp, { recursive: true, force: true }).catch(() => {
     });
+    for (const take of takes.values()) {
+      await rm2(take.framesDir, { recursive: true, force: true }).catch(() => {
+      });
+    }
   }
-  return buffer;
 }
 
 // src/script/parser.ts
@@ -4146,7 +4183,10 @@ var OutputConfigSchema = z.object({
   codec: z.enum(["auto", "h264", "hevc", "av1"]).default("auto"),
   // Zero-Footprint 계약 (v0.8): 모든 산출물은 .clipwise/ 아래로.
   outputDir: z.string().default(".clipwise/output"),
-  filename: z.string().default("clipwise-recording")
+  filename: z.string().default("clipwise-recording"),
+  /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+   *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+  aspects: z.array(z.enum(["16:9", "9:16", "1:1"])).default([])
 });
 var StepEffectsOverrideSchema = z.object({
   zoom: ZoomEffectSchema.partial().optional(),
@@ -4299,6 +4339,11 @@ var SceneSchema = z.discriminatedUnion("type", [
   ScreenSceneSchema,
   VignetteSceneSchema
 ]);
+var CaptionSchema = z.object({
+  text: z.string().min(1),
+  start: z.number().min(0),
+  end: z.number().min(0)
+});
 var ScenarioSchema = z.object({
   name: z.string(),
   description: z.string().optional(),
@@ -4319,7 +4364,9 @@ var ScenarioSchema = z.object({
   /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
   steps: z.array(StepSchema).default([]),
   /** Scene System (v0.9 preview) — motion/screen/vignette 타임라인. */
-  scenes: z.array(SceneSchema).optional()
+  scenes: z.array(SceneSchema).optional(),
+  /** scenes 전용 — 선언형 캡션 트랙 (스타일은 brand accent를 따른다). */
+  captions: z.array(CaptionSchema).default([])
 }).superRefine((s, ctx) => {
   if (s.steps.length === 0 && !s.scenes?.length) {
     ctx.addIssue({
@@ -4417,6 +4464,15 @@ function validateScenario(scenario) {
       }
     }
   }
+  for (let i = 0; i < scenario.captions.length; i++) {
+    const c = scenario.captions[i];
+    if (c.end <= c.start) {
+      errors.push(`captions #${i + 1} ("${c.text.slice(0, 20)}"): end must be greater than start`);
+    }
+  }
+  if (scenario.captions.length > 0 && !scenario.scenes?.length) {
+    warnings.push("captions are only rendered in scenes timelines (ignored for classic steps recordings)");
+  }
   if (scenario.steps.length > 0) {
     const firstStep = scenario.steps[0];
     const hasNavigate = firstStep.actions.some(

package/package.json

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

package/skills/clipwise.md

@@ -399,6 +399,10 @@ scenes:
 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)
+9. **Social formats**: `output.aspects: ["9:16", "1:1"]` renders extra reels/feed files in the
+   same run — footage is recorded once, only the stage re-composes. Files: `name-9x16.mp4` etc.
+10. **Captions**: top-level `captions: [{ text, start, end }]` (timeline-absolute seconds)
+   burns styled caption pills into every aspect — great for sound-off social playback
 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).
    `file:` also accepts a URL (downloaded+cached on the user's machine — use license-free

package/templates/motion/kinetic-type.html

@@ -91,6 +91,24 @@
   /* ── 스레드 — 영상 전체를 관통하는 한 줄의 잉크 선.
      threadFrom→threadTo 구간을 신 길이 동안 선형으로 전진시키면
      하드컷을 넘어도 같은 경로 위에서 끊김 없이 이어진다. ── */
+
+  /* ── 전역 캡션 트랙 — 타임라인 절대시각 기준, 신 경계를 넘어 이어진다.
+     ffmpeg 자막 필터(libass) 의존 없이 템플릿 레이어로 렌더 — 어떤 ffmpeg
+     빌드에서도 동작하고 폰트·브랜드 토큰을 그대로 쓴다. ── */
+  .gcap { position: absolute; left: 50%; transform: translateX(-50%);
+    bottom: 2.4%; z-index: 8; max-width: 86%;
+    font-family: var(--sans); font-weight: 600; color: var(--ink);
+    background: rgba(255, 255, 255, 0.82); border: 1px solid rgba(20, 20, 19, 0.08);
+    border-radius: 12px; padding: 0.5em 1.1em; text-align: center;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    opacity: 0; animation: gcap-show linear both; }
+  @keyframes gcap-show {
+    0% { opacity: 0; transform: translateX(-50%) translateY(8px); }
+    7% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    93% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    100% { opacity: 0; transform: translateX(-50%) translateY(0); }
+  }
+
   .thread { position: absolute; inset: 0; pointer-events: none; z-index: 2; }
   .thread path { fill: none; stroke: var(--accent); stroke-width: 2.5; opacity: 0.55;
     stroke-linecap: round;
@@ -114,7 +132,8 @@
   <script>
     const P = new URLSearchParams(location.search);
     document.documentElement.style.setProperty("--accent", P.get("accent") || "#6366f1");
-    if (P.get("size")) document.documentElement.style.setProperty("--size", P.get("size") + "px");
+    const stageScale = Math.max(0.55, Math.min(1, innerWidth / 1280));
+    if (P.get("size")) document.documentElement.style.setProperty("--size", (parseFloat(P.get("size")) * stageScale).toFixed(1) + "px");
     document.documentElement.dataset.font = P.get("font") || "editorial";
     const FX = P.get("fx") || "underline"; // underline | marker | off
 
@@ -164,13 +183,17 @@
     }
 
     // ── 스레드: 모든 신이 공유하는 동일 경로 — 구간만 다르게 전진 ──
-    const THREAD_PATH = "M -6 716 C 150 704, 320 730, 480 714 S 770 724, 940 706 S 1180 728, 1286 712";
+    // 스레드 경로 — 스테이지 크기에서 동적 생성. 두 템플릿이 동일 공식을 쓰므로
+    // 어떤 비율(16:9/9:16/1:1)에서도 신 간 연속성이 유지된다.
+    const _W = innerWidth, _H = innerHeight, _ty = _H * 0.895, _a = _H * 0.016;
+    const _f = (n) => n.toFixed(1);
+    const THREAD_PATH = `M -6 ${_f(_ty - _a * 0.3)} C ${_f(_W * 0.12)} ${_f(_ty - _a)}, ${_f(_W * 0.25)} ${_f(_ty + _a)}, ${_f(_W * 0.375)} ${_f(_ty - _a * 0.2)} S ${_f(_W * 0.6)} ${_f(_ty + _a * 0.6)}, ${_f(_W * 0.734)} ${_f(_ty - _a * 1.1)} S ${_f(_W * 0.92)} ${_f(_ty + _a)}, ${_f(_W + 6)} ${_f(_ty - _a * 0.4)}`;
     const tf = P.get("threadFrom"), tt = P.get("threadTo");
     if (tf !== null && tt !== null) {
       const durS = parseFloat(P.get("dur") || "3");
       const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
       svg.setAttribute("class", "thread");
-      svg.setAttribute("viewBox", "0 0 1280 800");
+      svg.setAttribute("viewBox", `0 0 ${_W} ${_H}`);
       svg.innerHTML = `<path d="${THREAD_PATH}" pathLength="1"
         style="--tf:${tf};--tt:${tt};animation-duration:${durS}s"/>`;
       stage.appendChild(svg);
@@ -196,6 +219,25 @@
       }
     });
 
+
+    // 전역 캡션 — capsJson(절대 start/end 초) + capsOffset(이 신의 절대 시작 초)
+    if (P.get("capsJson")) {
+      const offset = parseFloat(P.get("capsOffset") || "0");
+      const sceneDur = parseFloat(P.get("dur") || "4");
+      const capFs = Math.max(15, innerHeight * 0.026);
+      for (const c of JSON.parse(P.get("capsJson"))) {
+        const s = c.start - offset, e = c.end - offset;
+        if (e <= 0 || s >= sceneDur) continue; // 이 신과 무관
+        const el = document.createElement("div");
+        el.className = "gcap";
+        el.textContent = c.text;
+        el.style.fontSize = capFs.toFixed(1) + "px";
+        el.style.animationDelay = Math.max(0, s).toFixed(3) + "s";
+        el.style.animationDuration = (Math.min(e, sceneDur) - Math.max(0, s)).toFixed(3) + "s";
+        document.querySelector(".stage").appendChild(el);
+      }
+    }
+
     window.__clipwiseSeek = async (t) => {
       await ready;
       for (const a of document.getAnimations()) { a.pause(); a.currentTime = t; }

package/templates/motion/vignette.html

@@ -64,6 +64,24 @@
   .stage { width: 100%; height: 100%; display: flex; flex-direction: column;
     align-items: center; justify-content: center; gap: 22px; position: relative; }
 
+
+  /* ── 전역 캡션 트랙 — 타임라인 절대시각 기준, 신 경계를 넘어 이어진다.
+     ffmpeg 자막 필터(libass) 의존 없이 템플릿 레이어로 렌더 — 어떤 ffmpeg
+     빌드에서도 동작하고 폰트·브랜드 토큰을 그대로 쓴다. ── */
+  .gcap { position: absolute; left: 50%; transform: translateX(-50%);
+    bottom: 2.4%; z-index: 8; max-width: 86%;
+    font-family: var(--sans); font-weight: 600; color: var(--ink);
+    background: rgba(255, 255, 255, 0.82); border: 1px solid rgba(20, 20, 19, 0.08);
+    border-radius: 12px; padding: 0.5em 1.1em; text-align: center;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    opacity: 0; animation: gcap-show linear both; }
+  @keyframes gcap-show {
+    0% { opacity: 0; transform: translateX(-50%) translateY(8px); }
+    7% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    93% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    100% { opacity: 0; transform: translateX(-50%) translateY(0); }
+  }
+
   /* 스레드 — 카드 뒤를 지나는 연결 선 (kinetic-type.html과 동일 경로/문법) */
   .thread { position: absolute; inset: 0; pointer-events: none; z-index: 1; }
   .thread path { fill: none; stroke: var(--accent); stroke-width: 2.5; opacity: 0.55;
@@ -279,14 +297,18 @@
     const img = document.getElementById("footage");
 
     // ── 스레드 — 모든 신이 공유하는 동일 경로, 구간(threadFrom→threadTo)만 전진 ──
-    const THREAD_PATH = "M -6 716 C 150 704, 320 730, 480 714 S 770 724, 940 706 S 1180 728, 1286 712";
+    // 스레드 경로 — 스테이지 크기에서 동적 생성. 두 템플릿이 동일 공식을 쓰므로
+    // 어떤 비율(16:9/9:16/1:1)에서도 신 간 연속성이 유지된다.
+    const _W = innerWidth, _H = innerHeight, _ty = _H * 0.895, _a = _H * 0.016;
+    const _f = (n) => n.toFixed(1);
+    const THREAD_PATH = `M -6 ${_f(_ty - _a * 0.3)} C ${_f(_W * 0.12)} ${_f(_ty - _a)}, ${_f(_W * 0.25)} ${_f(_ty + _a)}, ${_f(_W * 0.375)} ${_f(_ty - _a * 0.2)} S ${_f(_W * 0.6)} ${_f(_ty + _a * 0.6)}, ${_f(_W * 0.734)} ${_f(_ty - _a * 1.1)} S ${_f(_W * 0.92)} ${_f(_ty + _a)}, ${_f(_W + 6)} ${_f(_ty - _a * 0.4)}`;
     const tf = P.get("threadFrom"), tt = P.get("threadTo");
     if (tf !== null && tt !== null) {
       const durS = parseFloat(P.get("dur") || "4");
       const stage = document.querySelector(".stage");
       const tsvg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
       tsvg.setAttribute("class", "thread");
-      tsvg.setAttribute("viewBox", "0 0 1280 800");
+      tsvg.setAttribute("viewBox", `0 0 ${_W} ${_H}`);
       tsvg.innerHTML = `<path d="${THREAD_PATH}" pathLength="1"
         style="--tf:${tf};--tt:${tt};animation-duration:${durS}s"/>`;
       stage.appendChild(tsvg);
@@ -296,6 +318,25 @@
       stage.appendChild(dot);
     }
 
+
+    // 전역 캡션 — capsJson(절대 start/end 초) + capsOffset(이 신의 절대 시작 초)
+    if (P.get("capsJson")) {
+      const offset = parseFloat(P.get("capsOffset") || "0");
+      const sceneDur = parseFloat(P.get("dur") || "4");
+      const capFs = Math.max(15, innerHeight * 0.026);
+      for (const c of JSON.parse(P.get("capsJson"))) {
+        const s = c.start - offset, e = c.end - offset;
+        if (e <= 0 || s >= sceneDur) continue; // 이 신과 무관
+        const el = document.createElement("div");
+        el.className = "gcap";
+        el.textContent = c.text;
+        el.style.fontSize = capFs.toFixed(1) + "px";
+        el.style.animationDelay = Math.max(0, s).toFixed(3) + "s";
+        el.style.animationDuration = (Math.min(e, sceneDur) - Math.max(0, s)).toFixed(3) + "s";
+        document.querySelector(".stage").appendChild(el);
+      }
+    }
+
     window.__clipwiseSeek = async (t) => {
       for (const a of document.getAnimations()) { a.pause(); a.currentTime = t; }
       if (BASE) {