@milkstraw/traceframe 0.5.1 → 0.6.1

package/README.md

@@ -8,13 +8,13 @@ https://github.com/user-attachments/assets/38e02cd5-a9ba-4f3c-938c-159955353141
 
 ## Prerequisites
 
-Traceframe requires Node.js 22+ and system FFmpeg 5+ with `libx264` and `ffprobe` to render the MP4 (for example, `brew install ffmpeg` or `sudo apt install ffmpeg`). Playwright uses its own Chromium and FFmpeg builds to record the page. Install them with the exact Playwright version Traceframe uses; other cached versions are not used:
+Traceframe requires Node.js 22+ and system FFmpeg 5+ with `libx264` and `ffprobe` to render the MP4 (for example, `brew install ffmpeg` or `sudo apt install ffmpeg`). Install Chromium with the exact Playwright version Traceframe uses; other cached versions are not used:
 
 ```sh
-npx playwright@1.64.1 install --only-shell chromium ffmpeg
+npx playwright@1.64.1 install --only-shell chromium
 ```
 
-To use system Chrome 150 or later, pass `--browser` or set `CHROME_PATH`, and install Playwright's recording FFmpeg with `npx playwright@1.64.1 install ffmpeg`. Older Chrome versions can fail to scroll targets inside panels.
+To use system Chrome 150 or later, pass `--browser` or set `CHROME_PATH`. Older Chrome versions can fail to scroll targets inside panels. Recording uses Playwright's frame callback and does not require its separate FFmpeg executable.
 
 In a sandbox, such as a coding agent's, allow Playwright's browser download and let Chromium start.
 
@@ -59,7 +59,19 @@ Both presets use a 1280×800 CSS viewport. `draft` produces 1280×800 at 30 FPS;
 
 The cursor and click pulses are always drawn at the full frame rate. Chromium may capture page changes, such as scrolling and animations, at a lower rate at 2560×1600, depending on the machine. The video repeats the last page frame until the next one arrives.
 
-Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and FFmpeg filter file, including a partial capture if the flow fails during recording. On a preparation or recording failure, Traceframe also tries to save a viewport screenshot as `failure.png`. Keep that directory out of Git, because captures and screenshots can contain private page data.
+Use `--capture-diagnostics` (`captureDiagnostics: true` with `record` or `recordPage`) to include `captureStats` in the result. It reports received frames, their timestamp span and rate, the largest forward timestamp jumps and delivery gaps, and out-of-order timestamps. `lateFrames` counts frames older than the first received frame or the last written frame; `overflowFrames` counts frames dropped at the 64 MiB capture-buffer limit, and `maxBufferedBytes` reports its peak use. `writeWaitMs` and `maxWriteWaitMs` measure total and maximum time waiting for frame-write callbacks, including the final static frame; they do not measure durable disk writes. Slow writes can delay frame acknowledgments and reduce what Chromium sends, even when the writer drop counters stay at zero. These measurements describe frames delivered by Chromium. They do not count distinct pictures or prove smoothness; a static page legitimately delivers few frames, and a 30 FPS video cannot supply 60 distinct source frames per second.
+
+`--capture-quality <1–100>` (`captureQuality` in either API) controls the JPEG frames exported by Chromium; the default remains 95. A lower setting such as 80 can reduce frame-export and transfer cost, with a loss of image detail. This is separate from the final MP4 encoder. Check representative moving content and text at the intended resolution before choosing it.
+
+Since v0.6.0, the retained raw file is `capture.mkv` instead of `capture.webm`; update scripts that inspect it. Final output remains MP4.
+
+Traceframe saves Chromium's JPEG frames and presentation timestamps directly into a temporary `capture.mkv`, then encodes the final MP4 after the flow ends. This avoids a live intermediate video encode and works with CPU or GPU browser rendering. Chromium frame timestamps are retained with millisecond precision; a 150 ms buffer orders delayed arrivals. The first received frame establishes the audio clock, so subsequently delivered frames older than that origin are dropped. Slow storage applies backpressure. Moving content needs more temporary disk space than an inter-frame codec: at high resolution, allow hundreds of megabytes for short takes and potentially gigabytes for longer ones. Static pages need only a few stored frames. If your temporary directory is backed by RAM, choose a disk-backed `--run-dir` for large takes and remove it afterward. The final renderer supplies the requested frame rate while keeping cursor animations smooth.
+
+GPU rendering and hardware video decoding can help the browser, but frame export still costs CPU. The bundled headless browser used software rendering on the tested Linux setup; selecting an executable or adding a GPU flag does not guarantee acceleration. For a caller-owned browser, configure and verify its GPU use before `recordPage`; use full Chromium for extensions. A GPU capability flag alone does not establish that the active video is hardware-decoded. When measuring performance, keep the browser version, source codec, viewport and device scale fixed, and compare recorded image updates and audio timing as well as file metadata.
+
+Start performance comparisons with the Chromium build bundled with Playwright. A custom `--browser` executable can have different screencast performance even when recording succeeds. Traceframe preserves your requested resolution and quality. If the workload cannot sustain the desired cadence, increasing the encoded FPS repeats existing frames; choose a lower quality or smaller dimensions explicitly if that tradeoff suits your recording.
+
+Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and FFmpeg filter file, including a partial capture if the flow fails during recording. An interrupted or failed capture can be incomplete; a retained file is not proof that recording finalized successfully. On a preparation or recording failure, Traceframe also tries to save a viewport screenshot as `failure.png`. Keep that directory out of Git, because captures and screenshots can contain private page data.
 
 When available, failure output includes the error code, flow-file locations, elapsed recording time, and paths to artifacts saved for that attempt. Without `--run-dir`, temporary captures are removed and no failure screenshot is saved. See [diagnosing a failed take](docs/recording-flows.md#diagnose-a-failed-take).
 
@@ -178,9 +190,9 @@ For 2× frames, launch the caller's browser with `chromium.launch({ args: ['--fo
 
 Keep the viewport, zoom and visual scale fixed and the page open until `recordPage` settles; geometry is checked only at startup. Only that page is recorded; a tab closed during a take may lose its capture. Use the page exclusively for recording: concurrent screencasts, context `recordVideo` and tracing with screenshots can change frame dimensions or supply stale frames. A size check cannot detect every conflict. Overlapping `recordPage` calls on the same page reject with `PAGE_RECORDING_ACTIVE`.
 
-Await every helper. Helpers observe cancellation before further pointer or scroll actions, and release a mouse button that was already pressed; an already-issued action may still complete. Arbitrary callback code must cooperate with `signal`, including passing it to supported Playwright operations. A flow timeout does not forcibly terminate that code. Sequential takes are supported after a successful screencast stop, including ordinary flow failures and cooperative cancellation. If Playwright's FFmpeg is missing, Traceframe stops the partial capture before rejecting. Other startup or stop failures may need a new page or context; Traceframe leaves that recovery to the caller and does not stop a pre-existing caller screencast.
+Await every helper. Helpers observe cancellation before further pointer or scroll actions, and release a mouse button that was already pressed; an already-issued action may still complete. Arbitrary callback code must cooperate with `signal`, including passing it to supported Playwright operations. A flow timeout does not forcibly terminate that code. Sequential takes are supported after a successful screencast stop, including ordinary flow failures and cooperative cancellation. Startup or stop failures may need a new page or context; Traceframe leaves that recovery to the caller and does not stop a pre-existing caller screencast.
 
-Traceframe removes its own temporary outputs unless `runDirectory` is supplied. Playwright keeps original WebMs in its browser artifacts directory until the caller closes the browser, even after a take has been saved. For extension pages, use full Chromium; the headless shell alone does not load extensions. This path was checked on Linux with Playwright 1.64.1 and its bundled full Chromium using a synthetic extension.
+Traceframe removes its temporary capture unless `runDirectory` is supplied. For extension pages, use full Chromium; the headless shell alone does not load extensions. This path was checked on Linux with Playwright 1.64.1 and its bundled full Chromium using a synthetic extension.
 
 ### Add audio
 
@@ -195,7 +207,7 @@ npx @milkstraw/traceframe record --url http://localhost:3000 --flow ./flow.mjs \
 
 The input must be a local file, such as WAV, MP3, M4A or audio WebM. Static inputs are checked before browser recording, so a missing file or missing audio stream cannot waste a take (`AUDIO_INVALID`). After capture, an audio start at or after the video's end rejects with `AUDIO_OUTSIDE_VIDEO`. A negative offset that discards the entire source produces a silent audio track.
 
-Traceframe reads the file without modifying or deleting it; use an input path different from the output and the reserved files in `runDirectory` (`capture.webm`, `render.filter`, `failure.png`). Keep recordings in an ignored directory.
+Traceframe reads the file without modifying or deleting it; use an input path different from the output and the reserved files in `runDirectory` (`capture.mkv`, legacy `capture.webm`, `render.filter`, `failure.png`). Keep recordings in an ignored directory.
 
 For audio recorded alongside the flow, supply an async function instead. It runs once after successful capture and post-roll, before rendering, so it can finalize the external recorder and return its file. `startedAt` is the first video frame's timestamp in epoch milliseconds:
 
@@ -228,11 +240,11 @@ When available, `error.diagnostics` contains:
 | `capturePath` | Absolute path to the retained raw capture, only when `runDirectory` was supplied and saving succeeded. |
 | `screenshotPath` | Absolute path to the saved failure screenshot, only when `runDirectory` was supplied and the screenshot succeeded. |
 
-A flow timeout may have no flow location because it is raised outside the blocked operation. Screenshots are best effort and have a five-second collection budget. Partial captures are saved before browser shutdown, with no fixed time limit so slower encoders can finish. Diagnostic failures do not replace the original error.
+A flow timeout may have no flow location because it is raised outside the blocked operation. Screenshots are best effort and have a five-second collection budget. Partial captures are flushed before browser shutdown, with no fixed time limit so slower storage can finish. Diagnostic failures do not replace the original error.
 
 Pass `signal` to stop a recording early. Traceframe stops its recording/rendering work and removes its temporary files before rejecting with the signal's reason. `record` also closes its browser; `recordPage` leaves the caller's browser open. When you pass a signal, Traceframe leaves Ctrl-C and other termination signals to you. The CLI does this for you: the first Ctrl-C stops and cleans up, and a second one exits at once.
 
-A stuck recording encoder can delay saving and cancellation indefinitely. A second Ctrl-C forces the CLI to exit and can discard the unfinished capture. API callers that need a hard shutdown deadline should run recording in a separate process they can terminate.
+A stalled storage device can delay flushing and cancellation. A second Ctrl-C forces the CLI to exit and can discard unfinished writes. API callers that need a hard shutdown deadline should run recording in a separate process they can terminate.
 
 ## Sample output
 

package/docs/recording-flows.md

@@ -160,7 +160,7 @@ The two `Emulation` calls set the locale that `navigator.language`, `Intl`, and
 
 Use `--preset draft` while writing the flow and the default preset for the final video.
 
-While writing the flow, pass `--run-dir` with an ignored folder, such as `.traceframe/runs/demo`. Use a separate directory for each take. A failed take keeps its partial `capture.webm` when saving succeeds and attempts a viewport screenshot, `failure.png`. The raw capture has no added cursor overlay and may include repeated final frames after the failure time.
+While writing the flow, pass `--run-dir` with an ignored folder, such as `.traceframe/runs/demo`. Use a separate directory for each take. A failed take keeps its partial `capture.mkv` when available and attempts a viewport screenshot, `failure.png`. An interrupted capture may be incomplete. The raw capture has no added cursor overlay and may include repeated final frames after the failure time.
 
 A failed take may already have submitted real jobs, so reset demo data before recording again. Check the finished file for decode errors:
 
@@ -200,7 +200,7 @@ The CLI keeps the original error message and adds available context on standard
 traceframe: [FLOW_FAILED] Expected the Saved status.
   Flow: /project/review.mjs:18:9
   Recording time: 12.35 s
-  Capture: /project/.traceframe/runs/demo/capture.webm
+  Capture: /project/.traceframe/runs/demo/capture.mkv
   Screenshot: /project/.traceframe/runs/demo/failure.png
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milkstraw/traceframe",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Record scripted browser flows and render smooth cursor overlays into video.",
   "keywords": [
     "playwright",

package/src/capture-stats.mjs

@@ -0,0 +1,33 @@
+// Delivery cadence describes Chromium's exported frames. It cannot establish
+// distinct pixels or smoothness: a static page legitimately sends few frames.
+export function createCaptureStats() {
+  let framesReceived = 0, earliestTimestamp, latestTimestamp, lastDelivery
+  let maxFrameGapMs = 0, maxDeliveryGapMs = 0, outOfOrderFrames = 0
+  return {
+    observe(timestamp, delivery) {
+      if (framesReceived === 0) earliestTimestamp = latestTimestamp = timestamp
+      else {
+        earliestTimestamp = Math.min(earliestTimestamp, timestamp)
+        if (timestamp < latestTimestamp) outOfOrderFrames++
+        else {
+          maxFrameGapMs = Math.max(maxFrameGapMs, timestamp - latestTimestamp)
+          latestTimestamp = timestamp
+        }
+        maxDeliveryGapMs = Math.max(maxDeliveryGapMs, delivery - lastDelivery)
+      }
+      lastDelivery = delivery
+      framesReceived++
+    },
+    summary() {
+      const sourceSpanSeconds = framesReceived > 1 ? (latestTimestamp - earliestTimestamp) / 1000 : 0
+      return {
+        framesReceived,
+        sourceSpanSeconds,
+        receivedFps: sourceSpanSeconds > 0 ? (framesReceived - 1) / sourceSpanSeconds : 0,
+        maxFrameGapMs,
+        maxDeliveryGapMs,
+        outOfOrderFrames,
+      }
+    },
+  }
+}

package/src/capture.mjs

@@ -7,21 +7,30 @@ import { chromium } from 'playwright'
 import { TraceframeError } from './errors.mjs'
 import { addDiagnostics, retainedFile } from './diagnostics.mjs'
 import { createFlowApi } from './flow.mjs'
+import { createCaptureStats } from './capture-stats.mjs'
+import { createJpegCapture } from './jpeg-capture.mjs'
 
 const PLAYWRIGHT_DEFAULT_TIMEOUT = 30_000
 const FIRST_FRAME_TIMEOUT = 10_000
 const FAILURE_SCREENSHOT_TIMEOUT = 5_000
 
 export async function captureFlow({ config, flow, directory, page, signal: callerSignal }) {
-  const signal = callerSignal ?? new AbortController().signal
-  const rawPath = join(directory, 'capture.webm')
+  const captureErrors = new AbortController()
+  const signal = callerSignal ? AbortSignal.any([callerSignal, captureErrors.signal]) : captureErrors.signal
+  const rawPath = join(directory, 'capture.mkv')
   const trace = { initialPointer: flow.initialPointer, moves: [], clicks: [] }
+  const stats = config.captureDiagnostics ? createCaptureStats() : undefined
 
   signal.throwIfAborted()
   const browser = page ? undefined : await launchBrowser(config, { handleSignals: !callerSignal })
   let clock
   let recording = false
   let failed = false
+  let capture
+  async function stopCapture() {
+    const stoppedAt = Date.now()
+    try { await page.screencast.stop() } finally { await capture?.stop(stoppedAt) }
+  }
   try {
     if (browser) {
       page = await browser.newPage({ viewport: config.viewport, deviceScaleFactor: config.scale, storageState: config.storageState })
@@ -34,7 +43,12 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
 
     const firstFrame = Promise.withResolvers()
     signal.throwIfAborted()
-    await startScreencast(page, rawPath, config, firstFrame.resolve)
+    capture = createJpegCapture(rawPath, { ...config.video, onError: cause => captureErrors.abort(new TraceframeError(`Could not save capture: ${cause.message}`, { code: 'CAPTURE_FAILED', cause })) })
+    await page.screencast.start({ size: { width: config.video.width, height: config.video.height }, fps: config.video.fps, quality: config.captureQuality, onFrame: (frame) => {
+      stats?.observe(frame.timestamp, performance.now())
+      firstFrame.resolve(frame)
+      return capture.append(frame)
+    } })
     recording = true
     const frame = await withDeadline(
       () => firstFrame.promise,
@@ -43,8 +57,8 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
       signal,
     )
     clock = frame.timestamp
+    assertFrameSize(frame, config)
     if (!browser) {
-      assertFrameSize(frame, config)
       signal.throwIfAborted()
       // Rejected caller-page attempts must leave the caller's pointer alone.
       await page.mouse.move(trace.initialPointer.x, trace.initialPointer.y)
@@ -62,23 +76,27 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
     }
     trace.end = (Date.now() - clock) / 1000
     await delay(config.postRoll * 1000, undefined, { signal })
-    // A failed stop must not be retried: Playwright may still be waiting to finish its artifact.
+    // Stop the page subscription only once, including when shutdown fails.
     recording = false
-    await page.screencast.stop()
-    return { rawPath, trace, startedAt: clock }
+    await stopCapture()
+    return { rawPath, trace, startedAt: clock, ...(stats ? { captureStats: { ...stats.summary(), ...capture.stats } } : {}) }
   } catch (error) {
     failed = true
+    // A writer failure during cleanup must not replace the initiating failure.
+    const failure = signal.aborted ? signal.reason : error
     const recordingTime = clock === undefined ? undefined : Math.max(0, (Date.now() - clock) / 1000)
-    // Let the encoder finish saving before closing the browser, including on slower machines.
+    // Flush captured frames before closing the browser, including on slower disks.
     const [capturePath, screenshotPath] = await Promise.all([
-      recording ? page.screencast.stop()
-        .then(() => config.runDirectory ? retainedFile(rawPath) : undefined)
-        .catch(() => undefined) : undefined,
+      (recording ? stopCapture().catch(() => {}) : Promise.resolve())
+        .then(() => capture?.stop())
+        .then(() => clock !== undefined && config.runDirectory ? retainedFile(rawPath) : undefined)
+        .catch(() => undefined),
       config.runDirectory && page && !signal.aborted ? saveFailureScreenshot(page, directory, signal) : undefined,
     ])
-    if (signal.aborted) throw error
-    throw await addDiagnostics(error, { flow: config.flow, recordingTime, capturePath, screenshotPath })
+    if (callerSignal?.aborted) throw callerSignal.reason
+    throw await addDiagnostics(failure, { flow: config.flow, recordingTime, capturePath, screenshotPath })
   } finally {
+    await capture?.stop().catch(() => {})
     // A shutdown error must not hide the flow failure.
     if (browser) {
       if (failed) await browser.close().catch(() => {})
@@ -100,7 +118,7 @@ async function assertPageGeometry(page, config, signal) {
 }
 
 function assertFrameSize(frame, config) {
-  // Playwright may pad the saved WebM. Check the actual JPEG, not DPR or the container size.
+  // Check the exported JPEG dimensions; deviceScaleFactor alone is insufficient.
   const size = jpegSize(frame.data)
   if (size?.width !== config.video.width || size?.height !== config.video.height ||
       frame.viewportWidth !== config.viewport.width || frame.viewportHeight !== config.viewport.height) {
@@ -150,7 +168,7 @@ async function launchBrowser(config, { handleSignals }) {
     if (!/Executable doesn't exist/i.test(error.message)) throw error
     const message = config.browser
       ? `Configured browser executable is unavailable: ${config.browser}`
-      : 'Playwright Chromium is not installed. Run `npx playwright@1.64.1 install --only-shell chromium`, or pass --browser to a Chrome executable and run `npx playwright@1.64.1 install ffmpeg`.'
+      : 'Playwright Chromium is not installed. Run `npx playwright@1.64.1 install --only-shell chromium`, or pass --browser to a Chrome executable.'
     throw new TraceframeError(message, { code: 'PLAYWRIGHT_RUNTIME_MISSING', cause: error })
   }
 }
@@ -167,17 +185,6 @@ async function waitForReady(page, flow, config, signal) {
   }
 }
 
-async function startScreencast(page, path, config, onFrame) {
-  try {
-    await page.screencast.start({ path, size: { width: config.video.width, height: config.video.height }, fps: config.video.fps, quality: 95, onFrame })
-  } catch (error) {
-    if (!/Executable doesn't exist/i.test(error.message)) throw error
-    // Playwright added our frame client before looking for FFmpeg; no caller recorder was active.
-    await page.screencast.stop().catch(() => {})
-    throw new TraceframeError("Playwright's FFmpeg is not installed. It is needed to record, even with --browser. Run `npx playwright@1.64.1 install ffmpeg`.", { code: 'PLAYWRIGHT_RUNTIME_MISSING', cause: error })
-  }
-}
-
 // Settles with the task, or rejects at the deadline or on abort, even if the task ignores its signal.
 async function withDeadline(task, milliseconds, error, signal) {
   const controller = new AbortController()

package/src/cli.mjs

@@ -20,6 +20,8 @@ const OPTION_KEYS = {
   'viewport-height': 'viewportHeight',
   scale: 'scale',
   fps: 'fps',
+  'capture-quality': 'captureQuality',
+  'capture-diagnostics': 'captureDiagnostics',
   'post-roll': 'postRoll',
   'ready-timeout': 'readyTimeout',
   'flow-timeout': 'flowTimeout',
@@ -27,7 +29,7 @@ const OPTION_KEYS = {
   audio: 'audio',
   'audio-offset': 'audioOffset',
 }
-const NUMBER_KEYS = new Set(['viewportWidth', 'viewportHeight', 'scale', 'fps', 'postRoll', 'readyTimeout', 'flowTimeout', 'audioOffset'])
+const NUMBER_KEYS = new Set(['viewportWidth', 'viewportHeight', 'scale', 'fps', 'captureQuality', 'postRoll', 'readyTimeout', 'flowTimeout', 'audioOffset'])
 const HELP = `traceframe ${VERSION}
 
 Record a scripted Chromium flow and render a smooth cursor and click pulse.
@@ -44,6 +46,8 @@ Options:
   --viewport-height <pixels>   CSS viewport height
   --scale <1|2>                Device scale factor; the video is the viewport times this
   --fps <30|60>                Encoded frame rate
+  --capture-quality <1–100>    JPEG frame quality (default: 95); lower can reduce capture cost
+  --capture-diagnostics        Include frame delivery cadence and gaps in the JSON summary
   --post-roll <seconds>        Tail after the flow (default: 0.3)
   --ready-timeout <seconds>    Playwright default timeout during navigation and ready() (default: 30)
   --flow-timeout <seconds>     Time limit for the flow, including waits (default: 120)
@@ -99,7 +103,7 @@ function parseCommand(args) {
     options: {
       help: { type: 'boolean', short: 'h' },
       version: { type: 'boolean', short: 'v' },
-      ...Object.fromEntries(Object.keys(OPTION_KEYS).map((name) => [name, { type: 'string' }])),
+      ...Object.fromEntries(Object.keys(OPTION_KEYS).map((name) => [name, { type: name === 'capture-diagnostics' ? 'boolean' : 'string' }])),
     },
   })
   if (values.help || args.length === 0) return { help: true }

package/src/config.mjs

@@ -54,6 +54,9 @@ function recordingConfig(options, viewport, defaults) {
     fps: options.fps ?? defaults.fps,
   }
   check(video.fps === 30 || video.fps === 60, 'FPS must be 30 or 60.')
+  const captureQuality = options.captureQuality ?? 95
+  check(Number.isInteger(captureQuality) && captureQuality >= 1 && captureQuality <= 100, 'Capture quality must be an integer from 1 to 100.')
+  check(options.captureDiagnostics === undefined || typeof options.captureDiagnostics === 'boolean', 'Capture diagnostics must be a boolean.')
   check(video.width % 2 === 0 && video.height % 2 === 0, 'At scale 1, the viewport width and height must be even.')
 
   const output = resolve(options.output ?? 'traceframe.mp4')
@@ -69,6 +72,8 @@ function recordingConfig(options, viewport, defaults) {
     audio: typeof options.audio === 'function' ? options.audio : createAudioConfig(options.audio, output, runDirectory),
     viewport: { ...viewport },
     video,
+    captureQuality,
+    captureDiagnostics: options.captureDiagnostics ?? false,
     scale,
     postRoll,
     flowTimeout,
@@ -82,7 +87,7 @@ export function createAudioConfig(audio, output, directory) {
   const path = resolve(audio.path)
   check(path !== output, 'Audio input and video output must use different paths.')
   if (directory) {
-    check(!['capture.webm', 'render.filter', 'failure.png'].some((name) => path === resolve(directory, name)), `Audio input must not use a reserved recording file: ${path}`)
+    check(!['capture.mkv', 'capture.webm', 'render.filter', 'failure.png'].some((name) => path === resolve(directory, name)), `Audio input must not use a reserved recording file: ${path}`)
   }
   const offset = audio.offset ?? 0
   check(Number.isFinite(offset), 'Audio offset must be a finite number of seconds.')

package/src/ffmpeg.mjs

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process'
+import { addAbortListener } from 'node:events'
 import { stat } from 'node:fs/promises'
 import { promisify } from 'node:util'
 
@@ -20,7 +21,11 @@ export async function probeFfmpeg({ audio = false } = {}) {
     throw new TraceframeError('System FFmpeg does not provide the AAC encoder required for audio.', { code: 'FFMPEG_UNSUPPORTED' })
   }
   await runCommand('ffprobe', ['-version'])
-  return { filterComplexFileOption: filterComplexFileOption(major) }
+  return {
+    filterComplexFileOption: filterComplexFileOption(major),
+    // FFmpeg 7's pass mode cuts off padded main-video frames at the original EOF.
+    overlayEofAction: major === 7 ? 'repeat' : 'pass',
+  }
 }
 
 export async function probeAudio(path, signal) {
@@ -41,8 +46,19 @@ export async function probeVideoDuration(path, signal) {
 }
 
 export async function runCommand(command, args, options = {}) {
-  const run = execFileAsync(command, args, options)
+  const windowsSignal = process.platform === 'win32' ? options.signal : undefined
+  windowsSignal?.throwIfAborted()
+  const run = execFileAsync(command, args, windowsSignal ? { ...options, signal: undefined } : options)
   const closed = new Promise((resolve) => run.child.once('close', resolve))
+  let termination
+  const abort = windowsSignal && addAbortListener(windowsSignal, () => {
+    // Chocolatey shims launch the real encoder as a child. Stop both before
+    // removing files, which Windows keeps locked while the encoder is alive.
+    if (run.child.pid && run.child.exitCode === null && run.child.signalCode === null) {
+      termination = execFileAsync('taskkill', ['/pid', String(run.child.pid), '/t', '/f'])
+        .catch(() => run.child.kill())
+    }
+  })
   try {
     return await run
   } catch (error) {
@@ -54,6 +70,9 @@ export async function runCommand(command, args, options = {}) {
     const rawDetail = error.stderr?.trim() || error.stdout?.trim() || error.message
     const detail = rawDetail.length > 2_000 ? `${rawDetail.slice(0, 1_900)}\n… output truncated` : rawDetail
     throw new TraceframeError(`${command} failed: ${detail}`, { code: 'COMMAND_FAILED', cause: error })
+  } finally {
+    abort?.[Symbol.dispose]()
+    await termination
   }
 }
 

package/src/jpeg-capture.mjs

@@ -0,0 +1,132 @@
+import { createWriteStream } from 'node:fs'
+import { open, rm } from 'node:fs/promises'
+import { finished } from 'node:stream/promises'
+
+// Keep Chromium's JPEGs and presentation timestamps; encode only during rendering.
+// A short reorder window handles JPEGs that finish compression out of order.
+const REORDER_MS = 150
+const MAX_BUFFER_BYTES = 64 * 1024 * 1024
+
+export function createJpegCapture(path, { width, height, fps, onError }) {
+  const output = createWriteStream(path)
+  let error, origin, newest = -Infinity, last, bufferedBytes = 0, draining, closing
+  const pending = []
+  const stats = { lateFrames: 0, overflowFrames: 0, maxBufferedBytes: 0, writeWaitMs: 0, maxWriteWaitMs: 0 }
+  function fail(cause) {
+    if (!error) { error = cause; onError(cause) }
+  }
+  output.on('error', fail)
+  const { bytes, durationOffset } = header(width, height, fps)
+  output.write(bytes)
+
+  async function write(frame) {
+    if (frame.timestamp < (last?.timestamp ?? origin)) { stats.lateFrames++; return }
+    const started = performance.now()
+    try {
+      await new Promise((resolve, reject) => {
+        output.cork()
+        output.write(cluster(Math.round(frame.timestamp - origin), frame.data.length))
+        output.write(frame.data, cause => cause ? reject(cause) : resolve())
+        output.uncork()
+      })
+    } finally {
+      const elapsed = performance.now() - started
+      stats.writeWaitMs += elapsed
+      stats.maxWriteWaitMs = Math.max(stats.maxWriteWaitMs, elapsed)
+    }
+    last = frame
+  }
+  async function flush(all = false) {
+    while (!error && pending.length && (all || pending[0].timestamp <= newest - REORDER_MS)) {
+      const frame = pending.shift()
+      try { await write(frame) } finally { bufferedBytes -= frame.data.length }
+    }
+  }
+  return {
+    stats,
+    append(frame) {
+      if (closing || error) return
+      origin ??= frame.timestamp
+      newest = Math.max(newest, frame.timestamp)
+      if (bufferedBytes + frame.data.length > MAX_BUFFER_BYTES) stats.overflowFrames++
+      else {
+        pending.push(frame)
+        pending.sort((a, b) => a.timestamp - b.timestamp)
+        bufferedBytes += frame.data.length
+      }
+      stats.maxBufferedBytes = Math.max(stats.maxBufferedBytes, bufferedBytes)
+      draining ??= flush().catch(fail).finally(() => { draining = undefined })
+      return draining
+    },
+    stop(stoppedAt = Date.now()) {
+      closing ??= (async () => {
+        try {
+          await draining
+          await flush(true)
+          if (error) throw error
+          // Preserve a static tail without encoding duplicate pictures live.
+          if (last && stoppedAt > last.timestamp) await write({ data: last.data, timestamp: stoppedAt })
+          output.end()
+          await finished(output)
+          if (last) {
+            const duration = Buffer.from('4489880000000000000000', 'hex')
+            duration.writeDoubleBE(Math.round(last.timestamp - origin) + 1000 / fps, 3)
+            const file = await open(path, 'r+')
+            try {
+              const { bytesWritten } = await file.write(duration, 0, duration.length, durationOffset)
+              if (bytesWritten !== duration.length) throw new Error('Could not finish the capture duration.')
+            } finally { await file.close() }
+          }
+        } catch (cause) {
+          fail(cause)
+          throw cause
+        } finally {
+          output.destroy()
+          await finished(output).catch(() => {})
+          pending.length = 0
+          last = undefined
+          if (origin === undefined && !error) await rm(path, { force: true })
+        }
+      })()
+      return closing
+    },
+  }
+}
+
+// The fixed Matroska subset contains one MJPEG track and one keyframe per cluster.
+// Timestamps are milliseconds; JPEG dimensions and pixels remain unchanged.
+function uint(value) {
+  const bytes = []
+  do { bytes.unshift(value % 256); value = Math.floor(value / 256) } while (value)
+  return Buffer.from(bytes)
+}
+function size(value) {
+  let length = 1
+  while (value >= 2 ** (7 * length) - 1) length++
+  const bytes = Buffer.alloc(length)
+  for (let i = length - 1; i >= 0; i--) { bytes[i] = value % 256; value = Math.floor(value / 256) }
+  bytes[0] |= 1 << (8 - length)
+  return bytes
+}
+function element(id, value) {
+  const data = typeof value === 'number' ? uint(value) : typeof value === 'string' ? Buffer.from(value) : Buffer.concat(value)
+  return Buffer.concat([Buffer.from(id, 'hex'), size(data.length), data])
+}
+function header(width, height, fps) {
+  const prefix = Buffer.concat([
+    element('1a45dfa3', [element('4286', 1), element('42f7', 1), element('42f2', 4), element('42f3', 8), element('4282', 'matroska'), element('4287', 4), element('4285', 2)]),
+    Buffer.from('1853806701ffffffffffffff', 'hex'),
+  ])
+  // Reserve a Void element, then replace it with Duration after the last write.
+  const durationSlot = Buffer.from('ec89000000000000000000', 'hex')
+  const info = element('1549a966', [element('2ad7b1', 1_000_000), element('4d80', 'traceframe'), element('5741', 'traceframe'), durationSlot])
+  const bytes = Buffer.concat([prefix, info,
+    element('1654ae6b', [element('ae', [element('d7', 1), element('73c5', 1), element('83', 1), element('9c', 0), element('86', 'V_MJPEG'), element('23e383', Math.round(1e9 / fps)), element('e0', [element('b0', width), element('ba', height)])])]),
+  ])
+  return { bytes, durationOffset: prefix.length + info.length - durationSlot.length }
+}
+function cluster(timestamp, length) {
+  const time = element('e7', timestamp)
+  const block = Buffer.concat([Buffer.from('a3', 'hex'), size(length + 4), Buffer.from('81000080', 'hex')])
+  return Buffer.concat([Buffer.from('1f43b675', 'hex'), size(time.length + block.length + length), time, block])
+}

package/src/record.mjs

@@ -67,6 +67,7 @@ async function recordFlow({ config, flow, ffmpeg, signal, page }) {
       clickCount: trace.clicks.length,
       runDirectory: config.runDirectory,
       ...(audio ? { audio: true } : {}),
+      ...(capture.captureStats ? { captureStats: capture.captureStats } : {}),
     }
   } catch (error) {
     failed = true

package/src/render.mjs

@@ -9,18 +9,15 @@ const ASSETS = join(import.meta.dirname, 'assets')
 // The arrow tip in cursor.svg.
 const CURSOR_HOTSPOT = { x: 6.6, y: 1.6 }
 const CLICK = { duration: 0.24, scaleStart: 0.7, scaleEnd: 1.25 }
-// eof_action=pass lets the main video drive each overlay instead of waiting on the looping image inputs; without it, rendering is many times slower.
-// format=yuv444 places overlays on whole pixels. The default yuv420 snaps them to even pixels, and RGB costs more for the same result.
-const OVERLAY = 'eof_action=pass:format=yuv444'
 
 export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, signal, audio }) {
   const { fps } = config.video
-  const outputDuration = Math.max(trace.end + config.postRoll, ...trace.clicks.map((click) => click.at + CLICK.duration))
+  const outputDuration = Math.max(1 / fps, trace.end + config.postRoll, ...trace.clicks.map((click) => click.at + CLICK.duration))
   if (audio && audio.offset >= outputDuration) {
     throw new TraceframeError(`Audio offset ${audio.offset} seconds starts at or after the video's end (${number(outputDuration)} seconds). Reduce its offset.`, { code: 'AUDIO_OUTSIDE_VIDEO' })
   }
   const filterPath = join(directory, 'render.filter')
-  await writeFile(filterPath, buildFilterScript({ trace, scale: config.scale, audio }))
+  await writeFile(filterPath, buildFilterScript({ trace, scale: config.scale, fps, audio, overlayEofAction: ffmpeg.overlayEofAction }))
   const outputTemp = join(dirname(config.output), `.traceframe-${randomUUID()}.tmp.mp4`)
   const args = [
     '-y', '-hide_banner', '-loglevel', 'error',
@@ -58,18 +55,29 @@ export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, s
 }
 
 // Event times are seconds from the first frame of the raw video.
-export function buildFilterScript({ trace, scale, audio }) {
+export function buildFilterScript({ trace, scale, fps = 60, audio, overlayEofAction = 'pass' }) {
   const { clicks, moves } = trace
-  // Playwright ends the raw video by the time it received the last frame, so a page that stays still can end it a little before the post-roll. The page did not change, so repeat its last frame.
-  const filters = [`[0:v]setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=1[video0]`]
+  const animatedOverlays = clicks.length > 0 || moves.length > 0
+  const cadence = `tpad=stop_mode=clone:stop_duration=1,fps=${fps}`
+  // Pass mode avoids waiting on looping image inputs; FFmpeg 7 needs repeat for padding.
+  // yuv444 places overlays on whole pixels rather than snapping them to even pixels.
+  const overlay = `eof_action=${overlayEofAction}:format=yuv444`
+  // Animated overlays need every output tick, even on a static page.
+  // With stationary overlays, composite before duplicating identical frames.
+  // Padding also covers a sub-frame take or final rounding.
+  // Chrome JPEGs are full range; normalize before compositing limited-range overlays.
+  // Convert to the overlay format before duplicating frames. Converting afterward
+  // can queue a full-size buffer for every repeated frame in a long static gap.
+  const filters = [`[0:v]scale=out_range=tv,format=yuv420p,format=yuv444p,setpts=PTS-STARTPTS${animatedOverlays ? ',' + cadence : ''}[video0]`]
   if (clicks.length) filters.push(`[2:v]format=rgba,split=${clicks.length}${clicks.map((_, index) => `[pulse${index}]`).join('')}`)
-  clicks.forEach((click, index) => filters.push(...clickFilter(click, index, scale)))
+  clicks.forEach((click, index) => filters.push(...clickFilter(click, index, scale, overlay)))
 
   const cursorLabels = moves.map((_, index) => `[cursor${index}]`).join('')
-  filters.push(`[1:v]format=rgba,split=${moves.length + 1}${cursorLabels}[cursor${moves.length}]`)
+  // Convert the cursor once before splitting it into movement segments.
+  filters.push(`[1:v]format=yuva444p,split=${moves.length + 1}${cursorLabels}[cursor${moves.length}]`)
   const coordinate = (value, hotspot) => number(value * scale - hotspot * scale)
   const initialEnable = moves.length ? `:enable='lt(t,${number(moves[0].at)})'` : ''
-  filters.push(`[video${clicks.length}][cursor0]overlay=x='${coordinate(trace.initialPointer.x, CURSOR_HOTSPOT.x)}':y='${coordinate(trace.initialPointer.y, CURSOR_HOTSPOT.y)}':${OVERLAY}${initialEnable}[cursorVideo0]`)
+  filters.push(`[video${clicks.length}][cursor0]overlay=x='${coordinate(trace.initialPointer.x, CURSOR_HOTSPOT.x)}':y='${coordinate(trace.initialPointer.y, CURSOR_HOTSPOT.y)}':${overlay}${initialEnable}[cursorVideo0]`)
   moves.forEach((move, index) => {
     const start = number(move.at)
     const end = index + 1 < moves.length ? number(moves[index + 1].at) : undefined
@@ -79,9 +87,9 @@ export function buildFilterScript({ trace, scale, audio }) {
     const eased = `(1-pow(1-clip((t-${start})/${number(move.duration)},0,1),3))`
     const x = `${coordinate(move.from.x, CURSOR_HOTSPOT.x)}+${number((move.to.x - move.from.x) * scale)}*${eased}`
     const y = `${coordinate(move.from.y, CURSOR_HOTSPOT.y)}+${number((move.to.y - move.from.y) * scale)}*${eased}`
-    filters.push(`[cursorVideo${index}][cursor${index + 1}]overlay=x='${x}':y='${y}':${OVERLAY}:enable='${enable}'[cursorVideo${index + 1}]`)
+    filters.push(`[cursorVideo${index}][cursor${index + 1}]overlay=x='${x}':y='${y}':${overlay}:enable='${enable}'[cursorVideo${index + 1}]`)
   })
-  filters.push(`[cursorVideo${moves.length}]colorspace=ispace=bt470bg:iprimaries=bt709:itrc=bt709:all=bt709:format=yuv420p[final]`)
+  filters.push(`[cursorVideo${moves.length}]colorspace=ispace=bt470bg:iprimaries=bt709:itrc=bt709:all=bt709:format=yuv420p${animatedOverlays ? '' : ',' + cadence}[final]`)
   if (audio) {
     const input = clicks.length ? 3 : 2
     const trim = number(Math.max(0, -audio.offset))
@@ -93,13 +101,13 @@ export function buildFilterScript({ trace, scale, audio }) {
   return filters.join(';')
 }
 
-function clickFilter(click, index, scale) {
+function clickFilter(click, index, scale, overlay) {
   const start = number(click.at)
   const end = number(start + CLICK.duration)
   const growth = `(${CLICK.scaleStart}+${CLICK.scaleEnd - CLICK.scaleStart}*clip((t-${start})/${CLICK.duration},0,1))`
   return [
     `[pulse${index}]setpts=PTS-STARTPTS+${start}/TB,scale=w='iw*${growth}':h='ih*${growth}':eval=frame,fade=t=out:st=${start}:d=${CLICK.duration}:alpha=1[click${index}]`,
-    `[video${index}][click${index}]overlay=x='${number(click.point.x * scale)}-w/2':y='${number(click.point.y * scale)}-h/2':${OVERLAY}:enable='between(t,${start},${end})'[video${index + 1}]`,
+    `[video${index}][click${index}]overlay=x='${number(click.point.x * scale)}-w/2':y='${number(click.point.y * scale)}-h/2':${overlay}:enable='between(t,${start},${end})'[video${index + 1}]`,
   ]
 }