autokap 1.0.8 → 1.1.0

package/dist/clip-frame-recorder.js

@@ -0,0 +1,305 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { postProcessClipFrames } from './clip-postprocess.js';
+import { resolvePhysicalCaptureSize } from './clip-scale.js';
+import { logger } from './logger.js';
+const DEFAULT_CLIP_SOURCE_FPS = 30;
+const DEFAULT_CLIP_OUTPUT_FPS = 30;
+const INTERMEDIATE_FRAME_FORMAT = 'jpeg';
+const INTERMEDIATE_FRAME_QUALITY = 80;
+const MAX_PENDING_FRAME_WRITES = 4;
+export function buildCdpViewportClip(viewport, effectiveScale, scrollOffset) {
+    return {
+        x: Math.max(0, scrollOffset.x),
+        y: Math.max(0, scrollOffset.y),
+        width: Math.max(1, Math.round(viewport.width)),
+        height: Math.max(1, Math.round(viewport.height)),
+        scale: Math.max(0.1, effectiveScale),
+    };
+}
+export class FrameSequenceClipRecorder {
+    page;
+    options;
+    sourceFps;
+    outputFps;
+    workingDirPromise;
+    startedAt = Date.now();
+    frames = [];
+    stopRequested = false;
+    loopPromise = null;
+    finalResult = null;
+    frameDimensions = null;
+    lastCaptureError = null;
+    pendingWrites = new Set();
+    pendingWriteError = null;
+    cdpSession = null;
+    cdpSessionPromise = null;
+    cdpCaptureDisabled = false;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+        this.sourceFps = Math.max(1, Math.round(options.sourceFps ?? DEFAULT_CLIP_SOURCE_FPS));
+        this.outputFps = Math.max(1, Math.round(options.outputFps ?? DEFAULT_CLIP_OUTPUT_FPS));
+        this.workingDirPromise = options.baseDir
+            ? Promise.resolve(options.baseDir)
+            : fs.mkdtemp(path.join(os.tmpdir(), 'autokap-clip-frames-'));
+        this.frameDimensions = resolvePhysicalCaptureSize(options.viewport, options.effectiveScale)
+            ?? {
+                width: Math.max(2, Math.round(options.viewport.width)) & ~1,
+                height: Math.max(2, Math.round(options.viewport.height)) & ~1,
+            };
+    }
+    async start() {
+        const workingDir = await this.workingDirPromise;
+        await fs.mkdir(path.join(workingDir, 'frames'), { recursive: true });
+        await this.captureFrame(Date.now(), false);
+        this.loopPromise = this.runCaptureLoop();
+    }
+    async stop() {
+        if (this.finalResult) {
+            return this.finalResult;
+        }
+        this.stopRequested = true;
+        await this.loopPromise;
+        const stopAt = Date.now();
+        await this.captureFrame(stopAt, true);
+        await this.flushPendingWrites();
+        if (this.frames.length === 0) {
+            throw this.lastCaptureError ?? new Error('clip capture failed before any frame could be recorded');
+        }
+        if (this.pendingWriteError) {
+            throw this.pendingWriteError;
+        }
+        const workingDir = await this.workingDirPromise;
+        const outputDimensions = this.frameDimensions
+            ?? resolvePhysicalCaptureSize(this.options.viewport, this.options.effectiveScale)
+            ?? this.options.viewport;
+        const frameEntries = buildFrameEntries(this.frames, stopAt, this.sourceFps, this.outputFps);
+        const actualSourceFps = resolveActualSourceFps(this.frames, stopAt);
+        try {
+            const result = await postProcessClipFrames(frameEntries, workingDir, 'clip', {
+                ...this.options.clipOptions,
+                mp4Width: outputDimensions.width,
+                mp4Height: outputDimensions.height,
+            });
+            if (!result.mp4Path || !result.thumbnailPath) {
+                throw new Error('clip packaging failed: missing MP4 or thumbnail output');
+            }
+            const [mp4Buffer, gifBuffer, thumbnailBuffer] = await Promise.all([
+                fs.readFile(result.mp4Path),
+                result.gifPath ? fs.readFile(result.gifPath) : Promise.resolve(null),
+                fs.readFile(result.thumbnailPath),
+            ]);
+            const clipPackage = {
+                mp4: {
+                    buffer: mp4Buffer,
+                    mimeType: 'video/mp4',
+                },
+                ...(gifBuffer
+                    ? {
+                        gif: {
+                            buffer: gifBuffer,
+                            mimeType: 'image/gif',
+                        },
+                    }
+                    : {}),
+                thumbnail: {
+                    buffer: thumbnailBuffer,
+                    mimeType: 'image/png',
+                },
+                captureMethod: 'frame_sequence',
+                requestedScale: this.options.requestedScale,
+                effectiveScale: this.options.effectiveScale,
+                sourceFps: this.sourceFps,
+                actualSourceFps,
+                outputFps: this.outputFps,
+                frameCount: this.frames.length,
+                dimensions: outputDimensions,
+            };
+            this.finalResult = {
+                buffer: mp4Buffer,
+                mimeType: 'video/mp4',
+                durationMs: result.durationMs,
+                trimStartMs: 0,
+                clipPackage,
+            };
+            return this.finalResult;
+        }
+        finally {
+            await this.cdpSession?.detach().catch(() => undefined);
+            await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    async abort() {
+        this.stopRequested = true;
+        await this.loopPromise?.catch(() => undefined);
+        await this.cdpSession?.detach().catch(() => undefined);
+        const workingDir = await this.workingDirPromise;
+        await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    async runCaptureLoop() {
+        const frameIntervalMs = Math.max(1, Math.round(1000 / this.sourceFps));
+        let nextCaptureAt = this.startedAt + frameIntervalMs;
+        while (!this.stopRequested) {
+            const waitMs = nextCaptureAt - Date.now();
+            if (waitMs > 0) {
+                await sleep(waitMs);
+            }
+            if (this.stopRequested) {
+                return;
+            }
+            await this.captureFrame(Date.now(), true);
+            nextCaptureAt += frameIntervalMs;
+        }
+    }
+    async captureFrame(capturedAt, allowFailure) {
+        try {
+            const workingDir = await this.workingDirPromise;
+            const frameIndex = this.frames.length;
+            const framePath = path.join(workingDir, 'frames', `frame-${String(frameIndex).padStart(6, '0')}.jpg`);
+            const frameBuffer = await this.captureFrameBuffer();
+            await this.queueFrameWrite(framePath, frameBuffer);
+            this.frames.push({ path: framePath, capturedAt });
+        }
+        catch (error) {
+            const captureError = error instanceof Error ? error : new Error(String(error));
+            this.lastCaptureError = captureError;
+            if (!allowFailure) {
+                throw captureError;
+            }
+            logger.debug(`[clip] frame capture skipped: ${captureError.message}`);
+        }
+    }
+    async captureFrameBuffer() {
+        const scrollOffset = await this.readScrollOffset();
+        const cdpBuffer = await this.captureFrameViaCdp(scrollOffset);
+        if (cdpBuffer) {
+            return cdpBuffer;
+        }
+        return this.page.screenshot({
+            type: INTERMEDIATE_FRAME_FORMAT,
+            quality: INTERMEDIATE_FRAME_QUALITY,
+            fullPage: false,
+            scale: 'device',
+        });
+    }
+    async readScrollOffset() {
+        try {
+            return await this.page.evaluate(() => ({
+                x: window.scrollX || window.pageXOffset || 0,
+                y: window.scrollY || window.pageYOffset || 0,
+            }));
+        }
+        catch {
+            return { x: 0, y: 0 };
+        }
+    }
+    async captureFrameViaCdp(scrollOffset) {
+        const session = await this.getCdpSession();
+        if (!session) {
+            return null;
+        }
+        try {
+            const screenshot = await session.send('Page.captureScreenshot', {
+                format: INTERMEDIATE_FRAME_FORMAT,
+                quality: INTERMEDIATE_FRAME_QUALITY,
+                optimizeForSpeed: true,
+                clip: buildCdpViewportClip(this.options.viewport, this.options.effectiveScale, scrollOffset),
+            });
+            return Buffer.from(screenshot.data, 'base64');
+        }
+        catch (error) {
+            this.disableCdpCapture(error);
+            return null;
+        }
+    }
+    async getCdpSession() {
+        if (this.cdpCaptureDisabled) {
+            return null;
+        }
+        if (this.cdpSession) {
+            return this.cdpSession;
+        }
+        if (!this.cdpSessionPromise) {
+            this.cdpSessionPromise = (async () => {
+                try {
+                    const context = this.page.context();
+                    if (typeof context.newCDPSession !== 'function') {
+                        this.cdpCaptureDisabled = true;
+                        return null;
+                    }
+                    this.cdpSession = await context.newCDPSession(this.page);
+                    return this.cdpSession;
+                }
+                catch (error) {
+                    this.disableCdpCapture(error);
+                    return null;
+                }
+            })();
+        }
+        return this.cdpSessionPromise;
+    }
+    disableCdpCapture(error) {
+        if (!this.cdpCaptureDisabled) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.debug(`[clip] CDP frame capture unavailable, falling back to Playwright screenshot: ${message}`);
+        }
+        this.cdpCaptureDisabled = true;
+        this.cdpSessionPromise = Promise.resolve(null);
+    }
+    async queueFrameWrite(framePath, frameBuffer) {
+        await this.waitForPendingWriteCapacity();
+        if (this.pendingWriteError) {
+            throw this.pendingWriteError;
+        }
+        let writePromise;
+        writePromise = fs.writeFile(framePath, frameBuffer)
+            .catch((error) => {
+            this.pendingWriteError = error instanceof Error ? error : new Error(String(error));
+            throw this.pendingWriteError;
+        })
+            .finally(() => {
+            this.pendingWrites.delete(writePromise);
+        });
+        this.pendingWrites.add(writePromise);
+    }
+    async waitForPendingWriteCapacity() {
+        while (this.pendingWrites.size >= MAX_PENDING_FRAME_WRITES) {
+            await Promise.race(this.pendingWrites);
+            if (this.pendingWriteError) {
+                throw this.pendingWriteError;
+            }
+        }
+    }
+    async flushPendingWrites() {
+        while (this.pendingWrites.size > 0) {
+            await Promise.allSettled(Array.from(this.pendingWrites));
+        }
+    }
+}
+function buildFrameEntries(frames, stopAt, sourceFps, outputFps) {
+    const entries = [];
+    const minFrameDurationMs = Math.max(1, Math.min(Math.round(1000 / sourceFps), Math.round(1000 / outputFps)));
+    for (let index = 0; index < frames.length; index += 1) {
+        const frame = frames[index];
+        const nextTimestamp = frames[index + 1]?.capturedAt ?? stopAt;
+        entries.push({
+            path: frame.path,
+            durationMs: Math.max(minFrameDurationMs, nextTimestamp - frame.capturedAt),
+        });
+    }
+    return entries;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveActualSourceFps(frames, stopAt) {
+    if (frames.length <= 1) {
+        return frames.length;
+    }
+    const firstTimestamp = frames[0].capturedAt;
+    const durationSec = Math.max(0.001, (stopAt - firstTimestamp) / 1000);
+    return Math.round((frames.length / durationSec) * 100) / 100;
+}
+//# sourceMappingURL=clip-frame-recorder.js.map

package/dist/clip-postprocess.d.ts

@@ -15,11 +15,40 @@ export declare function convertToGif(webmPath: string, outputPath: string, opts?
 /**
  * Convert a WebM recording to an MP4 with web-optimized settings.
  */
-export declare function convertToMp4(webmPath: string, outputPath: string): Promise<void>;
+export declare function convertToMp4(webmPath: string, outputPath: string, opts?: {
+    width?: number;
+    height?: number;
+    trimStartSec?: number;
+    maxDurationSec?: number;
+    holdLastFrameSec?: number;
+    fps?: number;
+}): Promise<void>;
 /**
  * Extract the first frame of a WebM as a PNG thumbnail.
  */
 export declare function extractThumbnail(webmPath: string, outputPath: string): Promise<void>;
+/**
+ * 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 declare function assembleMp4FromFrames(opts: {
+    framesDir: string;
+    outputPath: string;
+    fps: number;
+    frameOffsetsMs?: number[];
+}): Promise<void>;
 /**
  * Trim a recording: skip dead frames at the start and cap duration.
  */
@@ -37,6 +66,6 @@ export interface ClipPostProcessResult {
 }
 /**
  * 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 declare function postProcessClipRecording(webmPath: string, outputDir: string, clipId: string, options?: ClipOptions): Promise<ClipPostProcessResult>;

package/dist/clip-postprocess.js

@@ -1,13 +1,14 @@
 import { execFile } from 'node:child_process';
-import { rm, 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 ────────────────────────────────────────────────
 const cachedBinaryPaths = {};
 async function ensureBinaryAvailable(binaryName) {
@@ -48,44 +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);
-            await rm(palettePath, { force: true });
-        }
-        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',
@@ -103,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.
  */
@@ -148,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 rm(trimmedPath, { force: true });
-    }
-    catch { /* ignore */ }
-    if (sourcePath !== trimmedPath) {
-        try {
-            await rm(sourcePath, { force: true });
-        }
-        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>;