@t3lnet/sceneforge 1.0.28 → 1.0.30

package/cli/commands/record-demo.js

@@ -182,8 +182,6 @@ export async function runRecordDemoCommand(argv) {
   const hqVideo = hasFlag(args, "--hq-video");
   const hqFormat = getFlagValue(args, "--hq-format") ?? "jpeg";
   const hqQuality = parseInt(getFlagValue(args, "--hq-quality") ?? "100", 10);
-  const hqFpsArg = getFlagValue(args, "--hq-fps");
-  const hqFps = hqFpsArg ? parseInt(hqFpsArg, 10) : undefined; // undefined = use actual capture rate
 
   if (!baseUrl) {
     console.error("[error] --base-url is required");
@@ -308,7 +306,7 @@ export async function runRecordDemoCommand(argv) {
     const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
     try {
       if (!demoError && result?.success) {
-        await cdpRecorder.assembleVideo(finalVideoPath, hqFps ? { fps: hqFps } : {});
+        await cdpRecorder.assembleVideo(finalVideoPath);
         console.log(`[record] High-quality video saved: ${finalVideoPath}`);
         if (result.scriptPath) {
           // Use the actual first frame time for alignment, not when we started the recorder

package/cli/utils/cdp-recorder.js

@@ -206,46 +206,64 @@ export function createCDPRecorder(page, options) {
 
     /**
      * Assemble captured frames into a video using FFmpeg
+     * Uses timestamp-aware assembly to preserve real-time playback timing
      *
      * @param {string} outputPath - Output video path
-     * @param {Object} [assembleOptions] - Assembly options
-     * @param {number} [assembleOptions.fps] - Output framerate (auto-detected if not specified)
      * @returns {Promise<string>} - Path to assembled video
      */
-    async assembleVideo(outputPath, assembleOptions = {}) {
-      const { fps: fpsOverride } = assembleOptions;
+    async assembleVideo(outputPath) {
 
       if (frameTimestamps.length === 0) {
         throw new Error("No frames captured - cannot assemble video");
       }
 
-      // Calculate actual capture FPS for real-time playback
-      // This ensures video duration matches the actual recording duration
-      const calculatedFps = frameTimestamps.length > 0 && recordingDuration > 0
-        ? frameTimestamps.length / (recordingDuration / 1000)
-        : 30;
+      // Sort frames by timestamp to ensure correct order
+      const sortedFrames = [...frameTimestamps].sort((a, b) => a.timestamp - b.timestamp);
+
+      // Calculate duration for each frame based on gap to next frame
+      // This preserves real-time playback - waits stay as waits, actions stay as actions
+      const framesWithDuration = sortedFrames.map((frame, index) => {
+        let duration;
+        if (index < sortedFrames.length - 1) {
+          // Duration is the gap to the next frame
+          duration = sortedFrames[index + 1].timestamp - frame.timestamp;
+        } else {
+          // Last frame - use average duration or minimum display time
+          const avgDuration = sortedFrames.length > 1
+            ? (sortedFrames[sortedFrames.length - 1].timestamp - sortedFrames[0].timestamp) / (sortedFrames.length - 1)
+            : 1 / 30;
+          duration = Math.max(avgDuration, 1 / 30);
+        }
+        // Clamp duration to reasonable bounds (min 1ms, max 10 seconds per frame)
+        duration = Math.max(0.001, Math.min(duration, 10));
+        return { ...frame, duration };
+      });
 
-      // Use provided fps override or actual capture fps for real-time playback
-      const fps = fpsOverride || calculatedFps;
+      // Calculate total video duration from timestamps
+      const totalDuration = framesWithDuration.reduce((sum, f) => sum + f.duration, 0);
+      console.log(`[cdp-recorder] Assembling ${sortedFrames.length} frames with timestamp-aware timing`);
+      console.log(`[cdp-recorder] Expected video duration: ${totalDuration.toFixed(2)}s (real-time preserved)`);
 
-      if (fpsOverride && Math.abs(fpsOverride - calculatedFps) > 1) {
-        console.log(`[cdp-recorder] Note: Using ${fps} fps (actual capture rate was ${calculatedFps.toFixed(1)} fps)`);
-        console.log(`[cdp-recorder] This will ${fpsOverride > calculatedFps ? 'speed up' : 'slow down'} playback`);
-      }
+      // Generate FFmpeg concat demuxer file
+      // This tells FFmpeg exactly how long to display each frame
+      const concatFilePath = path.join(framesDir, "concat.txt");
+      const concatContent = framesWithDuration
+        .map((frame) => `file '${path.basename(frame.path)}'\nduration ${frame.duration.toFixed(6)}`)
+        .join("\n");
 
-      console.log(`[cdp-recorder] Assembling video at ${fps.toFixed(1)} fps`);
+      // Add the last frame again without duration (FFmpeg concat demuxer requirement)
+      const lastFrame = framesWithDuration[framesWithDuration.length - 1];
+      const finalConcatContent = concatContent + `\nfile '${path.basename(lastFrame.path)}'`;
 
-      const frameExtension = format === "png" ? "png" : "jpg";
-      const framePattern = path.join(framesDir, `frame_%08d.${frameExtension}`);
+      await fs.writeFile(concatFilePath, finalConcatContent);
 
       // Determine encoding based on output format
-      // WebM requires VP8/VP9/AV1, MP4 can use H.264
       const outputExtension = path.extname(outputPath).toLowerCase();
       const isWebM = outputExtension === ".webm";
 
       let encodingArgs;
       if (isWebM) {
-        // Use VP9 with lossless mode for WebM
+        // Use VP9 with high quality for WebM
         encodingArgs = [
           "-c:v", "libvpx-vp9",
           "-lossless", "1",  // Lossless mode
@@ -257,15 +275,15 @@ export function createCDPRecorder(page, options) {
         encodingArgs = getIntermediateEncodingArgs({ includeAudio: false });
       }
 
+      // Use concat demuxer for timestamp-aware assembly
       await runFFmpeg([
         "-y",
-        "-framerate",
-        String(fps),
-        "-i",
-        framePattern,
+        "-f", "concat",
+        "-safe", "0",
+        "-i", concatFilePath,
         ...encodingArgs,
-        "-pix_fmt",
-        isWebM ? "yuv420p" : "yuv420p",
+        "-pix_fmt", "yuv420p",
+        "-fps_mode", "vfr",       // Variable framerate to preserve timing
         outputPath,
       ]);
 
@@ -295,9 +313,7 @@ export function getCDPRecordingHelpText() {
   return `
 High-Quality Recording Options:
   --hq-video              Use CDP-based high-quality recording instead of Playwright
-                          Captures frames at maximum quality and assembles with FFmpeg
+                          Captures frames with timestamps and assembles with real-time timing
   --hq-format <format>    Frame format: jpeg (default) or png (lossless, larger files)
-  --hq-quality <1-100>    JPEG quality (default: 100, ignored for PNG)
-  --hq-fps <fps>          Output framerate (default: actual capture rate for real-time)
-                          Override only if you want to change playback speed`;
+  --hq-quality <1-100>    JPEG quality (default: 100, ignored for PNG)`;
 }

package/context/templates/base/cli-reference.md

@@ -466,7 +466,6 @@ The CDP-based recorder captures frames directly from Chrome DevTools Protocol an
 --hq-video              # Enable CDP-based high-quality recording
 --hq-format <format>    # Frame format: jpeg (default) or png
 --hq-quality <1-100>    # JPEG quality (default: 100, ignored for PNG)
---hq-fps <fps>          # Override output framerate (default: actual capture rate for real-time)
 ```
 
 ### Frame Formats
@@ -478,9 +477,9 @@ The CDP-based recorder captures frames directly from Chrome DevTools Protocol an
 
 ### How It Works
 
-1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method
+1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method with timestamps
 2. **Frame Storage**: Saves frames as JPEG (quality 100) or lossless PNG
-3. **Video Assembly**: FFmpeg assembles frames with lossless intermediate encoding
+3. **Timestamp-Aware Assembly**: FFmpeg assembles frames using per-frame durations to preserve real-time playback (waits stay as waits, actions stay as actions)
 4. **Final Output**: Quality settings applied at concat step
 
 ### Examples

package/dist/templates/base/cli-reference.md

@@ -466,7 +466,6 @@ The CDP-based recorder captures frames directly from Chrome DevTools Protocol an
 --hq-video              # Enable CDP-based high-quality recording
 --hq-format <format>    # Frame format: jpeg (default) or png
 --hq-quality <1-100>    # JPEG quality (default: 100, ignored for PNG)
---hq-fps <fps>          # Override output framerate (default: actual capture rate for real-time)
 ```
 
 ### Frame Formats
@@ -478,9 +477,9 @@ The CDP-based recorder captures frames directly from Chrome DevTools Protocol an
 
 ### How It Works
 
-1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method
+1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method with timestamps
 2. **Frame Storage**: Saves frames as JPEG (quality 100) or lossless PNG
-3. **Video Assembly**: FFmpeg assembles frames with lossless intermediate encoding
+3. **Timestamp-Aware Assembly**: FFmpeg assembles frames using per-frame durations to preserve real-time playback (waits stay as waits, actions stay as actions)
 4. **Final Output**: Quality settings applied at concat step
 
 ### Examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3lnet/sceneforge",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "SceneForge runner and generation utilities for YAML-driven demos",
   "license": "MIT",
   "author": "T3LNET",