@t3lnet/sceneforge 1.0.25 → 1.0.27

package/cli/commands/record-demo.js

@@ -182,6 +182,7 @@ 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);
 
   if (!baseUrl) {
     console.error("[error] --base-url is required");
@@ -291,8 +292,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();
@@ -303,10 +305,12 @@ export async function runRecordDemoCommand(argv) {
     const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
     try {
       if (!demoError && result?.success) {
-        await cdpRecorder.assembleVideo(finalVideoPath);
+        await cdpRecorder.assembleVideo(finalVideoPath, { 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,6 +55,7 @@ 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;
 
@@ -64,6 +65,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
@@ -156,15 +162,21 @@ export function createCDPRecorder(page, options) {
       // Wait for all pending frame writes to complete
       await writeQueue;
 
+      const delayToFirstFrame = firstFrameTime ? firstFrameTime - startTime : 0;
       console.log(
         `[cdp-recorder] Captured ${frameTimestamps.length} frames in ${(duration / 1000).toFixed(2)}s`
       );
+      if (delayToFirstFrame > 100) {
+        console.log(`[cdp-recorder] First frame delay: ${delayToFirstFrame}ms`);
+      }
 
       return {
         frameCount: frameTimestamps.length,
         duration,
         framesDir,
         frameTimestamps,
+        firstFrameTime, // Wall clock time when first frame was captured
+        startTime,      // Wall clock time when recording was started
       };
     },
 
@@ -183,17 +195,8 @@ export function createCDPRecorder(page, options) {
         throw new Error("No frames captured - cannot assemble video");
       }
 
-      // Calculate actual FPS from captured frame timestamps
-      let fps = fpsOverride;
-      if (!fps && frameTimestamps.length > 1) {
-        const firstTimestamp = frameTimestamps[0].timestamp;
-        const lastTimestamp = frameTimestamps[frameTimestamps.length - 1].timestamp;
-        const durationSec = lastTimestamp - firstTimestamp;
-        if (durationSec > 0) {
-          fps = Math.round(frameTimestamps.length / durationSec);
-        }
-      }
-      fps = fps || 30; // Default to 30fps
+      // Use provided fps or default to 30
+      const fps = fpsOverride || 30;
 
       console.log(`[cdp-recorder] Assembling video at ${fps} fps`);
 
@@ -259,5 +262,6 @@ High-Quality Recording Options:
   --hq-video              Use CDP-based high-quality recording instead of Playwright
                           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-quality <1-100>    JPEG quality (default: 100, ignored for PNG)
+  --hq-fps <fps>          Output framerate (default: 30)`;
 }

package/package.json

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