clipwise 0.5.1 → 0.6.0

package/dist/index.js

@@ -105,12 +105,13 @@ var ClipwiseRecorder = class {
    *  each input field's text on a separate line. */
   keystrokeSessionId = 0;
   currentStepIndex = 0;
+  isScrolling = false;
   cursorPosition = { x: 0, y: 0 };
   viewport = { width: 1280, height: 800 };
   deviceScaleFactor = 1;
   isCapturing = false;
   targetFps = 30;
-  cursorSpeed = "fast";
+  cursorSpeed = "normal";
   firstContentTimestamp = 0;
   pendingResponsePromises = /* @__PURE__ */ new Map();
   // ── 중복 프레임 제거 (Phase 1-A) ──────────────────────────────────────────
@@ -143,6 +144,7 @@ var ClipwiseRecorder = class {
     this.keystrokeTimeline = [];
     this.keystrokeSessionId = 0;
     this.currentStepIndex = 0;
+    this.isScrolling = false;
     this.cursorPosition = { x: 0, y: 0 };
     this.isCapturing = false;
     this.firstContentTimestamp = 0;
@@ -172,11 +174,12 @@ var ClipwiseRecorder = class {
         } else {
           this.lastFrameSignature = Buffer.from(signature);
           const captureTime = Date.now();
-          this.rawFrames.push({ buffer, timestamp: captureTime, stepIndex: this.currentStepIndex });
+          const rawFrame = { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex, isScrolling: this.isScrolling };
+          this.rawFrames.push(rawFrame);
           this.dedupStats.stored++;
           if (this.frameChannel && this.firstContentTimestamp > 0) {
             const frame = this.buildFrameOnline(
-              { buffer, timestamp: captureTime, stepIndex: this.currentStepIndex },
+              rawFrame,
               this.channelIndex++
             );
             this.frameChannel.push(frame);
@@ -381,7 +384,8 @@ var ClipwiseRecorder = class {
       viewport: { ...this.viewport },
       deviceScaleFactor: this.deviceScaleFactor,
       stepIndex: raw.stepIndex,
-      keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0
+      keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
+      isScrolling: raw.isScrolling || void 0
     };
   }
   /**
@@ -517,6 +521,7 @@ var ClipwiseRecorder = class {
       case "scroll": {
         const scrollTarget = action.selector ? await getElementCenter(this.page, action.selector, action.timeout) : null;
         const scrollDistance = Math.abs(action.y) + Math.abs(action.x);
+        this.isScrolling = true;
         if (action.smooth && scrollDistance > 0) {
           const scrollSteps = Math.max(12, Math.round(scrollDistance / 25));
           const yStep = action.y / scrollSteps;
@@ -556,6 +561,7 @@ var ClipwiseRecorder = class {
             timestamp: Date.now()
           });
         }
+        this.isScrolling = false;
         await this.waitWithRepaints(120);
         break;
       }
@@ -721,8 +727,9 @@ var ClipwiseRecorder = class {
         viewport: { ...this.viewport },
         deviceScaleFactor: this.deviceScaleFactor,
         keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
-        stepIndex: raw.stepIndex
+        stepIndex: raw.stepIndex,
         // use per-frame step index captured at event time
+        isScrolling: raw.isScrolling || void 0
       };
     });
   }
@@ -1573,7 +1580,8 @@ async function composeFrame(frame, effects, output, context) {
   }
   const scale = ctx.zoomScale;
   if (effects.zoom.enabled && scale > 1) {
-    const rawFocus = frame.clickPosition ?? frame.cursorPosition ?? { x: frame.viewport.width / 2, y: frame.viewport.height / 2 };
+    const followCursor = effects.zoom.autoZoom.followCursor;
+    const rawFocus = followCursor ? frame.cursorPosition ?? frame.clickPosition ?? { x: frame.viewport.width / 2, y: frame.viewport.height / 2 } : frame.clickPosition ?? frame.cursorPosition ?? { x: frame.viewport.width / 2, y: frame.viewport.height / 2 };
     const offset = getFrameOffset(effects.deviceFrame, dpr);
     const focusPoint = {
       x: rawFocus.x * dpr + offset.left,
@@ -1641,37 +1649,170 @@ async function composeFrame(frame, effects, output, context) {
 
 // src/effects/transition.ts
 import sharp8 from "sharp";
+async function decodeToRaw(buf, rawInfo, targetWidth, targetHeight) {
+  const src = rawInfo ? sharp8(buf, { raw: { width: rawInfo.width, height: rawInfo.height, channels: rawInfo.channels } }) : sharp8(buf);
+  const pipeline = targetWidth && targetHeight ? src.resize(targetWidth, targetHeight, { fit: "fill" }).ensureAlpha().raw() : src.ensureAlpha().raw();
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+  return { data: Buffer.from(data), width: info.width, height: info.height };
+}
+function returnRaw(buf, rawInfo, w, h) {
+  if (rawInfo) return { buffer: buf, rawInfo };
+  return null;
+}
 async function applyCrossfade(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
   const t = Math.max(0, Math.min(1, progress));
   if (t <= 0) {
-    const rawInfo = fromRawInfo ?? { width, height, channels: 4 };
-    if (fromRawInfo) return { buffer: fromBuffer, rawInfo };
-    const { data, info } = await sharp8(fromBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-    return { buffer: Buffer.from(data), rawInfo: { width: info.width, height: info.height, channels: 4 } };
+    const fast = returnRaw(fromBuffer, fromRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(fromBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
   }
   if (t >= 1) {
-    const rawInfo = toRawInfo ?? { width, height, channels: 4 };
-    if (toRawInfo) return { buffer: toBuffer, rawInfo };
-    const { data, info } = await sharp8(toBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-    return { buffer: Buffer.from(data), rawInfo: { width: info.width, height: info.height, channels: 4 } };
+    const fast = returnRaw(toBuffer, toRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(toBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  const from = await decodeToRaw(fromBuffer, fromRawInfo);
+  const to = await decodeToRaw(toBuffer, toRawInfo, from.width, from.height);
+  const pixels = Buffer.alloc(from.data.length);
+  for (let i = 0; i < from.data.length; i++) {
+    pixels[i] = Math.round(from.data[i] * (1 - t) + to.data[i] * t);
+  }
+  return { buffer: pixels, rawInfo: { width: from.width, height: from.height, channels: 4 } };
+}
+async function applySlide(fromBuffer, toBuffer, progress, width, height, direction, fromRawInfo, toRawInfo) {
+  const t = Math.max(0, Math.min(1, progress));
+  if (t <= 0) {
+    const fast = returnRaw(fromBuffer, fromRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(fromBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  if (t >= 1) {
+    const fast = returnRaw(toBuffer, toRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(toBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  const from = await decodeToRaw(fromBuffer, fromRawInfo);
+  const to = await decodeToRaw(toBuffer, toRawInfo, from.width, from.height);
+  const w = from.width;
+  const h = from.height;
+  const pixels = Buffer.alloc(from.data.length);
+  const eased = easeInOutCubic3(t);
+  if (direction === "left") {
+    const offsetX = Math.round(w * (1 - eased));
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const dstIdx = (y * w + x) * 4;
+        const srcX = x + offsetX;
+        if (srcX < w) {
+          const srcIdx = (y * w + srcX) * 4;
+          pixels[dstIdx] = to.data[srcIdx];
+          pixels[dstIdx + 1] = to.data[srcIdx + 1];
+          pixels[dstIdx + 2] = to.data[srcIdx + 2];
+          pixels[dstIdx + 3] = to.data[srcIdx + 3];
+        } else {
+          const fromX = srcX - w;
+          if (fromX < w) {
+            const srcIdx = (y * w + fromX) * 4;
+            pixels[dstIdx] = from.data[srcIdx];
+            pixels[dstIdx + 1] = from.data[srcIdx + 1];
+            pixels[dstIdx + 2] = from.data[srcIdx + 2];
+            pixels[dstIdx + 3] = from.data[srcIdx + 3];
+          }
+        }
+      }
+    }
+  } else {
+    const offsetY = Math.round(h * (1 - eased));
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const dstIdx = (y * w + x) * 4;
+        const srcY = y + offsetY;
+        if (srcY < h) {
+          const srcIdx = (srcY * w + x) * 4;
+          pixels[dstIdx] = to.data[srcIdx];
+          pixels[dstIdx + 1] = to.data[srcIdx + 1];
+          pixels[dstIdx + 2] = to.data[srcIdx + 2];
+          pixels[dstIdx + 3] = to.data[srcIdx + 3];
+        } else {
+          const fromY = srcY - h;
+          if (fromY < h) {
+            const srcIdx = (fromY * w + x) * 4;
+            pixels[dstIdx] = from.data[srcIdx];
+            pixels[dstIdx + 1] = from.data[srcIdx + 1];
+            pixels[dstIdx + 2] = from.data[srcIdx + 2];
+            pixels[dstIdx + 3] = from.data[srcIdx + 3];
+          }
+        }
+      }
+    }
+  }
+  return { buffer: pixels, rawInfo: { width: w, height: h, channels: 4 } };
+}
+async function applyBlur(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
+  const t = Math.max(0, Math.min(1, progress));
+  if (t <= 0) {
+    const fast = returnRaw(fromBuffer, fromRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(fromBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
   }
+  if (t >= 1) {
+    const fast = returnRaw(toBuffer, toRawInfo, width, height);
+    if (fast) return fast;
+    const d = await decodeToRaw(toBuffer, void 0);
+    return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+  const sigma = t * 20;
   const fromSrc = fromRawInfo ? sharp8(fromBuffer, { raw: { width: fromRawInfo.width, height: fromRawInfo.height, channels: fromRawInfo.channels } }) : sharp8(fromBuffer);
-  const fromRaw = await fromSrc.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-  const toSrc = toRawInfo ? sharp8(toBuffer, { raw: { width: toRawInfo.width, height: toRawInfo.height, channels: toRawInfo.channels } }) : sharp8(toBuffer);
-  const toRaw = await toSrc.resize(fromRaw.info.width, fromRaw.info.height, { fit: "fill" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-  const pixels = Buffer.alloc(fromRaw.data.length);
-  for (let i = 0; i < fromRaw.data.length; i++) {
-    pixels[i] = Math.round(
-      fromRaw.data[i] * (1 - t) + toRaw.data[i] * t
-    );
+  const blurredFrom = await fromSrc.blur(Math.max(0.3, sigma)).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const to = await decodeToRaw(toBuffer, toRawInfo, blurredFrom.info.width, blurredFrom.info.height);
+  const pixels = Buffer.alloc(blurredFrom.data.length);
+  for (let i = 0; i < blurredFrom.data.length; i++) {
+    pixels[i] = Math.round(blurredFrom.data[i] * (1 - t) + to.data[i] * t);
   }
   return {
     buffer: pixels,
-    rawInfo: { width: fromRaw.info.width, height: fromRaw.info.height, channels: 4 }
+    rawInfo: { width: blurredFrom.info.width, height: blurredFrom.info.height, channels: 4 }
   };
 }
+async function applyTransition(type, fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo) {
+  switch (type) {
+    case "fade":
+      return applyCrossfade(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo);
+    case "slide-left":
+      return applySlide(fromBuffer, toBuffer, progress, width, height, "left", fromRawInfo, toRawInfo);
+    case "slide-up":
+      return applySlide(fromBuffer, toBuffer, progress, width, height, "up", fromRawInfo, toRawInfo);
+    case "blur":
+      return applyBlur(fromBuffer, toBuffer, progress, width, height, fromRawInfo, toRawInfo);
+    case "none":
+    default:
+      const d = await decodeToRaw(toBuffer, toRawInfo);
+      return { buffer: d.data, rawInfo: { width: d.width, height: d.height, channels: 4 } };
+  }
+}
+function easeInOutCubic3(t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
 
 // src/compose/canvas-renderer.ts
+function mergeStepEffects(global, stepIndex, steps) {
+  if (stepIndex === void 0 || !steps[stepIndex]?.effects) return global;
+  const override = steps[stepIndex].effects;
+  return {
+    zoom: override.zoom ? { ...global.zoom, ...override.zoom } : global.zoom,
+    cursor: override.cursor ? { ...global.cursor, ...override.cursor } : global.cursor,
+    background: override.background ? { ...global.background, ...override.background } : global.background,
+    deviceFrame: override.deviceFrame ? { ...global.deviceFrame, ...override.deviceFrame } : global.deviceFrame,
+    speedRamp: override.speedRamp ? { ...global.speedRamp, ...override.speedRamp } : global.speedRamp,
+    keystroke: override.keystroke ? { ...global.keystroke, ...override.keystroke } : global.keystroke,
+    watermark: override.watermark ? { ...global.watermark, ...override.watermark } : global.watermark
+  };
+}
 var MIN_FRAMES_PER_WORKER = 4;
 var cachedWorkerUrl = null;
 function getWorkerUrl() {
@@ -1727,14 +1868,17 @@ var CanvasRenderer = class {
     const cpuCount = os.cpus().length;
     const workerCount = Math.min(cpuCount, 8);
     const useWorkers = workerCount >= 2 && processFrames.length >= workerCount * MIN_FRAMES_PER_WORKER;
+    const perFrameEffects = processFrames.map(
+      (f) => mergeStepEffects(this.effects, f.stepIndex, this.steps)
+    );
     let composed;
     if (useWorkers) {
-      composed = await this.processWithWorkers(processFrames, contexts, workerCount);
+      composed = await this.processWithWorkers(processFrames, contexts, workerCount, perFrameEffects);
     } else {
       composed = [];
       for (let i = 0; i < processFrames.length; i++) {
         composed.push(
-          await composeFrame(processFrames[i], this.effects, this.output, contexts[i])
+          await composeFrame(processFrames[i], perFrameEffects[i], this.output, contexts[i])
         );
       }
     }
@@ -1747,7 +1891,7 @@ var CanvasRenderer = class {
    * Distribute frame composition across a pool of worker threads.
    * Workers process frames concurrently; results are collected in order.
    */
-  processWithWorkers(frames, contexts, workerCount) {
+  processWithWorkers(frames, contexts, workerCount, perFrameEffects) {
     return new Promise((resolve, reject) => {
       const results = new Array(frames.length);
       let completed = 0;
@@ -1761,7 +1905,7 @@ var CanvasRenderer = class {
         worker.postMessage({
           taskId: i,
           frame: frames[i],
-          effects: this.effects,
+          effects: perFrameEffects ? perFrameEffects[i] : this.effects,
           output: this.output,
           context: contexts[i]
         });
@@ -1824,6 +1968,9 @@ var CanvasRenderer = class {
           effectiveScale,
           transitionFrames
         );
+        if (frame.isScrolling && zoomScale > 1) {
+          zoomScale = 1;
+        }
       }
       const clickProgress = frame.clickPosition != null ? frame.clickProgress ?? 0.5 : null;
       const trailLength = this.effects.cursor.trailLength;
@@ -1898,7 +2045,7 @@ var CanvasRenderer = class {
    * using the same applyTransitionsToStream() logic as composeStream().
    */
   async *composeStreamOnline(source) {
-    const hasFadeTransitions = this.steps.some((s) => s.transition === "fade");
+    const hasFadeTransitions = this.steps.some((s) => s.transition !== "none");
     if (!hasFadeTransitions) {
       const cpuCount = os.cpus().length;
       const workerCount = Math.min(cpuCount, 8);
@@ -1954,6 +2101,9 @@ var CanvasRenderer = class {
           effectiveScale,
           transitionFrames
         );
+        if (frame.isScrolling && zoomScale > 1) {
+          zoomScale = 1;
+        }
       }
       const clickProgress = frame.clickPosition != null ? frame.clickProgress ?? 0.5 : null;
       const trail = [];
@@ -1965,10 +2115,11 @@ var CanvasRenderer = class {
     const dispatch = (worker) => {
       if (canDispatch(nextToDispatch)) {
         const i = nextToDispatch++;
+        const frameEffects = mergeStepEffects(this.effects, frames[i].stepIndex, this.steps);
         worker.postMessage({
           taskId: i,
           frame: frames[i],
-          effects: this.effects,
+          effects: frameEffects,
           output: this.output,
           context: computeContext(i)
         });
@@ -2078,13 +2229,16 @@ var CanvasRenderer = class {
     const workerUrl = getWorkerUrl();
     const workers = [];
     let nextToDispatch = 0;
+    const perFrameEffects = frames.map(
+      (f) => mergeStepEffects(this.effects, f.stepIndex, this.steps)
+    );
     const dispatch = (worker) => {
       if (nextToDispatch >= frames.length || workerError) return;
       const i = nextToDispatch++;
       worker.postMessage({
         taskId: i,
         frame: frames[i],
-        effects: this.effects,
+        effects: perFrameEffects[i],
         output: this.output,
         context: contexts[i]
       });
@@ -2135,7 +2289,8 @@ var CanvasRenderer = class {
    */
   async *streamSequential(frames, contexts) {
     for (let i = 0; i < frames.length; i++) {
-      yield await composeFrame(frames[i], this.effects, this.output, contexts[i]);
+      const frameEffects = mergeStepEffects(this.effects, frames[i].stepIndex, this.steps);
+      yield await composeFrame(frames[i], frameEffects, this.output, contexts[i]);
     }
   }
   /**
@@ -2150,11 +2305,11 @@ var CanvasRenderer = class {
       if (frames[i].stepIndex !== void 0 && frames[i - 1].stepIndex !== void 0 && frames[i].stepIndex !== frames[i - 1].stepIndex) {
         const stepIdx = frames[i].stepIndex;
         const step = this.steps[stepIdx];
-        if (step && step.transition === "fade") {
+        if (step && step.transition !== "none") {
           const startIdx = Math.max(0, i - Math.floor(transitionFrames / 2));
           const endIdx = Math.min(frames.length - 1, i + Math.ceil(transitionFrames / 2));
           if (endIdx - startIdx >= 2) {
-            windows.push({ startIdx, endIdx });
+            windows.push({ startIdx, endIdx, type: step.transition });
           }
         }
       }
@@ -2201,10 +2356,12 @@ var CanvasRenderer = class {
           const fromBuf = state.frames[0].buffer;
           const toBuf = state.frames[state.frames.length - 1].buffer;
           const range = state.frames.length - 1;
+          const transType = win.type;
           const fromRawInfo = state.frames[0].rawInfo;
           const toRawInfo = state.frames[state.frames.length - 1].rawInfo;
           for (let j = 1; j < state.frames.length - 1; j++) {
-            const blended = await applyCrossfade(
+            const blended = await applyTransition(
+              transType,
               fromBuf,
               toBuf,
               j / range,
@@ -2246,8 +2403,8 @@ var CanvasRenderer = class {
       if (frames[i].stepIndex !== void 0 && frames[i - 1].stepIndex !== void 0 && frames[i].stepIndex !== frames[i - 1].stepIndex) {
         const stepIdx = frames[i].stepIndex;
         const step = this.steps[stepIdx];
-        if (step && step.transition === "fade") {
-          boundaries.push({ index: i, stepIndex: stepIdx });
+        if (step && step.transition !== "none") {
+          boundaries.push({ index: i, stepIndex: stepIdx, type: step.transition });
         }
       }
     }
@@ -2262,7 +2419,8 @@ var CanvasRenderer = class {
       const toRawInfo = composed[endIdx].rawInfo;
       for (let i = startIdx + 1; i < endIdx; i++) {
         const progress = (i - startIdx) / range;
-        const blended = await applyCrossfade(
+        const blended = await applyTransition(
+          boundary.type,
           fromBuffer,
           toBuffer,
           progress,
@@ -2339,7 +2497,7 @@ async function encodeGif(frames, config) {
   gif.finish();
   return Buffer.from(gif.bytes());
 }
-async function encodeMp4(frames, config) {
+async function encodeMp4(frames, config, audio) {
   if (frames.length === 0) {
     throw new Error("Cannot encode MP4: no frames provided");
   }
@@ -2347,14 +2505,14 @@ async function encodeMp4(frames, config) {
   try {
     const encoder = await detectVideoEncoder();
     const params = resolveEncodingParams(config);
-    await pipeFramesToFfmpeg(frames, config, params, encoder, outputPath);
+    await pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, audio);
     return await readFile(outputPath);
   } finally {
     await rm(outputPath, { force: true }).catch(() => {
     });
   }
 }
-async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath) {
+async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, audio) {
   const videoArgs = encoder === "hevc_videotoolbox" ? [
     "-c:v",
     "hevc_videotoolbox",
@@ -2388,6 +2546,14 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath) {
     "-pix_fmt",
     "yuv420p"
   ];
+  const audioInputArgs = audio ? ["-i", audio.file] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"];
+  const audioFilters = [];
+  if (audio) {
+    if (audio.volume !== 1) audioFilters.push(`volume=${audio.volume}`);
+    if (audio.fadeIn > 0) audioFilters.push(`afade=t=in:d=${audio.fadeIn / 1e3}`);
+    if (audio.fadeOut > 0) audioFilters.push(`afade=t=out:st=999999:d=${audio.fadeOut / 1e3}`);
+  }
+  const audioFilterArgs = audioFilters.length > 0 ? ["-af", audioFilters.join(",")] : [];
   return new Promise((resolve, reject) => {
     const ffmpeg = spawn(
       "ffmpeg",
@@ -2404,16 +2570,14 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath) {
         String(config.fps),
         "-i",
         "pipe:0",
-        // Silent audio track for platform compatibility
-        "-f",
-        "lavfi",
-        "-i",
-        "anullsrc=r=48000:cl=stereo",
+        // Audio input
+        ...audioInputArgs,
         ...videoArgs,
         "-c:a",
         "aac",
         "-b:a",
         "128k",
+        ...audioFilterArgs,
         "-shortest",
         "-movflags",
         "+faststart",
@@ -2458,19 +2622,19 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath) {
     })().catch(reject);
   });
 }
-async function encodeMp4Stream(frames, config) {
+async function encodeMp4Stream(frames, config, audio) {
   const outputPath = join(tmpdir(), `clipwise-${Date.now()}-${Math.random().toString(36).slice(2)}.mp4`);
   try {
     const encoder = await detectVideoEncoder();
     const params = resolveEncodingParams(config);
-    await pipeStreamToFfmpeg(frames, config, params, encoder, outputPath);
+    await pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, audio);
     return await readFile(outputPath);
   } finally {
     await rm(outputPath, { force: true }).catch(() => {
     });
   }
 }
-async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
+async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, audio) {
   const videoArgs = encoder === "hevc_videotoolbox" ? [
     "-c:v",
     "hevc_videotoolbox",
@@ -2503,6 +2667,14 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
     "-pix_fmt",
     "yuv420p"
   ];
+  const audioInputArgs = audio ? ["-i", audio.file] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"];
+  const audioFilters = [];
+  if (audio) {
+    if (audio.volume !== 1) audioFilters.push(`volume=${audio.volume}`);
+    if (audio.fadeIn > 0) audioFilters.push(`afade=t=in:d=${audio.fadeIn / 1e3}`);
+    if (audio.fadeOut > 0) audioFilters.push(`afade=t=out:st=999999:d=${audio.fadeOut / 1e3}`);
+  }
+  const audioFilterArgs = audioFilters.length > 0 ? ["-af", audioFilters.join(",")] : [];
   return new Promise((resolve, reject) => {
     const ffmpeg = spawn(
       "ffmpeg",
@@ -2518,15 +2690,13 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath) {
         String(config.fps),
         "-i",
         "pipe:0",
-        "-f",
-        "lavfi",
-        "-i",
-        "anullsrc=r=48000:cl=stereo",
+        ...audioInputArgs,
         ...videoArgs,
         "-c:a",
         "aac",
         "-b:a",
         "128k",
+        ...audioFilterArgs,
         "-shortest",
         "-movflags",
         "+faststart",
@@ -2615,7 +2785,8 @@ var ConcurrentSession = class extends EventEmitter {
           yield frame;
         }
       })(),
-      this.scenario.output
+      this.scenario.output,
+      this.scenario.audio
     );
     const session = await handle.done;
     this.emit("progress", { composed, total: composed, pct: 100 });
@@ -2655,7 +2826,8 @@ var StreamingSession = class extends EventEmitter {
           yield frame;
         }
       })(),
-      scenario.output
+      scenario.output,
+      scenario.audio
     );
   }
 };
@@ -2770,15 +2942,16 @@ var ZoomEffectSchema = z.object({
   enabled: z.boolean().default(true),
   /**
    * Numeric zoom scale (1.0 = no zoom).  Overridden by `intensity` when set.
-   * Default lowered from 1.8 → 1.35 to match "moderate" intensity.
+   * Default: 1.25 to match "light" intensity (industry standard).
    */
-  scale: z.number().min(1).max(5).default(1.35),
+  scale: z.number().min(1).max(5).default(1.25),
   /**
    * Intensity preset — overrides `scale` when set.
    * Calibrated against Loom (light≈1.25x) and Camtasia (moderate≈1.35x).
+   * Default: "light" (1.25x) — matches industry standard (Screen Studio, Loom).
    */
-  intensity: ZoomIntensitySchema.optional(),
-  duration: z.number().default(600),
+  intensity: ZoomIntensitySchema.default("light"),
+  duration: z.number().default(800),
   easing: z.enum(["ease-in-out", "ease-in", "ease-out", "linear"]).default("ease-in-out"),
   autoZoom: AutoZoomConfigSchema.default({})
 });
@@ -2786,7 +2959,7 @@ var CursorEffectSchema = z.object({
   enabled: z.boolean().default(true),
   size: z.number().default(20),
   color: z.string().default("#000000"),
-  speed: z.enum(["fast", "normal", "slow"]).default("fast"),
+  speed: z.enum(["fast", "normal", "slow"]).default("normal"),
   smoothing: z.boolean().default(true),
   clickEffect: z.boolean().default(true),
   clickColor: z.string().default("rgba(59, 130, 246, 0.3)"),
@@ -2812,7 +2985,7 @@ var DeviceFrameSchema = z.object({
 });
 var SpeedRampConfigSchema = z.object({
   enabled: z.boolean().default(false),
-  idleSpeed: z.number().min(0.5).max(8).default(3),
+  idleSpeed: z.number().min(0.5).max(8).default(2),
   actionSpeed: z.number().min(0.25).max(2).default(0.8),
   transitionFrames: z.number().default(15)
 });
@@ -2854,10 +3027,11 @@ var EffectsConfigSchema = z.object({
   watermark: WatermarkConfigSchema.default({})
 });
 var OutputConfigSchema = z.object({
-  format: z.enum(["gif", "mp4", "webm", "png-sequence"]).default("gif"),
+  format: z.enum(["gif", "mp4", "webm", "png-sequence"]).default("mp4"),
   width: z.number().default(1280),
   height: z.number().default(800),
   fps: z.number().min(1).max(60).default(30),
+  /** @deprecated Use `preset` instead. Will be removed in v0.7. */
   quality: z.number().min(1).max(100).default(80),
   // Encoding preset for MP4 output. Overrides quality when set.
   // social   — optimized for Twitter/X and YouTube (CRF 25, capped bitrate)
@@ -2867,12 +3041,40 @@ var OutputConfigSchema = z.object({
   outputDir: z.string().default("./output"),
   filename: z.string().default("clipwise-recording")
 });
+var StepEffectsOverrideSchema = z.object({
+  zoom: ZoomEffectSchema.partial().optional(),
+  cursor: CursorEffectSchema.partial().optional(),
+  background: BackgroundSchema.partial().optional(),
+  deviceFrame: DeviceFrameSchema.partial().optional(),
+  speedRamp: SpeedRampConfigSchema.partial().optional(),
+  keystroke: KeystrokeConfigSchema.partial().optional(),
+  watermark: WatermarkConfigSchema.partial().optional()
+}).optional();
+var TransitionTypeSchema = z.enum([
+  "none",
+  "fade",
+  "slide-left",
+  "slide-up",
+  "blur"
+]);
 var StepSchema = z.object({
   name: z.string().optional(),
   actions: z.array(StepActionSchema),
   captureDelay: z.number().default(300),
   holdDuration: z.number().default(1500),
-  transition: z.enum(["fade", "none"]).default("none")
+  transition: TransitionTypeSchema.default("none"),
+  /** Per-step effects override — merges with global effects config. */
+  effects: StepEffectsOverrideSchema
+});
+var AudioConfigSchema = z.object({
+  /** Path to the audio file (MP3, WAV, AAC, etc.). */
+  file: z.string().min(1),
+  /** Volume level (0.0 = silent, 1.0 = full). */
+  volume: z.number().min(0).max(1).default(1),
+  /** Fade-in duration in milliseconds. */
+  fadeIn: z.number().min(0).default(0),
+  /** Fade-out duration in milliseconds. */
+  fadeOut: z.number().min(0).default(0)
 });
 var ScenarioSchema = z.object({
   name: z.string(),
@@ -2883,6 +3085,8 @@ var ScenarioSchema = z.object({
   }).default({}),
   effects: EffectsConfigSchema.default({}),
   output: OutputConfigSchema.default({}),
+  /** Optional audio narration — muxed into MP4 output. */
+  audio: AudioConfigSchema.optional(),
   steps: z.array(StepSchema).min(1)
 });
 
@@ -3000,7 +3204,10 @@ export {
   ConcurrentSession,
   StreamingSession,
   ZOOM_INTENSITY_SCALES,
+  applyBlur,
   applyCrossfade,
+  applySlide,
+  applyTransition,
   buildZoomClickLookup,
   calculateAdaptiveZoom,
   calculateAdaptiveZoomFromLookup,