Speed

Source README.md · versioncam 0.5.3 from npm

Writing a clip is a loop: run it, look at it, change a line. What matters is how long that loop takes.

Most frames are not photographed. A clip is mostly frames in which nothing moved. The screenshot is by far the most expensive thing a frame does: 25 ms, against half a millisecond for everything else. So the driver takes one only when the page can have changed. That is when the DOM mutated, the element under the cursor changed, an animation or a transition is running, input was just sent, or forceCaptureEvery frames have gone by. On the example app that skips 81% to 95% of frames, and the recording is identical either way. A test records every clip both ways on every push and compares the bytes. The failure it guards against is not a crash but a video that is quietly wrong.

The one thing the gate cannot see is a surface that redraws itself: a canvas, a WebGL view, a video. None of them touches the DOM. forceCaptureEvery (default 30) is the floor under that. A clip whose subject is a canvas should set it to 1 and pay full price:

export default clip("03-the-map", { title: "The map", capture: { forceCaptureEvery: 1 } }, …);

--draft for the loop. Fifteen frames a second, captured at CSS scale instead of device scale, into the same place a full recording goes.

npx versioncam record --draft 02-find-a-shipment   # then render and look

A draft does not change the page: same viewport, same device pixel ratio, same layout, same code. A draft that lowered the DPR could pass while the capture it stands in for fails on a media query. It does ignore a clip’s own fps, because the point is to be cheap. Its length can land up to 1/15 s from the full capture’s, so a draft is for looking at, not for comparing against.

versioncam record prints where the time went. That tells you whether the next second would come from the frames or from somewhere else:

  01-create-a-shipment: 425 frames, 63 states, 1 cut · plays 7.1s · took 6.3s
    open 0.0s · settles 0.5s · frames 5.7s (79 captured, 346 skipped) · write 0.0s

plays is the clip’s own length and took is what the machine spent making it. They move in opposite directions when a clip gets slower to record, which is why both are named.