FramePacingReport

interface FramePacingReport

import type { FramePacingReport } from '@driftengine/core';

In depth

The measuring half is not diagnostics bolted on afterwards — it is half the reason this module exists. A clip that "judders" has at least three possible causes (the renderer missing its rate, the encoder starved of bitrate, the content itself stepping unevenly) and they are indistinguishable by eye. What separates them is a number: how many frames the loop produced, how many were handed to the recorder, and how far apart in wall-clock time those were.

The schedule counts animation frames, not milliseconds, and that is the whole design. A recorder stamps each frame with the instant it arrived, and the only instants a render loop can offer are its display's own — so a schedule expressed in wall-clock slots asks for moments that do not exist. It then takes the nearest frame either side, alternately early and late, and the file holds frames of uneven duration: 13.9 ms, 20.8 ms, 13.9 ms on a 144 Hz panel asked for 60 a second. Capturing every n-th frame instead makes every gap identical by construction, which is what makes the clip play evenly.

The rate that comes out is therefore the display's rate divided by a whole number — 60 from 60 Hz, 72 from 144, 60 from 240 — rather than exactly what was asked for. That is the right trade: a clip at 72 fps whose frames are evenly spaced is smooth, and one at exactly 60 whose frames are not is the defect this replaced.

Two rules the schedule follows, both learned from what a stutter looks like:

• Never two captures for one animation frame. A duplicated frame is a frozen instant followed by a double-length step, which reads as a hitch even though nothing was dropped. Counting frames makes this true by construction.
• After falling behind, resume — do not catch up. Firing twice in quick succession to make up a missed slot converts one gap into a lurch forward. A gap is a frame nobody notices; a lurch is the artefact everybody calls lag.

Properties