clipwise 0.11.0 → 0.12.0

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

@@ -789,6 +789,9 @@ var init_recorder = __esm({
       frameChannel = null;
       channelIndex = 0;
       // sequential index for channel-pushed frames
+      /** low-memory 채널 모드 — 버퍼는 스트림으로만 내보내고 내부에는 메타데이터만
+       *  보관한다. done의 frames는 빈 screenshot + sourceIndex(원본 참조)를 갖는다. */
+      channelLowMemory = false;
       /**
        * Launch the browser and create a page with the scenario viewport.
        */
@@ -834,6 +837,7 @@ var init_recorder = __esm({
         this.dedupStats = { received: 0, stored: 0, skipped: 0 };
         this.frameChannel = null;
         this.channelIndex = 0;
+        this.channelLowMemory = false;
       }
       /**
        * Start CDP screencast for continuous frame capture.
@@ -867,6 +871,9 @@ var init_recorder = __esm({
                   this.channelIndex++
                 );
                 this.frameChannel.push(frame);
+                if (this.channelLowMemory) {
+                  rawFrame.buffer = Buffer.alloc(0);
+                }
               }
             }
             await this.cdpClient.send("Page.screencastFrameAck", {
@@ -1000,12 +1007,13 @@ var init_recorder = __esm({
        * Use this with CanvasRenderer.composeStreamOnline() to overlap recording
        * time with composition time — total wall-clock ≈ max(recordingMs, composeMs).
        */
-      recordToChannel(scenario) {
+      recordToChannel(scenario, options) {
         const channel = new FrameChannel();
         const done = (async () => {
           try {
             await this.init(scenario);
             this.frameChannel = channel;
+            this.channelLowMemory = options?.lowMemory ?? false;
             const startTime = Date.now();
             if (scenario.steps.length > 0) {
               const s0 = scenario.steps[0];
@@ -1562,7 +1570,9 @@ var init_recorder = __esm({
           frames.length,
           Math.round(recordingDurationMs / 1e3 * this.targetFps)
         );
-        if (targetFrameCount <= frames.length) return frames;
+        if (targetFrameCount <= frames.length) {
+          return frames.map((f, idx) => ({ ...f, sourceIndex: idx }));
+        }
         const startTime = frames[0].timestamp;
         const endTime = frames[frames.length - 1].timestamp;
         const duration = Math.max(1, endTime - startTime);
@@ -1588,6 +1598,7 @@ var init_recorder = __esm({
           resampled.push({
             index: i,
             screenshot: frames[nearestIdx].screenshot,
+            sourceIndex: nearestIdx,
             timestamp: targetTimestamp,
             cursorPosition: cursorPos,
             clickPosition: clickEvent?.position ?? null,
@@ -2824,7 +2835,7 @@ var init_canvas_renderer = __esm({
     init_transition();
     MIN_FRAMES_PER_WORKER = 4;
     cachedWorkerUrl = null;
-    CanvasRenderer = class {
+    CanvasRenderer = class _CanvasRenderer {
       constructor(effects, output, steps) {
         this.effects = effects;
         this.output = output;
@@ -3219,25 +3230,28 @@ var init_canvas_renderer = __esm({
        * Uses a notify-on-progress pattern (same as streamWithWorkers) extended
        * with an intake coroutine that feeds the growing frames[] buffer.
        */
+      static EMPTY_SCREENSHOT = Buffer.alloc(0);
       async *streamOnlineWithWorkers(source, workerCount) {
         const transitionFrames = this.effects.zoom.enabled ? Math.round(this.output.fps * (this.effects.zoom.duration / 1e3)) : 0;
         const trailLength = this.effects.cursor.trailLength;
         const frames = [];
         let sourceComplete = false;
         let workerError = null;
-        let notify = null;
+        let waiters = [];
         const trigger = () => {
-          notify?.();
-          notify = null;
+          const ws = waiters;
+          waiters = [];
+          for (const w of ws) w();
         };
         const waitForProgress = () => new Promise((r) => {
-          notify = r;
+          waiters.push(r);
         });
         const completed = /* @__PURE__ */ new Map();
         const idleWorkers = [];
         let nextToDispatch = 0;
         let nextToYield = 0;
-        const canDispatch = (i) => i < frames.length && (sourceComplete || frames.length > i + transitionFrames);
+        const MAX_BACKLOG = workerCount * 3;
+        const canDispatch = (i) => i < frames.length && (sourceComplete || frames.length > i + transitionFrames) && i - nextToYield < MAX_BACKLOG;
         const effectiveScale = resolveZoomScale(
           this.effects.zoom.scale,
           this.effects.zoom.intensity
@@ -3277,6 +3291,7 @@ var init_canvas_renderer = __esm({
               output: this.output,
               context: computeContext(i)
             });
+            frames[i] = { ...frames[i], screenshot: _CanvasRenderer.EMPTY_SCREENSHOT };
           } else {
             idleWorkers.push(worker);
           }
@@ -3312,11 +3327,15 @@ var init_canvas_renderer = __esm({
           });
           idleWorkers.push(worker);
         }
+        const INTAKE_AHEAD = Math.max(MAX_BACKLOG, transitionFrames + workerCount) + 16;
         const intakeTask = (async () => {
           for await (const frame of source) {
             frames.push(frame);
             dispatchToIdle();
             trigger();
+            while (!workerError && frames.length - nextToYield > INTAKE_AHEAD) {
+              await waitForProgress();
+            }
           }
           sourceComplete = true;
           dispatchToIdle();
@@ -3332,6 +3351,8 @@ var init_canvas_renderer = __esm({
               const frame = completed.get(nextToYield);
               completed.delete(nextToYield);
               nextToYield++;
+              dispatchToIdle();
+              trigger();
               yield frame;
               continue;
             }
@@ -4128,21 +4149,34 @@ async function recordFootageTake(scenario, scene, selectors) {
     effects: footageEffects(scenario.effects)
   };
   const recorder = new ClipwiseRecorder();
-  const session = await recorder.record(takeScenario);
+  const handle = recorder.recordToChannel(takeScenario, { lowMemory: true });
+  const rawDir = await mkdtemp(join2(tmpdir2(), `clipwise-raw-${scene.id}-`));
+  for await (const frame of handle.frameStream) {
+    await writeFile2(join2(rawDir, `${frame.index}.png`), frame.screenshot);
+  }
+  const session = await handle.done;
   const renderer = new CanvasRenderer(
     takeScenario.effects,
     segmentOutput(scenario, scenario.viewport.width, scenario.viewport.height),
     scene.steps
   );
+  const planStream = (async function* () {
+    for (const f of session.frames) {
+      yield { ...f, screenshot: await readFile4(join2(rawDir, `${f.sourceIndex ?? f.index}.png`)) };
+    }
+  })();
   const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
   let count = 0;
-  for await (const f of renderer.composeStream(session.frames)) {
+  const composed = renderer.canStreamOnline() ? renderer.composeStreamOnline(planStream) : renderer.composeStream(session.frames);
+  for await (const f of composed) {
     const png = f.rawInfo ? await sharp10(f.buffer, {
       raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
     }).png().toBuffer() : f.buffer;
     await writeFile2(join2(framesDir, `${count}.png`), png);
     count++;
   }
+  await rm2(rawDir, { recursive: true, force: true }).catch(() => {
+  });
   const anchors = [];
   for (let k = 0; k < scene.steps.length; k++) {
     const idx = session.frames.findIndex((f) => (f.stepIndex ?? 0) >= k);
@@ -4642,7 +4676,7 @@ import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
-).version("0.11.0");
+).version("0.12.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)"
@@ -4926,6 +4960,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 }
 
@@ -4934,6 +4973,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

@@ -9889,6 +9889,11 @@ interface CapturedFrame {
     isWaitingPhase?: boolean;
     /** Speed multiplier for this frame when in a smartWait phase. */
     displaySpeed?: number;
+    /**
+     * low-memory 스트리밍 녹화에서 이 프레임이 참조하는 원본(채널) 프레임 인덱스.
+     * screenshot이 빈 버퍼일 때, 소비자가 디스크에 받아둔 원본을 이 인덱스로 찾는다.
+     */
+    sourceIndex?: number;
 }
 interface ComposedFrame {
     index: number;
@@ -9967,6 +9972,9 @@ declare class ClipwiseRecorder {
     private dedupStats;
     private frameChannel;
     private channelIndex;
+    /** low-memory 채널 모드 — 버퍼는 스트림으로만 내보내고 내부에는 메타데이터만
+     *  보관한다. done의 frames는 빈 screenshot + sourceIndex(원본 참조)를 갖는다. */
+    private channelLowMemory;
     /**
      * Launch the browser and create a page with the scenario viewport.
      */
@@ -9997,7 +10005,9 @@ declare class ClipwiseRecorder {
      * Use this with CanvasRenderer.composeStreamOnline() to overlap recording
      * time with composition time — total wall-clock ≈ max(recordingMs, composeMs).
      */
-    recordToChannel(scenario: Scenario): RecordingHandle;
+    recordToChannel(scenario: Scenario, options?: {
+        lowMemory?: boolean;
+    }): RecordingHandle;
     /**
      * Build a single CapturedFrame from a RawFrame in real-time.
      * Used by recordToChannel() to emit frames as they arrive.
@@ -10292,6 +10302,7 @@ declare class CanvasRenderer {
      * Uses a notify-on-progress pattern (same as streamWithWorkers) extended
      * with an intake coroutine that feeds the growing frames[] buffer.
      */
+    private static readonly EMPTY_SCREENSHOT;
     private streamOnlineWithWorkers;
     /**
      * Stream frame composition — yields ComposedFrames as workers finish,

package/dist/index.js

@@ -247,6 +247,9 @@ var ClipwiseRecorder = class {
   frameChannel = null;
   channelIndex = 0;
   // sequential index for channel-pushed frames
+  /** low-memory 채널 모드 — 버퍼는 스트림으로만 내보내고 내부에는 메타데이터만
+   *  보관한다. done의 frames는 빈 screenshot + sourceIndex(원본 참조)를 갖는다. */
+  channelLowMemory = false;
   /**
    * Launch the browser and create a page with the scenario viewport.
    */
@@ -292,6 +295,7 @@ var ClipwiseRecorder = class {
     this.dedupStats = { received: 0, stored: 0, skipped: 0 };
     this.frameChannel = null;
     this.channelIndex = 0;
+    this.channelLowMemory = false;
   }
   /**
    * Start CDP screencast for continuous frame capture.
@@ -325,6 +329,9 @@ var ClipwiseRecorder = class {
               this.channelIndex++
             );
             this.frameChannel.push(frame);
+            if (this.channelLowMemory) {
+              rawFrame.buffer = Buffer.alloc(0);
+            }
           }
         }
         await this.cdpClient.send("Page.screencastFrameAck", {
@@ -458,12 +465,13 @@ var ClipwiseRecorder = class {
    * Use this with CanvasRenderer.composeStreamOnline() to overlap recording
    * time with composition time — total wall-clock ≈ max(recordingMs, composeMs).
    */
-  recordToChannel(scenario) {
+  recordToChannel(scenario, options) {
     const channel = new FrameChannel();
     const done = (async () => {
       try {
         await this.init(scenario);
         this.frameChannel = channel;
+        this.channelLowMemory = options?.lowMemory ?? false;
         const startTime = Date.now();
         if (scenario.steps.length > 0) {
           const s0 = scenario.steps[0];
@@ -1020,7 +1028,9 @@ var ClipwiseRecorder = class {
       frames.length,
       Math.round(recordingDurationMs / 1e3 * this.targetFps)
     );
-    if (targetFrameCount <= frames.length) return frames;
+    if (targetFrameCount <= frames.length) {
+      return frames.map((f, idx) => ({ ...f, sourceIndex: idx }));
+    }
     const startTime = frames[0].timestamp;
     const endTime = frames[frames.length - 1].timestamp;
     const duration = Math.max(1, endTime - startTime);
@@ -1046,6 +1056,7 @@ var ClipwiseRecorder = class {
       resampled.push({
         index: i,
         screenshot: frames[nearestIdx].screenshot,
+        sourceIndex: nearestIdx,
         timestamp: targetTimestamp,
         cursorPosition: cursorPos,
         clickPosition: clickEvent?.position ?? null,
@@ -2300,7 +2311,7 @@ function getWorkerUrl() {
   cachedWorkerUrl = candidates[1];
   return cachedWorkerUrl;
 }
-var CanvasRenderer = class {
+var CanvasRenderer = class _CanvasRenderer {
   constructor(effects, output, steps) {
     this.effects = effects;
     this.output = output;
@@ -2695,25 +2706,28 @@ var CanvasRenderer = class {
    * Uses a notify-on-progress pattern (same as streamWithWorkers) extended
    * with an intake coroutine that feeds the growing frames[] buffer.
    */
+  static EMPTY_SCREENSHOT = Buffer.alloc(0);
   async *streamOnlineWithWorkers(source, workerCount) {
     const transitionFrames = this.effects.zoom.enabled ? Math.round(this.output.fps * (this.effects.zoom.duration / 1e3)) : 0;
     const trailLength = this.effects.cursor.trailLength;
     const frames = [];
     let sourceComplete = false;
     let workerError = null;
-    let notify = null;
+    let waiters = [];
     const trigger = () => {
-      notify?.();
-      notify = null;
+      const ws = waiters;
+      waiters = [];
+      for (const w of ws) w();
     };
     const waitForProgress = () => new Promise((r) => {
-      notify = r;
+      waiters.push(r);
     });
     const completed = /* @__PURE__ */ new Map();
     const idleWorkers = [];
     let nextToDispatch = 0;
     let nextToYield = 0;
-    const canDispatch = (i) => i < frames.length && (sourceComplete || frames.length > i + transitionFrames);
+    const MAX_BACKLOG = workerCount * 3;
+    const canDispatch = (i) => i < frames.length && (sourceComplete || frames.length > i + transitionFrames) && i - nextToYield < MAX_BACKLOG;
     const effectiveScale = resolveZoomScale(
       this.effects.zoom.scale,
       this.effects.zoom.intensity
@@ -2753,6 +2767,7 @@ var CanvasRenderer = class {
           output: this.output,
           context: computeContext(i)
         });
+        frames[i] = { ...frames[i], screenshot: _CanvasRenderer.EMPTY_SCREENSHOT };
       } else {
         idleWorkers.push(worker);
       }
@@ -2788,11 +2803,15 @@ var CanvasRenderer = class {
       });
       idleWorkers.push(worker);
     }
+    const INTAKE_AHEAD = Math.max(MAX_BACKLOG, transitionFrames + workerCount) + 16;
     const intakeTask = (async () => {
       for await (const frame of source) {
         frames.push(frame);
         dispatchToIdle();
         trigger();
+        while (!workerError && frames.length - nextToYield > INTAKE_AHEAD) {
+          await waitForProgress();
+        }
       }
       sourceComplete = true;
       dispatchToIdle();
@@ -2808,6 +2827,8 @@ var CanvasRenderer = class {
           const frame = completed.get(nextToYield);
           completed.delete(nextToYield);
           nextToYield++;
+          dispatchToIdle();
+          trigger();
           yield frame;
           continue;
         }
@@ -3669,21 +3690,34 @@ async function recordFootageTake(scenario, scene, selectors) {
     effects: footageEffects(scenario.effects)
   };
   const recorder = new ClipwiseRecorder();
-  const session = await recorder.record(takeScenario);
+  const handle = recorder.recordToChannel(takeScenario, { lowMemory: true });
+  const rawDir = await mkdtemp(join2(tmpdir2(), `clipwise-raw-${scene.id}-`));
+  for await (const frame of handle.frameStream) {
+    await writeFile2(join2(rawDir, `${frame.index}.png`), frame.screenshot);
+  }
+  const session = await handle.done;
   const renderer = new CanvasRenderer(
     takeScenario.effects,
     segmentOutput(scenario, scenario.viewport.width, scenario.viewport.height),
     scene.steps
   );
+  const planStream = (async function* () {
+    for (const f of session.frames) {
+      yield { ...f, screenshot: await readFile3(join2(rawDir, `${f.sourceIndex ?? f.index}.png`)) };
+    }
+  })();
   const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
   let count = 0;
-  for await (const f of renderer.composeStream(session.frames)) {
+  const composed = renderer.canStreamOnline() ? renderer.composeStreamOnline(planStream) : renderer.composeStream(session.frames);
+  for await (const f of composed) {
     const png = f.rawInfo ? await sharp10(f.buffer, {
       raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
     }).png().toBuffer() : f.buffer;
     await writeFile2(join2(framesDir, `${count}.png`), png);
     count++;
   }
+  await rm2(rawDir, { recursive: true, force: true }).catch(() => {
+  });
   const anchors = [];
   for (let k = 0; k < scene.steps.length; k++) {
     const idx = session.frames.findIndex((f) => (f.stepIndex ?? 0) >= k);

package/package.json

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