autokap 1.0.7 → 1.0.10

package/dist/clip-postprocess.js

@@ -1,32 +1,42 @@
 import { execFile } from 'node:child_process';
-import { stat } from 'node:fs/promises';
+import { copyFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 // ── Default values ──────────────────────────────────────────────────
-const DEFAULT_GIF_FPS = 15;
-const DEFAULT_GIF_MAX_WIDTH = 800;
+const DEFAULT_GIF_FPS = 24;
+const DEFAULT_GIF_MAX_WIDTH = 1440;
 const DEFAULT_MAX_DURATION_SEC = 8;
 const DEFAULT_TRIM_START_SEC = 0.3;
+const DEFAULT_MP4_FPS = 30;
 // ── ffmpeg detection ────────────────────────────────────────────────
-let cachedFfmpegPath = null;
+const cachedBinaryPaths = {};
+async function ensureBinaryAvailable(binaryName) {
+    const cached = cachedBinaryPaths[binaryName];
+    if (cached)
+        return cached;
+    const resolver = process.platform === 'win32' ? 'where' : 'which';
+    const { stdout } = await execFileAsync(resolver, [binaryName]);
+    const resolvedPath = stdout
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(Boolean);
+    if (!resolvedPath) {
+        throw new Error(`${binaryName} not found`);
+    }
+    cachedBinaryPaths[binaryName] = resolvedPath;
+    return resolvedPath;
+}
 /**
  * Resolve the system ffmpeg binary path. Throws if not found.
  */
 export async function ensureFfmpegAvailable() {
-    if (cachedFfmpegPath)
-        return cachedFfmpegPath;
     try {
-        const { stdout } = await execFileAsync('which', ['ffmpeg']);
-        const ffmpegPath = stdout.trim();
-        if (!ffmpegPath)
-            throw new Error('ffmpeg not found');
-        cachedFfmpegPath = ffmpegPath;
-        return ffmpegPath;
+        return await ensureBinaryAvailable('ffmpeg');
     }
     catch {
         throw new Error('ffmpeg is required for clip post-processing but was not found on your system. ' +
-            'Install it via: brew install ffmpeg (macOS) or apt install ffmpeg (Linux).');
+            'Install it via: brew install ffmpeg (macOS), apt install ffmpeg (Linux), or choco install ffmpeg (Windows).');
     }
 }
 // ── Conversion functions ────────────────────────────────────────────
@@ -39,43 +49,103 @@ export async function convertToGif(webmPath, outputPath, opts = {}) {
     const fps = opts.fps ?? DEFAULT_GIF_FPS;
     const maxWidth = opts.maxWidth ?? DEFAULT_GIF_MAX_WIDTH;
     const loopFlag = (opts.loop ?? true) ? '0' : '-1';
-    const paletteDir = path.dirname(outputPath);
-    const palettePath = path.join(paletteDir, `_palette_${Date.now()}.png`);
     const scaleFilter = `fps=${fps},scale=${maxWidth}:-1:flags=lanczos`;
-    // Pass 1: Generate palette
+    // Single-pass GIF generation with per-frame palette (paletteuse=new=1):
+    // each frame gets its own optimal 256-color palette, re-computed from the
+    // pixels in that frame. This is ~3× better visually than a single global
+    // palette for screen recordings where UI state transitions produce very
+    // different color distributions (modal open/close, theme accents, etc.).
+    // sierra2_4a = error-diffusion dither (clean diagonal pattern vs bayer
+    // dots). We intentionally DON'T use diff_mode=rectangle because it leaves
+    // stale-palette pixels in unchanged regions when `new=1` is active.
+    const lavfi = `${scaleFilter},split[a][b];` +
+        `[a]palettegen=stats_mode=single:max_colors=256:reserve_transparent=0[p];` +
+        `[b][p]paletteuse=dither=sierra2_4a:new=1`;
     await execFileAsync(ffmpeg, [
         '-i', webmPath,
-        '-vf', `${scaleFilter},palettegen=stats_mode=diff`,
-        '-y', palettePath,
+        '-lavfi', lavfi,
+        '-loop', loopFlag,
+        '-y', outputPath,
     ]);
-    // Pass 2: Encode GIF with palette
+}
+function resolveVideoDimension(value) {
+    return Number.isFinite(value) ? Math.max(2, Math.round(Number(value))) & ~1 : null;
+}
+function resolveMp4Bitrate(width, height) {
+    const effectiveWidth = width ?? 1440;
+    const effectiveHeight = height ?? 900;
+    const megapixels = Math.max(0.1, effectiveWidth * effectiveHeight / 1e6);
+    const targetMbps = Math.min(40, Math.max(6, Math.round(megapixels * 7)));
+    return {
+        target: `${targetMbps}M`,
+        maxrate: `${targetMbps}M`,
+        bufsize: `${targetMbps * 2}M`,
+    };
+}
+async function probeVideoDimensions(ffprobe, inputPath) {
     try {
-        await execFileAsync(ffmpeg, [
-            '-i', webmPath,
-            '-i', palettePath,
-            '-lavfi', `${scaleFilter}[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=3`,
-            '-loop', loopFlag,
-            '-y', outputPath,
+        const { stdout } = await execFileAsync(ffprobe, [
+            '-v', 'error',
+            '-select_streams', 'v:0',
+            '-show_entries', 'stream=width,height',
+            '-of', 'csv=p=0:s=,',
+            inputPath,
         ]);
+        const [w, h] = stdout.trim().split(',').map(Number);
+        if (!Number.isFinite(w) || !Number.isFinite(h))
+            return null;
+        return { width: w, height: h };
     }
-    finally {
-        // Clean up palette file
-        try {
-            await stat(palettePath).then(() => execFileAsync('rm', [palettePath]));
-        }
-        catch { /* ignore */ }
+    catch {
+        return null;
     }
 }
 /**
  * Convert a WebM recording to an MP4 with web-optimized settings.
  */
-export async function convertToMp4(webmPath, outputPath) {
+export async function convertToMp4(webmPath, outputPath, opts = {}) {
     const ffmpeg = await ensureFfmpegAvailable();
+    const ffprobe = await ensureBinaryAvailable('ffprobe');
+    const width = resolveVideoDimension(opts.width);
+    const height = resolveVideoDimension(opts.height);
+    const fps = Math.max(1, Math.round(opts.fps ?? DEFAULT_MP4_FPS));
+    const trimStartSec = Math.max(0, opts.trimStartSec ?? 0);
+    const maxDurationSec = Math.max(0.1, opts.maxDurationSec ?? DEFAULT_MAX_DURATION_SEC);
+    const holdLastFrameSec = Math.min(Math.max(opts.holdLastFrameSec ?? 0, 0), 10);
+    const outputDurationSec = maxDurationSec + holdLastFrameSec;
+    const filters = [
+        `fps=${fps}`,
+        'setpts=PTS-STARTPTS',
+    ];
+    if (holdLastFrameSec > 0) {
+        filters.push(`tpad=stop_mode=clone:stop_duration=${holdLastFrameSec}`);
+    }
+    if (width && height) {
+        const sourceDims = await probeVideoDimensions(ffprobe, webmPath);
+        const needsScale = !sourceDims
+            || Math.abs(sourceDims.width - width) > 1
+            || Math.abs(sourceDims.height - height) > 1;
+        if (needsScale) {
+            filters.push(`scale=${width}:${height}:flags=lanczos`);
+        }
+    }
+    const bitrate = resolveMp4Bitrate(width, height);
     await execFileAsync(ffmpeg, [
+        ...(trimStartSec > 0 ? ['-ss', String(trimStartSec)] : []),
         '-i', webmPath,
+        '-t', String(outputDurationSec),
+        '-vf', filters.join(','),
         '-c:v', 'libx264',
         '-preset', 'slow',
-        '-crf', '22',
+        '-crf', '16',
+        '-b:v', bitrate.target,
+        '-maxrate', bitrate.maxrate,
+        '-bufsize', bitrate.bufsize,
+        '-g', String(fps * 2),
+        '-keyint_min', String(fps),
+        '-sc_threshold', '0',
+        '-profile:v', 'high',
+        '-tune', 'animation',
         '-pix_fmt', 'yuv420p',
         '-movflags', '+faststart',
         '-an',
@@ -93,6 +163,70 @@ export async function extractThumbnail(webmPath, outputPath) {
         '-y', outputPath,
     ]);
 }
+/**
+ * Assemble a sequence of JPEG frames into an H.264 MP4.
+ * Expects frames named `frame_000000.jpg`, `frame_000001.jpg`, ... in framesDir.
+ *
+ * When `frameOffsetsMs` is provided (one offset per frame, ms from first
+ * frame), uses ffmpeg's concat demuxer to preserve the actual capture timing
+ * (VFR). This matters when the compositor is CPU-bound on heavy React UIs:
+ * frames arrive in bursts during idle periods and gaps during paint-heavy
+ * periods. Encoding those at uniform CFR would stretch bursts and compress
+ * gaps — viewers see temporally-distorted playback even though the average
+ * rate is correct. VFR lets each frame hold the screen for its true wall-
+ * clock duration.
+ *
+ * When `frameOffsetsMs` is absent, falls back to CFR at `fps` (useful for
+ * uniform-cadence captures like the synthetic smoke tests).
+ */
+export async function assembleMp4FromFrames(opts) {
+    const ffmpeg = await ensureFfmpegAvailable();
+    const fps = Number.isFinite(opts.fps) && opts.fps >= 1 ? opts.fps : 25;
+    if (opts.frameOffsetsMs && opts.frameOffsetsMs.length >= 2) {
+        // VFR path: generate a concat file with per-frame durations.
+        const offsets = opts.frameOffsetsMs;
+        const lines = [];
+        for (let i = 0; i < offsets.length; i++) {
+            const durationSec = i < offsets.length - 1
+                ? Math.max(0.001, (offsets[i + 1] - offsets[i]) / 1000)
+                : 1 / fps; // last frame duration = 1 / avg fps
+            lines.push(`file 'frame_${String(i).padStart(6, '0')}.jpg'`);
+            lines.push(`duration ${durationSec.toFixed(6)}`);
+        }
+        // ffmpeg concat demuxer quirk: last `file` entry is needed without a
+        // `duration` directive to close the list correctly.
+        lines.push(`file 'frame_${String(offsets.length - 1).padStart(6, '0')}.jpg'`);
+        const concatPath = path.join(opts.framesDir, 'concat.txt');
+        await (await import('node:fs/promises')).writeFile(concatPath, lines.join('\n'));
+        await execFileAsync(ffmpeg, [
+            '-f', 'concat',
+            '-safe', '0',
+            '-i', concatPath,
+            '-fps_mode', 'vfr',
+            '-c:v', 'libx264',
+            '-preset', 'medium',
+            '-crf', '16',
+            '-pix_fmt', 'yuv420p',
+            '-movflags', '+faststart',
+            '-an',
+            '-y', opts.outputPath,
+        ]);
+        return;
+    }
+    // CFR fallback (uniform framerate).
+    const pattern = path.join(opts.framesDir, 'frame_%06d.jpg');
+    await execFileAsync(ffmpeg, [
+        '-framerate', String(fps),
+        '-i', pattern,
+        '-c:v', 'libx264',
+        '-preset', 'medium',
+        '-crf', '16',
+        '-pix_fmt', 'yuv420p',
+        '-movflags', '+faststart',
+        '-an',
+        '-y', opts.outputPath,
+    ]);
+}
 /**
  * Trim a recording: skip dead frames at the start and cap duration.
  */
@@ -110,8 +244,7 @@ export async function trimRecording(inputPath, outputPath, startSec = DEFAULT_TR
  * Get the duration of a media file in milliseconds.
  */
 export async function getMediaDurationMs(filePath) {
-    const ffmpeg = await ensureFfmpegAvailable();
-    const ffprobe = ffmpeg.replace(/ffmpeg$/, 'ffprobe');
+    const ffprobe = await ensureBinaryAvailable('ffprobe');
     const { stdout } = await execFileAsync(ffprobe, [
         '-v', 'error',
         '-show_entries', 'format=duration',
@@ -139,54 +272,47 @@ async function freezeLastFrame(inputPath, outputPath, durationSec) {
 }
 /**
  * Full post-processing pipeline for a single clip recording:
- * trim → GIF and/or MP4 → thumbnail → measure.
+ * encode a normalized master MP4 → derive GIF + thumbnail → measure.
  */
 export async function postProcessClipRecording(webmPath, outputDir, clipId, options = {}) {
     const maxDuration = options.maxDurationSec ?? DEFAULT_MAX_DURATION_SEC;
-    // Step 1: Trim the recording — cut the setup phase (page load, overlay dismiss)
     const trimStart = options.trimStartSec ?? DEFAULT_TRIM_START_SEC;
-    const trimmedPath = path.join(outputDir, `${clipId}_trimmed.webm`);
-    await trimRecording(webmPath, trimmedPath, trimStart, maxDuration);
-    // Step 1b: Optionally freeze the last frame for a pause before looping
     const holdSec = Math.min(Math.max(options.holdLastFrameSec ?? 0, 0), 10);
-    let sourcePath = trimmedPath;
-    if (holdSec > 0) {
-        const paddedPath = path.join(outputDir, `${clipId}_padded.webm`);
-        await freezeLastFrame(trimmedPath, paddedPath, holdSec);
-        sourcePath = paddedPath;
+    const mp4Path = path.join(outputDir, `${clipId}.mp4`);
+    if (options.skipMp4Encode) {
+        // Source is already an H.264 MP4 produced client-side by ClipCaptureLoop.
+        // Copy it under the canonical name so the downstream GIF/thumbnail steps
+        // get a stable path. Skip re-encode to preserve quality and avoid ~1-2s
+        // of ffmpeg CPU.
+        await copyFile(webmPath, mp4Path);
     }
-    const durationMs = await getMediaDurationMs(sourcePath);
-    const result = { durationMs };
-    // Step 2: Always persist both a GIF and an MP4.
-    // The GIF remains useful for delivery and embeds, while the MP4 is the
-    // high-fidelity source for Studio playback and downstream re-renders.
+    else {
+        await convertToMp4(webmPath, mp4Path, {
+            width: options.mp4Width,
+            height: options.mp4Height,
+            trimStartSec: trimStart,
+            maxDurationSec: maxDuration,
+            holdLastFrameSec: holdSec,
+        });
+    }
+    const durationMs = await getMediaDurationMs(mp4Path);
+    const mp4Stat = await stat(mp4Path);
+    const result = {
+        durationMs,
+        mp4Path,
+        fileSizeBytes: mp4Stat.size,
+    };
     const gifPath = path.join(outputDir, `${clipId}.gif`);
-    await convertToGif(sourcePath, gifPath, {
+    await convertToGif(mp4Path, gifPath, {
         fps: options.gifFps,
         maxWidth: options.gifMaxWidth,
         loop: options.loop,
     });
     result.gifPath = gifPath;
-    const gifStat = await stat(gifPath);
-    result.fileSizeBytes = gifStat.size;
-    const mp4Path = path.join(outputDir, `${clipId}.mp4`);
-    await convertToMp4(sourcePath, mp4Path);
-    result.mp4Path = mp4Path;
     // Step 3: Extract thumbnail
     const thumbnailPath = path.join(outputDir, `${clipId}_thumb.png`);
-    await extractThumbnail(sourcePath, thumbnailPath);
+    await extractThumbnail(mp4Path, thumbnailPath);
     result.thumbnailPath = thumbnailPath;
-    // Clean up intermediate files
-    try {
-        await execFileAsync('rm', [trimmedPath]);
-    }
-    catch { /* ignore */ }
-    if (sourcePath !== trimmedPath) {
-        try {
-            await execFileAsync('rm', [sourcePath]);
-        }
-        catch { /* ignore */ }
-    }
     return result;
 }
 //# sourceMappingURL=clip-postprocess.js.map

package/dist/clip-runtime.d.ts

@@ -0,0 +1,18 @@
+import type { ClipCaptureMethod } from './execution-types.js';
+export declare const CLIP_BACKEND_ENV_VAR = "AUTOKAP_CLIP_BACKEND";
+export declare const CLIP_HEADLESS_POLICY_ENV_VAR = "AUTOKAP_CLIP_HEADLESS_POLICY";
+export type ClipHeadlessPolicy = 'auto' | 'headless' | 'headed';
+export interface ClipRuntimeSelection {
+    requestedMethod: ClipCaptureMethod;
+    captureMethod: ClipCaptureMethod;
+    browserHeaded: boolean;
+    headlessPolicy: ClipHeadlessPolicy;
+    fallbackReason?: string;
+    browserLaunchArgs?: string[];
+}
+export declare function resolveRequestedClipCaptureMethod(): ClipCaptureMethod;
+export declare function resolveClipHeadlessPolicy(): ClipHeadlessPolicy;
+export declare function resolveClipRuntimeSelection(options?: {
+    headed?: boolean;
+    platform?: NodeJS.Platform;
+}): Promise<ClipRuntimeSelection>;

package/dist/clip-runtime.js

@@ -0,0 +1,67 @@
+export const CLIP_BACKEND_ENV_VAR = 'AUTOKAP_CLIP_BACKEND';
+export const CLIP_HEADLESS_POLICY_ENV_VAR = 'AUTOKAP_CLIP_HEADLESS_POLICY';
+const BEGIN_FRAME_LAUNCH_ARGS = [
+    '--enable-begin-frame-control',
+    '--run-all-compositor-stages-before-draw',
+];
+function normalizeClipCaptureMethod(raw) {
+    switch (raw?.trim().toLowerCase()) {
+        case 'begin_frame':
+        case 'frame_sequence':
+        case 'playwright_video':
+            return raw.trim().toLowerCase();
+        default:
+            return null;
+    }
+}
+function normalizeHeadlessPolicy(raw) {
+    switch (raw?.trim().toLowerCase()) {
+        case 'headless':
+            return 'headless';
+        case 'headed':
+            return 'headed';
+        default:
+            return 'auto';
+    }
+}
+export function resolveRequestedClipCaptureMethod() {
+    return normalizeClipCaptureMethod(process.env[CLIP_BACKEND_ENV_VAR]) ?? 'begin_frame';
+}
+export function resolveClipHeadlessPolicy() {
+    return normalizeHeadlessPolicy(process.env[CLIP_HEADLESS_POLICY_ENV_VAR]);
+}
+export async function resolveClipRuntimeSelection(options = {}) {
+    const requestedMethod = resolveRequestedClipCaptureMethod();
+    const headlessPolicy = resolveClipHeadlessPolicy();
+    const platform = options.platform ?? process.platform;
+    const browserHeaded = headlessPolicy === 'headed'
+        ? true
+        : headlessPolicy === 'headless'
+            ? false
+            : options.headed ?? false;
+    let captureMethod = requestedMethod;
+    let fallbackReason;
+    let browserLaunchArgs;
+    if (requestedMethod === 'begin_frame') {
+        if (platform === 'darwin') {
+            captureMethod = 'frame_sequence';
+            fallbackReason = 'begin_frame is unsupported on macOS Chromium targets; falling back to frame sequence capture';
+        }
+        else if (browserHeaded) {
+            captureMethod = 'frame_sequence';
+            fallbackReason = 'begin_frame requires headless Chromium; falling back to frame sequence capture';
+        }
+        else {
+            browserLaunchArgs = [...BEGIN_FRAME_LAUNCH_ARGS];
+        }
+    }
+    return {
+        requestedMethod,
+        captureMethod,
+        browserHeaded,
+        headlessPolicy,
+        fallbackReason,
+        browserLaunchArgs,
+    };
+}
+//# sourceMappingURL=clip-runtime.js.map

package/dist/clip-scale.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_CAPTURE_OUTPUT_SCALE = 2;
+export declare function normalizeCaptureOutputScale(value?: number | null): number | null;
+export declare function resolveEffectiveCaptureOutputScale(requestedScale?: number | null, fallbackScale?: number): number;
+export declare function resolvePhysicalCaptureSize(viewport: {
+    width: number;
+    height: number;
+} | null, scale: number | null | undefined): {
+    width: number;
+    height: number;
+} | null;

package/dist/clip-scale.js

@@ -0,0 +1,21 @@
+export const DEFAULT_CAPTURE_OUTPUT_SCALE = 2;
+export function normalizeCaptureOutputScale(value) {
+    if (!Number.isFinite(value))
+        return null;
+    return Math.max(0.5, Math.min(4, Number(value)));
+}
+export function resolveEffectiveCaptureOutputScale(requestedScale, fallbackScale = DEFAULT_CAPTURE_OUTPUT_SCALE) {
+    return normalizeCaptureOutputScale(requestedScale)
+        ?? normalizeCaptureOutputScale(fallbackScale)
+        ?? DEFAULT_CAPTURE_OUTPUT_SCALE;
+}
+export function resolvePhysicalCaptureSize(viewport, scale) {
+    if (!viewport)
+        return null;
+    const effectiveScale = resolveEffectiveCaptureOutputScale(scale);
+    return {
+        width: Math.max(2, Math.round(viewport.width * effectiveScale)) & ~1,
+        height: Math.max(2, Math.round(viewport.height * effectiveScale)) & ~1,
+    };
+}
+//# sourceMappingURL=clip-scale.js.map

package/dist/clip-screencast-recorder.d.ts

@@ -0,0 +1,42 @@
+import type { Page } from 'playwright';
+import type { RecordingResult } from './execution-types.js';
+import type { ClipOptions } from './types.js';
+export interface CdpScreencastClipRecorderOptions {
+    baseDir?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    requestedScale?: number;
+    effectiveScale: number;
+    clipOptions?: ClipOptions;
+    sourceFps?: number;
+    outputFps?: number;
+}
+export declare class CdpScreencastClipRecorder {
+    private readonly page;
+    private readonly options;
+    private readonly sourceFps;
+    private readonly outputFps;
+    private readonly workingDirPromise;
+    private readonly frames;
+    private readonly startedAt;
+    private finalResult;
+    private frameDimensions;
+    private pendingWriteError;
+    private readonly pendingWrites;
+    private cdpSession;
+    private stopRequested;
+    private started;
+    constructor(page: Page, options: CdpScreencastClipRecorderOptions);
+    start(): Promise<void>;
+    stop(): Promise<RecordingResult>;
+    abort(): Promise<void>;
+    private captureInitialFrame;
+    private handleScreencastFrame;
+    private consumeFrame;
+    private queueFrameWrite;
+    private waitForPendingWriteCapacity;
+    private flushPendingWrites;
+    private cleanup;
+}