@t3lnet/sceneforge 1.0.26 → 1.0.28

package/cli/commands/record-demo.js

@@ -182,7 +182,8 @@ 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 hqFps = parseInt(getFlagValue(args, "--hq-fps") ?? "30", 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");
@@ -262,6 +263,8 @@ export async function runRecordDemoCommand(argv) {
       maxHeight: viewport.height,
     });
     await cdpRecorder.start();
+    // Wait for first frame to ensure recording is active before demo starts
+    await cdpRecorder.waitForFirstFrame();
   }
 
   const startUrl = resolveStartUrl(startPath, baseUrl);
@@ -292,8 +295,9 @@ export async function runRecordDemoCommand(argv) {
   }
 
   // Stop CDP recorder before closing context
+  let cdpStopInfo = null;
   if (cdpRecorder) {
-    await cdpRecorder.stop();
+    cdpStopInfo = await cdpRecorder.stop();
   }
 
   await context.close();
@@ -304,10 +308,12 @@ export async function runRecordDemoCommand(argv) {
     const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
     try {
       if (!demoError && result?.success) {
-        await cdpRecorder.assembleVideo(finalVideoPath, { fps: hqFps });
+        await cdpRecorder.assembleVideo(finalVideoPath, hqFps ? { fps: hqFps } : {});
         console.log(`[record] High-quality video saved: ${finalVideoPath}`);
         if (result.scriptPath) {
-          await alignScriptToVideo(result.scriptPath, finalVideoPath, videoRecordingStartTime);
+          // Use the actual first frame time for alignment, not when we started the recorder
+          const actualVideoStartTime = cdpStopInfo?.firstFrameTime || videoRecordingStartTime;
+          await alignScriptToVideo(result.scriptPath, finalVideoPath, actualVideoStartTime);
         }
       }
     } finally {

package/cli/utils/cdp-recorder.js

@@ -55,8 +55,10 @@ export function createCDPRecorder(page, options) {
   let frameTimestamps = [];
   let isRecording = false;
   let startTime = null;
+  let firstFrameTime = null; // Wall clock time when first frame was received
   let writeQueue = Promise.resolve();
   let nextFrameNumber = 0;
+  let recordingDuration = 0; // Duration in ms from start to stop
 
   const frameHandler = (params) => {
     if (!isRecording) return;
@@ -64,6 +66,11 @@ export function createCDPRecorder(page, options) {
     const { data, metadata, sessionId } = params;
     frameCount += 1;
 
+    // Track when we receive the first frame (wall clock time)
+    if (firstFrameTime === null) {
+      firstFrameTime = Date.now();
+    }
+
     // Acknowledge the frame immediately to continue receiving
     cdpSession.send("Page.screencastFrameAck", { sessionId }).catch(() => {
       // Session may be closed
@@ -133,6 +140,24 @@ export function createCDPRecorder(page, options) {
       console.log("[cdp-recorder] Started high-quality screen capture");
     },
 
+    /**
+     * Wait for the first frame to be captured.
+     * Call this after start() and before beginning the demo to ensure recording is active.
+     * @param {number} [timeoutMs=5000] - Maximum time to wait for first frame
+     * @returns {Promise<void>}
+     */
+    async waitForFirstFrame(timeoutMs = 5000) {
+      const startWait = Date.now();
+      while (firstFrameTime === null) {
+        if (Date.now() - startWait > timeoutMs) {
+          console.warn("[cdp-recorder] Timeout waiting for first frame - proceeding anyway");
+          return;
+        }
+        await new Promise(resolve => setTimeout(resolve, 50));
+      }
+      console.log(`[cdp-recorder] First frame received after ${Date.now() - startWait}ms`);
+    },
+
     /**
      * Stop recording and return frame information
      * @returns {Promise<{frameCount: number, duration: number, framesDir: string}>}
@@ -143,7 +168,7 @@ export function createCDPRecorder(page, options) {
       }
 
       isRecording = false;
-      const duration = Date.now() - startTime;
+      recordingDuration = Date.now() - startTime;
 
       try {
         await cdpSession.send("Page.stopScreencast");
@@ -156,15 +181,26 @@ export function createCDPRecorder(page, options) {
       // Wait for all pending frame writes to complete
       await writeQueue;
 
+      const delayToFirstFrame = firstFrameTime ? firstFrameTime - startTime : 0;
+      const actualFps = frameTimestamps.length > 0 && recordingDuration > 0
+        ? frameTimestamps.length / (recordingDuration / 1000)
+        : 30;
+
       console.log(
-        `[cdp-recorder] Captured ${frameTimestamps.length} frames in ${(duration / 1000).toFixed(2)}s`
+        `[cdp-recorder] Captured ${frameTimestamps.length} frames in ${(recordingDuration / 1000).toFixed(2)}s (${actualFps.toFixed(1)} fps)`
       );
+      if (delayToFirstFrame > 100) {
+        console.log(`[cdp-recorder] First frame delay: ${delayToFirstFrame}ms`);
+      }
 
       return {
         frameCount: frameTimestamps.length,
-        duration,
+        duration: recordingDuration,
         framesDir,
         frameTimestamps,
+        firstFrameTime, // Wall clock time when first frame was captured
+        startTime,      // Wall clock time when recording was started
+        actualFps,      // Actual capture framerate for real-time playback
       };
     },
 
@@ -183,10 +219,21 @@ export function createCDPRecorder(page, options) {
         throw new Error("No frames captured - cannot assemble video");
       }
 
-      // Use provided fps or default to 30
-      const fps = fpsOverride || 30;
+      // 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;
+
+      // Use provided fps override or actual capture fps for real-time playback
+      const fps = fpsOverride || calculatedFps;
+
+      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`);
+      }
 
-      console.log(`[cdp-recorder] Assembling video at ${fps} fps`);
+      console.log(`[cdp-recorder] Assembling video at ${fps.toFixed(1)} fps`);
 
       const frameExtension = format === "png" ? "png" : "jpg";
       const framePattern = path.join(framesDir, `frame_%08d.${frameExtension}`);
@@ -251,5 +298,6 @@ High-Quality Recording Options:
                           Captures frames at maximum quality and assembles with FFmpeg
   --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: 30)`;
+  --hq-fps <fps>          Output framerate (default: actual capture rate for real-time)
+                          Override only if you want to change playback speed`;
 }

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

@@ -466,6 +466,7 @@ 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

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

@@ -466,6 +466,7 @@ 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

package/package.json

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