@milkstraw/traceframe 0.6.1 → 0.6.3

package/README.md

@@ -61,16 +61,18 @@ The cursor and click pulses are always drawn at the full frame rate. Chromium ma
 
 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.
+`--capture-quality <1–100>` (`captureQuality` in either API) controls the JPEG frames exported by Chromium; the default is 85. In 3024 × 1964 tests, 85 made captured frames about a third smaller than 95, with slightly lower CPU use and no visible difference in the exported MP4. Quality did not change how many frames Chromium captured. Use 95 for maximum detail, or a lower setting such as 75 for smaller temporary captures with softer fine detail. This is separate from the final MP4 encoder. Check representative moving content and text at the intended resolution before choosing a non-default value.
 
 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.
+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 microsecond 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.
 
+For video-heavy flows, see [checking video playback](docs/recording-flows.md#check-video-playback), including optional page effects and media sizing.
+
 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).

package/docs/recording-flows.md

@@ -24,6 +24,16 @@ Put setup and page readiness in `ready({ page, signal })`. This runs after initi
 
 If your script already owns the page or an extension context, use [`recordPage`](../README.md#record-a-page-you-already-opened) with an inline callback. Prepare the page before calling it; the caller owns navigation and browser cleanup.
 
+### Check video playback
+
+For a video-heavy journey, check playback in your first take at the final recording settings; a separate check before recording is not needed. Record that take with `--capture-diagnostics` (`captureDiagnostics: true` in the API) and [inspect the saved motion](#record-inspect-and-refine) of its video segment. Capture diagnostics count delivered frames, which can contain repeated pictures; a final MP4 reporting 60 FPS does not establish 60 distinct captured images per second, and a 30 FPS source cannot provide 60 distinct video frames per second. If the video looks smooth, later takes need no new playback check until the browser, recording settings or workload changes.
+
+On YouTube, the player's **Settings (gear) → Ambient mode → Off** can reduce expensive background drawing during CPU-only playback. Ambient mode is available only with YouTube's dark theme; check the setting under the theme you will record. Disable this decorative effect only when it is unnecessary for the demonstration, and verify the setting before the take. Use the site's setting in `ready`, or prepare the caller-owned page before `recordPage`; Traceframe does not change it automatically.
+
+For video assets you control, matching the source dimensions to the displayed physical pixels can avoid costly browser resizing during CPU-only playback. Physical dimensions include device scale: a video displayed 1512 CSS pixels wide at scale 2 occupies 3024 physical pixels. Preparing another asset can change image quality, so compare it with the original and preserve the intended framing. Do not silently replace third-party media, crop content or lower the required output resolution to claim a performance improvement.
+
+If the video looks choppy, apply any preparation above that suits the demonstration and make one more take at the same recording settings. If it is still choppy, or nothing applies, keep the requested output dimensions, playback speed and source quality, finish the requested recording and report the limitation. For optional diagnosis of playback without recording, let buffering and any extension processing warm up, then read the video's `getVideoPlaybackQuality()` counters before and after a representative segment with recording off, for example in `ready` or before `recordPage`. Page preparation can improve playback while capture remains expensive.
+
 ## Save and switch login state
 
 Add `.auth/` to your project's `.gitignore`; saved state can grant access to the account. To create it interactively, install full Chromium and open Playwright's login window:

package/package.json

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

package/src/cli.mjs

@@ -46,7 +46,7 @@ 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-quality <1–100>    JPEG frame quality (default: 85); higher keeps more detail
   --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)

package/src/config.mjs

@@ -54,7 +54,7 @@ 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
+  const captureQuality = options.captureQuality ?? 85
   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.')

package/src/jpeg-capture.mjs

@@ -6,6 +6,9 @@ import { finished } from 'node:stream/promises'
 // A short reorder window handles JPEGs that finish compression out of order.
 const REORDER_MS = 150
 const MAX_BUFFER_BYTES = 64 * 1024 * 1024
+// Store microseconds. Millisecond rounding can move distinct pictures into the
+// same output frame when export resamples to a fixed frame rate.
+const TIMESTAMP_SCALE_NS = 1_000
 
 export function createJpegCapture(path, { width, height, fps, onError }) {
   const output = createWriteStream(path)
@@ -25,7 +28,7 @@ export function createJpegCapture(path, { width, height, fps, onError }) {
     try {
       await new Promise((resolve, reject) => {
         output.cork()
-        output.write(cluster(Math.round(frame.timestamp - origin), frame.data.length))
+        output.write(cluster(ticks(frame.timestamp - origin), frame.data.length))
         output.write(frame.data, cause => cause ? reject(cause) : resolve())
         output.uncork()
       })
@@ -70,7 +73,7 @@ export function createJpegCapture(path, { width, height, fps, onError }) {
           await finished(output)
           if (last) {
             const duration = Buffer.from('4489880000000000000000', 'hex')
-            duration.writeDoubleBE(Math.round(last.timestamp - origin) + 1000 / fps, 3)
+            duration.writeDoubleBE(ticks(last.timestamp - origin + 1000 / fps), 3)
             const file = await open(path, 'r+')
             try {
               const { bytesWritten } = await file.write(duration, 0, duration.length, durationOffset)
@@ -94,7 +97,10 @@ export function createJpegCapture(path, { width, height, fps, onError }) {
 }
 
 // The fixed Matroska subset contains one MJPEG track and one keyframe per cluster.
-// Timestamps are milliseconds; JPEG dimensions and pixels remain unchanged.
+// Timestamps are microseconds; JPEG dimensions and pixels remain unchanged.
+function ticks(milliseconds) {
+  return Math.round(milliseconds * 1e6 / TIMESTAMP_SCALE_NS)
+}
 function uint(value) {
   const bytes = []
   do { bytes.unshift(value % 256); value = Math.floor(value / 256) } while (value)
@@ -119,7 +125,7 @@ function header(width, height, fps) {
   ])
   // 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 info = element('1549a966', [element('2ad7b1', TIMESTAMP_SCALE_NS), 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)])])]),
   ])