@t3lnet/sceneforge 1.0.23 → 1.0.25

package/cli/commands/pipeline.js

@@ -5,6 +5,7 @@ import { getFlagValue, hasFlag } from "../utils/args.js";
 import { ensureDir, getOutputPaths, resolveRoot, toAbsolute } from "../utils/paths.js";
 import { getQualityHelpText } from "../utils/quality.js";
 import { getViewportHelpText, getOutputDimensionsHelpText } from "../utils/dimensions.js";
+import { getCDPRecordingHelpText } from "../utils/cdp-recorder.js";
 import { runRecordDemoCommand } from "./record-demo.js";
 import { runSplitVideoCommand } from "./split-video.js";
 import { runGenerateVoiceoverCommand } from "./generate-voiceover.js";
@@ -45,6 +46,7 @@ Media options (for final video):
 ${getQualityHelpText()}
 ${getViewportHelpText()}
 ${getOutputDimensionsHelpText()}
+${getCDPRecordingHelpText()}
 
   --help, -h             Show this help message
 

package/cli/commands/record-demo.js

@@ -19,6 +19,7 @@ import {
   parseViewportArgs,
   getViewportHelpText,
 } from "../utils/dimensions.js";
+import { createCDPRecorder, getCDPRecordingHelpText } from "../utils/cdp-recorder.js";
 
 function printHelp() {
   console.log(`
@@ -44,6 +45,7 @@ Options:
   --no-video              Skip video recording
   --help, -h              Show this help message
 ${getViewportHelpText()}
+${getCDPRecordingHelpText()}
 
 Examples:
   sceneforge record --definition demo-definitions/create-quote.yaml --base-url http://localhost:5173
@@ -177,6 +179,9 @@ export async function runRecordDemoCommand(argv) {
   const headed = hasFlag(args, "--headed");
   const slowMo = getFlagValue(args, "--slowmo");
   const noVideo = hasFlag(args, "--no-video");
+  const hqVideo = hasFlag(args, "--hq-video");
+  const hqFormat = getFlagValue(args, "--hq-format") ?? "jpeg";
+  const hqQuality = parseInt(getFlagValue(args, "--hq-quality") ?? "100", 10);
 
   if (!baseUrl) {
     console.error("[error] --base-url is required");
@@ -216,7 +221,8 @@ export async function runRecordDemoCommand(argv) {
   console.log(`[record] Viewport: ${viewport.width}x${viewport.height}`);
 
   const recordDir = path.join(outputPaths.videosDir, ".recordings", definition.name);
-  if (!noVideo) {
+  const framesDir = path.join(outputPaths.videosDir, ".frames", definition.name);
+  if (!noVideo && !hqVideo) {
     await ensureDir(recordDir);
   }
 
@@ -225,9 +231,12 @@ export async function runRecordDemoCommand(argv) {
     slowMo: slowMo ? Number(slowMo) : undefined,
   });
 
+  // When using HQ video, don't use Playwright's built-in recording
+  const usePlaywrightRecording = !noVideo && !hqVideo;
+
   const context = await browser.newContext({
     viewport,
-    recordVideo: noVideo ? undefined : { dir: recordDir, size: viewport },
+    recordVideo: usePlaywrightRecording ? { dir: recordDir, size: viewport } : undefined,
     storageState: storageState ? toAbsolute(rootDir, storageState) : undefined,
     locale: locale || undefined,
     extraHTTPHeaders: locale
@@ -238,41 +247,88 @@ export async function runRecordDemoCommand(argv) {
   });
 
   const page = await context.newPage();
-  const video = page.video();
+  const video = usePlaywrightRecording ? page.video() : null;
   const videoRecordingStartTime = Date.now();
-  const startUrl = resolveStartUrl(startPath, baseUrl);
 
-  if (startUrl) {
-    await page.goto(startUrl, { waitUntil: "networkidle" });
+  // Set up CDP recorder for high-quality video
+  let cdpRecorder = null;
+  if (hqVideo && !noVideo) {
+    cdpRecorder = createCDPRecorder(page, {
+      framesDir,
+      format: hqFormat,
+      quality: hqQuality,
+      maxWidth: viewport.width,
+      maxHeight: viewport.height,
+    });
+    await cdpRecorder.start();
   }
-  const result = await runDemo(
-    definition,
-    {
-      page,
-      baseURL: baseUrl,
-      outputDir: outputPaths.outputDir,
-      assetBaseDir: assetRoot ? toAbsolute(rootDir, assetRoot) : undefined,
-      videoRecordingStartTime,
-    },
-    {
-      generateScripts: true,
-      scriptOutputDir: path.join(outputPaths.outputDir, "scripts"),
+
+  const startUrl = resolveStartUrl(startPath, baseUrl);
+
+  let result;
+  let demoError = null;
+
+  try {
+    if (startUrl) {
+      await page.goto(startUrl, { waitUntil: "networkidle" });
     }
-  );
+    result = await runDemo(
+      definition,
+      {
+        page,
+        baseURL: baseUrl,
+        outputDir: outputPaths.outputDir,
+        assetBaseDir: assetRoot ? toAbsolute(rootDir, assetRoot) : undefined,
+        videoRecordingStartTime,
+      },
+      {
+        generateScripts: true,
+        scriptOutputDir: path.join(outputPaths.outputDir, "scripts"),
+      }
+    );
+  } catch (err) {
+    demoError = err;
+  }
+
+  // Stop CDP recorder before closing context
+  if (cdpRecorder) {
+    await cdpRecorder.stop();
+  }
 
   await context.close();
   await browser.close();
 
-  if (video) {
+  // Handle video based on recording method
+  if (cdpRecorder) {
+    const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
+    try {
+      if (!demoError && result?.success) {
+        await cdpRecorder.assembleVideo(finalVideoPath);
+        console.log(`[record] High-quality video saved: ${finalVideoPath}`);
+        if (result.scriptPath) {
+          await alignScriptToVideo(result.scriptPath, finalVideoPath, videoRecordingStartTime);
+        }
+      }
+    } finally {
+      // Always cleanup frames
+      await cdpRecorder.cleanup();
+      console.log(`[record] Cleaned up temporary frames from: ${framesDir}`);
+    }
+  } else if (video) {
     const recordedPath = await video.path();
     const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
     await moveVideo(recordedPath, finalVideoPath);
     console.log(`[record] Video saved: ${finalVideoPath}`);
-    if (result.scriptPath) {
+    if (result?.scriptPath) {
       await alignScriptToVideo(result.scriptPath, finalVideoPath, videoRecordingStartTime);
     }
   }
 
+  // Re-throw demo error after cleanup
+  if (demoError) {
+    throw demoError;
+  }
+
   if (result.success) {
     console.log(`[record] ✓ Completed ${definition.name}`);
     if (result.scriptPath) {

package/cli/utils/cdp-recorder.js

@@ -0,0 +1,263 @@
+/**
+ * CDP-based high-quality screen recorder
+ *
+ * Uses Chrome DevTools Protocol screencast API to capture high-quality frames,
+ * then assembles them into a video using FFmpeg. This bypasses Playwright's
+ * hardcoded low-quality video settings.
+ *
+ * Benefits over Playwright's built-in recording:
+ * - Configurable quality (PNG lossless or high-quality JPEG)
+ * - No 1Mbps bitrate cap
+ * - Better compression settings via FFmpeg
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+import { runFFmpeg } from "./media.js";
+import { getIntermediateEncodingArgs } from "./quality.js";
+
+/**
+ * @typedef {Object} CDPRecorderOptions
+ * @property {string} framesDir - Directory to store captured frames
+ * @property {number} [quality=100] - JPEG quality (1-100), 100 = best quality
+ * @property {string} [format='jpeg'] - Frame format: 'jpeg' or 'png'
+ * @property {number} [maxWidth] - Max frame width (undefined = viewport width)
+ * @property {number} [maxHeight] - Max frame height (undefined = viewport height)
+ * @property {number} [everyNthFrame=1] - Capture every Nth frame (1 = all frames)
+ */
+
+/**
+ * @typedef {Object} CDPRecorder
+ * @property {Function} start - Start recording
+ * @property {Function} stop - Stop recording and return frame info
+ * @property {Function} assembleVideo - Assemble frames into video
+ */
+
+/**
+ * Create a CDP-based screen recorder for a Playwright page
+ *
+ * @param {import('@playwright/test').Page} page - Playwright page
+ * @param {CDPRecorderOptions} options - Recorder options
+ * @returns {CDPRecorder}
+ */
+export function createCDPRecorder(page, options) {
+  const {
+    framesDir,
+    quality = 100,
+    format = "jpeg",
+    maxWidth,
+    maxHeight,
+    everyNthFrame = 1,
+  } = options;
+
+  let cdpSession = null;
+  let frameCount = 0;
+  let frameTimestamps = [];
+  let isRecording = false;
+  let startTime = null;
+  let writeQueue = Promise.resolve();
+  let nextFrameNumber = 0;
+
+  const frameHandler = (params) => {
+    if (!isRecording) return;
+
+    const { data, metadata, sessionId } = params;
+    frameCount += 1;
+
+    // Acknowledge the frame immediately to continue receiving
+    cdpSession.send("Page.screencastFrameAck", { sessionId }).catch(() => {
+      // Session may be closed
+    });
+
+    // Skip frames based on everyNthFrame setting
+    if (everyNthFrame > 1 && frameCount % everyNthFrame !== 0) {
+      return;
+    }
+
+    const timestamp = metadata.timestamp;
+    const frameNumber = nextFrameNumber;
+    nextFrameNumber += 1;
+    const paddedNumber = String(frameNumber).padStart(8, "0");
+    const extension = format === "png" ? "png" : "jpg";
+    const framePath = path.join(framesDir, `frame_${paddedNumber}.${extension}`);
+
+    // Decode base64 frame data
+    const buffer = Buffer.from(data, "base64");
+
+    // Queue frame writes to ensure sequential completion
+    writeQueue = writeQueue.then(async () => {
+      try {
+        await fs.writeFile(framePath, buffer);
+        frameTimestamps.push({
+          frameNumber,
+          timestamp,
+          path: framePath,
+        });
+      } catch (err) {
+        console.warn(`[cdp-recorder] Failed to write frame ${frameNumber}:`, err.message);
+      }
+    });
+  };
+
+  return {
+    /**
+     * Start recording frames via CDP screencast
+     */
+    async start() {
+      await fs.mkdir(framesDir, { recursive: true });
+
+      // Create CDP session for the page
+      cdpSession = await page.context().newCDPSession(page);
+
+      // Set up frame handler
+      cdpSession.on("Page.screencastFrame", frameHandler);
+
+      // Start screencast with high quality settings
+      // format: 'jpeg' or 'png'
+      // quality: 0-100 for jpeg (100 = best), ignored for png
+      // maxWidth/maxHeight: optional frame dimensions
+      // everyNthFrame: capture frequency (1 = every frame)
+      await cdpSession.send("Page.startScreencast", {
+        format,
+        quality,
+        maxWidth,
+        maxHeight,
+        everyNthFrame,
+      });
+
+      isRecording = true;
+      startTime = Date.now();
+      frameCount = 0;
+      frameTimestamps = [];
+
+      console.log("[cdp-recorder] Started high-quality screen capture");
+    },
+
+    /**
+     * Stop recording and return frame information
+     * @returns {Promise<{frameCount: number, duration: number, framesDir: string}>}
+     */
+    async stop() {
+      if (!isRecording || !cdpSession) {
+        return { frameCount: 0, duration: 0, framesDir };
+      }
+
+      isRecording = false;
+      const duration = Date.now() - startTime;
+
+      try {
+        await cdpSession.send("Page.stopScreencast");
+        cdpSession.off("Page.screencastFrame", frameHandler);
+        await cdpSession.detach();
+      } catch {
+        // Session may already be closed
+      }
+
+      // Wait for all pending frame writes to complete
+      await writeQueue;
+
+      console.log(
+        `[cdp-recorder] Captured ${frameTimestamps.length} frames in ${(duration / 1000).toFixed(2)}s`
+      );
+
+      return {
+        frameCount: frameTimestamps.length,
+        duration,
+        framesDir,
+        frameTimestamps,
+      };
+    },
+
+    /**
+     * Assemble captured frames into a video using FFmpeg
+     *
+     * @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;
+
+      if (frameTimestamps.length === 0) {
+        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
+
+      console.log(`[cdp-recorder] Assembling video at ${fps} fps`);
+
+      const frameExtension = format === "png" ? "png" : "jpg";
+      const framePattern = path.join(framesDir, `frame_%08d.${frameExtension}`);
+
+      // 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
+        encodingArgs = [
+          "-c:v", "libvpx-vp9",
+          "-lossless", "1",  // Lossless mode
+          "-row-mt", "1",    // Enable row-based multithreading
+          "-an",             // No audio for now
+        ];
+      } else {
+        // Use H.264 lossless for MP4
+        encodingArgs = getIntermediateEncodingArgs({ includeAudio: false });
+      }
+
+      await runFFmpeg([
+        "-y",
+        "-framerate",
+        String(fps),
+        "-i",
+        framePattern,
+        ...encodingArgs,
+        "-pix_fmt",
+        isWebM ? "yuv420p" : "yuv420p",
+        outputPath,
+      ]);
+
+      console.log(`[cdp-recorder] Video assembled: ${outputPath}`);
+
+      return outputPath;
+    },
+
+    /**
+     * Clean up frame files
+     */
+    async cleanup() {
+      try {
+        await fs.rm(framesDir, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    },
+  };
+}
+
+/**
+ * Get help text for CDP recording options
+ * @returns {string}
+ */
+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
+  --hq-format <format>    Frame format: jpeg (default) or png (lossless, larger files)
+  --hq-quality <1-100>    JPEG quality (default: 100, ignored for PNG)`;
+}

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

@@ -28,6 +28,9 @@ sceneforge record --definition <path> [options]
 | `--viewport` | Target video resolution (preset or WxH, default: 1440x900) |
 | `--width` | Video width (overrides --viewport) |
 | `--height` | Video height (overrides --viewport) |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png (lossless) |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
@@ -47,6 +50,12 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
 
 # Record at 4K resolution
 sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 4k
+
+# High-quality CDP recording (bypasses Playwright's bitrate limits)
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# HQ recording with lossless PNG frames
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
 ```
 
 ### setup
@@ -96,6 +105,9 @@ sceneforge pipeline --definition <path> [options]
 | `--output-size` | Final output dimensions (preset or WxH) |
 | `--output-width` | Output width (-1 for auto) |
 | `--output-height` | Output height (-1 for auto) |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Examples:**
 ```bash
@@ -434,3 +446,72 @@ sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
   --output-size 1080p \
   --quality high
 ```
+
+## High-Quality Recording (CDP)
+
+SceneForge offers an alternative high-quality recording mode that bypasses Playwright's built-in video recording limitations.
+
+### Why Use HQ Recording?
+
+Playwright's built-in video recording uses hardcoded FFmpeg settings optimized for debugging rather than production quality:
+- **1Mbps bitrate cap** - Severely limits quality at higher resolutions
+- **Speed 8 encoding** - Prioritizes speed over quality
+- **Realtime deadline** - No time for quality optimization
+
+The CDP-based recorder captures frames directly from Chrome DevTools Protocol and assembles them with FFmpeg using our quality settings.
+
+### CLI Flags (record, pipeline)
+
+```bash
+--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)
+```
+
+### Frame Formats
+
+| Format | Quality | File Size | Use Case |
+|--------|---------|-----------|----------|
+| `jpeg` | Very high (at quality 100) | Smaller | Default, good for most cases |
+| `png` | Lossless | Larger | Maximum quality, longer recordings |
+
+### How It Works
+
+1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method
+2. **Frame Storage**: Saves frames as JPEG (quality 100) or lossless PNG
+3. **Video Assembly**: FFmpeg assembles frames with lossless intermediate encoding
+4. **Final Output**: Quality settings applied at concat step
+
+### Examples
+
+```bash
+# High-quality recording with default settings
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# Lossless PNG frames for maximum quality
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
+
+# Full pipeline with HQ recording
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --hq-video --quality high
+
+# HQ recording at 4K
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --hq-video \
+  --viewport 4k \
+  --output-size 1080p \
+  --quality high
+```
+
+### Trade-offs
+
+| Aspect | Standard Recording | HQ Recording |
+|--------|-------------------|--------------|
+| Quality | Limited by 1Mbps cap | Full quality frames |
+| Speed | Faster | Slower (frame-by-frame) |
+| Disk Usage | Moderate | Higher (temporary frames) |
+| Compatibility | Always works | Requires FFmpeg |
+
+### When to Use
+
+- **Use HQ Recording** when final video quality is critical
+- **Use Standard Recording** for quick drafts, debugging, or when disk space is limited

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

@@ -28,6 +28,9 @@ sceneforge record --definition <path> [options]
 | `--viewport` | Target video resolution (preset or WxH, default: 1440x900) |
 | `--width` | Video width (overrides --viewport) |
 | `--height` | Video height (overrides --viewport) |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png (lossless) |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
@@ -47,6 +50,12 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
 
 # Record at 4K resolution
 sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 4k
+
+# High-quality CDP recording (bypasses Playwright's bitrate limits)
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# HQ recording with lossless PNG frames
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
 ```
 
 ### setup
@@ -96,6 +105,9 @@ sceneforge pipeline --definition <path> [options]
 | `--output-size` | Final output dimensions (preset or WxH) |
 | `--output-width` | Output width (-1 for auto) |
 | `--output-height` | Output height (-1 for auto) |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Examples:**
 ```bash
@@ -434,3 +446,72 @@ sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
   --output-size 1080p \
   --quality high
 ```
+
+## High-Quality Recording (CDP)
+
+SceneForge offers an alternative high-quality recording mode that bypasses Playwright's built-in video recording limitations.
+
+### Why Use HQ Recording?
+
+Playwright's built-in video recording uses hardcoded FFmpeg settings optimized for debugging rather than production quality:
+- **1Mbps bitrate cap** - Severely limits quality at higher resolutions
+- **Speed 8 encoding** - Prioritizes speed over quality
+- **Realtime deadline** - No time for quality optimization
+
+The CDP-based recorder captures frames directly from Chrome DevTools Protocol and assembles them with FFmpeg using our quality settings.
+
+### CLI Flags (record, pipeline)
+
+```bash
+--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)
+```
+
+### Frame Formats
+
+| Format | Quality | File Size | Use Case |
+|--------|---------|-----------|----------|
+| `jpeg` | Very high (at quality 100) | Smaller | Default, good for most cases |
+| `png` | Lossless | Larger | Maximum quality, longer recordings |
+
+### How It Works
+
+1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method
+2. **Frame Storage**: Saves frames as JPEG (quality 100) or lossless PNG
+3. **Video Assembly**: FFmpeg assembles frames with lossless intermediate encoding
+4. **Final Output**: Quality settings applied at concat step
+
+### Examples
+
+```bash
+# High-quality recording with default settings
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# Lossless PNG frames for maximum quality
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
+
+# Full pipeline with HQ recording
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --hq-video --quality high
+
+# HQ recording at 4K
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --hq-video \
+  --viewport 4k \
+  --output-size 1080p \
+  --quality high
+```
+
+### Trade-offs
+
+| Aspect | Standard Recording | HQ Recording |
+|--------|-------------------|--------------|
+| Quality | Limited by 1Mbps cap | Full quality frames |
+| Speed | Faster | Slower (frame-by-frame) |
+| Disk Usage | Moderate | Higher (temporary frames) |
+| Compatibility | Always works | Requires FFmpeg |
+
+### When to Use
+
+- **Use HQ Recording** when final video quality is critical
+- **Use Standard Recording** for quick drafts, debugging, or when disk space is limited

package/package.json

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