Open source CapCut alternative.
TypeScript
"use client";
import {
heapBytes,
mb,
memoryCeiling,
memoryUsage,
takeMemoryPressure,
type MemoryBucket,
type MemoryUsage,
} from "./memoryBudget";
import { logPerfRecord, notePerfTrouble, perfUploadReason, type PerfUploadReason } from "./perfLog";
import { isTextEntry } from "./shortcutGate";
/**
* What the preview actually did, frame by frame.
*
* Scrub latency and a stutter at a cut are both claims about time, and neither
* can be settled by watching. This records the two facts that settle them: when
* a time was asked for, and when a frame for that time reached the screen. From
* those, "the picture is one frame behind the pointer" and "the join dropped a
* frame" become numbers a script can hold to a budget.
*
* The trace is off until something arms it, and while it is off every call here
* is a null check. The perf eval arms it through `window.__cutPerf`, and so can
* a person on a machine we cannot reproduce: `__cutPerf.start()`, play the part
* that stutters, then `__cutPerf.report()` for a summary small enough to paste
* into a bug report. Nothing turns it on by itself.
*/
/** One composited frame that reached the canvas. */
export interface PresentRecord {
/** Timeline time the frame was composited for. */
t: number;
/** When it was painted, on the `performance.now()` clock. */
at: number;
/** Source timestamp of the master layer's picture, for spotting a frame that
* was shown twice or skipped. */
srcTs: number | null;
/**
* The source time the master layer was asked for.
*
* With `srcTs` this is how far the picture sits behind the clock it is drawn
* against. That clock is the audible one — see `audioLead` for the separate
* question of whether the preview is reading it, which this cannot see: a
* picture drawn against the wrong clock is exactly on time against it.
*/
wantSrc: number | null;
/** The clip the master picture came from, so a boundary is findable. */
clipId: string | null;
/**
* Whether the frame drawn is the one that belongs at `t`.
*
* This is the measure that matters, and it is not the same as "a new
* picture". Thirty-frame footage on a sixty-hertz display repeats every
* source frame once and is perfectly smooth; a decoder that fell behind
* repeats one too, and is not. Asking whether the source actually held the
* wanted frame tells those apart.
*/
exact: boolean;
/** True when no decoded frame existed at all and the paint fell back to
* holding or to black. A stale present never resolves a scrub. */
stale: boolean;
}
/** A time the editor was asked to show, and when it was asked for. */
export interface SeekRecord {
t: number;
at: number;
/** Engine ticks that had run when the time was asked for. The first tick
* after it is the first chance to paint the answer. */
tick: number;
/** How long until a frame for this time was painted. Null while unresolved —
* either still pending, or superseded by a later seek. */
latencyMs: number | null;
/**
* Frames the answer missed: zero when the first paint after the ask showed
* it, one when it took the next.
*
* This is the measure a drag is judged on. The milliseconds above also
* count the wait for the next frame, and that wait is the display's — half
* a frame on average, eight milliseconds at a hundred and twenty hertz and
* sixteen at sixty — so the same engine reads twice as slow on one monitor
* as on another. Frames missed reads the same on both.
*/
lateFrames: number | null;
}
export interface LongTaskRecord {
at: number;
ms: number;
}
/** A frame the browser reported as long, with the script it blames. */
export interface LongFrameRecord {
at: number;
ms: number;
/** Of that, the part no other work could run in. */
blockedMs: number;
fn: string;
src: string;
invoker: string;
scriptMs: number;
}
export interface Trace {
presents: PresentRecord[];
seeks: SeekRecord[];
longTasks: LongTaskRecord[];
/** The same stretches seen as frames, naming what held them. A long frame
* spans the task, the style pass, the layout and the paint, so its length
* is a different number from the task's and is read beside it. */
longFrames: LongFrameRecord[];
/** rAF callbacks the engine ran, for checking that an idle editor is idle. */
ticks: number;
/** Decoded frames the sources are holding open, sampled per present. */
liveSamples: number[];
/** Decoders open, sampled per present. Stood-down sources hold none, so this
* is what the pool's budget is measured against. */
liveSources: number[];
/** Sources the pool holds at all, decoder or not, sampled per present. */
keptSources: number[];
/** Megabytes of canvas backing on the warm shelf — the stood-down sources,
* which is the part the pool's memory budget governs. */
warmMb: number[];
/** Megabytes the whole editor is modeled to hold, sampled per present:
* decoders, canvases, the bytes behind them, sound and pictures. */
memMb: number[];
/**
* Seconds the picture is held behind the graph's clock, and seconds the
* output device says it holds, sampled per present.
*
* A rendered sample has not been heard yet — it is in the buffer the device
* reads next — so the moment the picture belongs at is the rendered moment
* less that buffer. These two are read independently, one from the clock the
* preview actually uses and one from the device, and they should agree. A
* lead of zero against a device reporting otherwise is the picture running
* ahead of its own sound by however much the device holds, which is tens of
* milliseconds on CoreAudio and can be a fifth of a second on shared-mode
* WASAPI or a Bluetooth output.
*/
audioLead: number[];
audioLatency: number[];
startedAt: number;
}
/**
* Records one trace keeps of each kind.
*
* The eval's runs are a fraction of this. What it bounds is a recording left
* armed on a real machine: at sixty frames a second this is around twenty
* minutes, after which the oldest records fall off and the trace describes the
* most recent stretch — which is the stretch someone recording a stutter cares
* about.
*/
const CAP = 72_000;
function keep<T>(xs: T[], x: T): void {
xs.push(x);
if (xs.length > CAP) xs.shift();
}
/** Times equal within this are the same instant. Half a frame at 120fps —
* tight enough that a real lag never passes, loose enough that float drift on
* the timeline never fails. */
const SAME_TIME = 0.004;
let trace: Trace | null = null;
let observer: PerformanceObserver | null = null;
let frameObserver: PerformanceObserver | null = null;
/** The seek still waiting for its picture. A later seek replaces it, which is
* what makes a fast drag measure the position it settled on. */
let pendingSeek: SeekRecord | null = null;
/** Whether anything is listening. The engine's hot path checks this first. */
export const tracing = () => trace !== null;
export function startTrace(): void {
trace = {
presents: [],
seeks: [],
longTasks: [],
longFrames: [],
ticks: 0,
liveSamples: [],
liveSources: [],
keptSources: [],
warmMb: [],
memMb: [],
audioLead: [],
audioLatency: [],
startedAt: performance.now(),
};
pendingSeek = null;
if (typeof PerformanceObserver === "undefined") return;
try {
observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (trace) keep(trace.longTasks, { at: entry.startTime, ms: entry.duration });
}
});
observer.observe({ entryTypes: ["longtask"] });
} catch {
// Long-task timing is Chromium-only. Its absence costs one metric, not the
// run.
observer = null;
}
// Beside it, the same stretches as frames. A long task says a frame was
// held; a long animation frame says which script held it, which is the
// question a report leads to. They are kept apart because their lengths
// mean different things and the budgets are set against the task's.
try {
frameObserver = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (!trace) continue;
const lead = leadScript(entry as LongFrameEntry);
keep(trace.longFrames, {
at: entry.startTime,
ms: entry.duration,
blockedMs: Math.round((entry as LongFrameEntry).blockingDuration ?? 0),
fn: lead?.sourceFunctionName ?? "",
src: chunkName(lead?.sourceURL),
invoker: lead?.invoker ?? "",
scriptMs: Math.round(lead?.duration ?? 0),
});
}
});
frameObserver.observe({ type: "long-animation-frame", buffered: false });
} catch {
// Long animation frames are newer than long tasks; a browser without them
// still reports the task.
frameObserver = null;
}
}
export function stopTrace(): Trace | null {
const out = trace;
observer?.disconnect();
observer = null;
frameObserver?.disconnect();
frameObserver = null;
trace = null;
pendingSeek = null;
return out;
}
/** A time was asked for — a scrub, a skim, a click on the ruler. */
export function markSeek(t: number): void {
if (!trace) return;
const rec: SeekRecord = { t, at: performance.now(), tick: trace.ticks, latencyMs: null, lateFrames: null };
keep(trace.seeks, rec);
pendingSeek = rec;
}
/** A frame reached the canvas. */
export function markPresent(rec: Omit<PresentRecord, "at">): void {
if (!trace) return;
const at = performance.now();
keep(trace.presents, { ...rec, at });
// A held or black frame is not an answer to the question the scrub asked —
// neither is the neighbouring frame drawn while the real one decodes. The
// clock keeps running until the frame that belongs at that time is on screen.
if (pendingSeek && rec.exact && !rec.stale && Math.abs(rec.t - pendingSeek.t) <= SAME_TIME) {
pendingSeek.latencyMs = at - pendingSeek.at;
// A present runs inside a tick, after the tick has counted itself; the
// first tick after the ask is the one that could have answered it.
pendingSeek.lateFrames = Math.max(0, trace.ticks - pendingSeek.tick - 1);
pendingSeek = null;
}
}
/** Whether a time has been asked for that no frame has answered yet. Lets a
* driver wait for the picture to catch up instead of guessing at a delay. */
export const awaitingFrame = () => pendingSeek !== null;
/** One turn of the engine's loop. */
export function markTick(): void {
if (!trace) return;
trace.ticks++;
}
/** What the preview's clock is doing about the output device: how far the
* picture is being held back, and how far the device says it should be. */
export function markAudioClock(lead: number, reported: number): void {
if (!trace) return;
keep(trace.audioLead, lead);
keep(trace.audioLatency, reported);
}
/** How many decoded frames are being held open right now. */
export function markLiveSamples(n: number): void {
if (!trace) return;
keep(trace.liveSamples, n);
}
/** What the decoder pool is holding right now: sources with a decoder, sources
* kept at all, and the canvas backing behind them. */
export function markLiveSources(active: number, kept: number, warmPixels: number): void {
if (!trace) return;
keep(trace.liveSources, active);
keep(trace.keptSources, kept);
keep(trace.warmMb, Math.round(warmPixels * 4e-6));
// Reading the total walks every cache that reports one, and this runs on
// every present. Sampled on the meter's cadence, for the meter's reason: a
// trace is what the perf eval judges, and a measurement that costs a frame
// has changed the thing it was measuring.
if (++traceMemTick % MEM_EVERY === 0) keep(trace.memMb, mb(memoryUsage().total));
}
let traceMemTick = 0;
/** A trace boiled down to the numbers that name a stutter. */
export interface TraceReport {
/** Seconds the recording covers, and frames painted in them. */
seconds: number;
presented: number;
/** Frames a second the preview actually held. */
fps: number;
/** Share of frames that were not the one belonging at that moment: the
* stutter, as the viewer sees it. */
late: number;
/** The same share over the first and last third, so a preview that decays
* across a session is tellable from one that was always this way. */
decay: { first: number; last: number };
/** Seconds the picture sat behind the moment asked for. */
lagP50: number;
lagP95: number;
lagMax: number;
/** Seconds the picture is held back for the output device, and what the
* device says it holds. These agree when the preview is reading the clock
* its sound leaves on; a lead of zero against a device holding a fifth of a
* second is a picture running that far ahead of its own audio. */
audioLeadS: number;
audioLatencyS: number;
/** Decoders open, frames held, and the canvas backing behind them. */
sources: number;
held: number;
warmMb: number;
/** The most the editor was modeled to be holding, in megabytes, across every
* cache that reports one. */
memMb: number;
/** The longest the main thread was blocked, in milliseconds. */
longTaskMs: number;
}
const pct = (xs: PresentRecord[]): number =>
xs.length ? +(xs.filter((p) => !p.exact || p.stale).length / xs.length).toFixed(3) : 0;
const at = (xs: number[], q: number): number => {
if (!xs.length) return 0;
const sorted = [...xs].sort((a, b) => a - b);
return +sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))].toFixed(3);
};
/** The largest of a series, walked rather than spread: these arrays run to
* CAP, which is far more arguments than a call frame takes. */
const maxOf = (xs: number[]): number => {
let m = 0;
for (const x of xs) if (x > m) m = x;
return m;
};
/** Boil a trace down to something a person can paste into a bug report. */
export function traceReport(t: Trace): TraceReport {
const presents = t.presents;
const span = presents.length ? (presents[presents.length - 1].at - presents[0].at) / 1000 : 0;
const lags = presents
.filter((p) => p.srcTs !== null && p.wantSrc !== null)
.map((p) => Math.max(0, p.wantSrc! - p.srcTs!));
const third = Math.floor(presents.length / 3);
return {
seconds: +span.toFixed(1),
presented: presents.length,
fps: span > 0 ? +(presents.length / span).toFixed(1) : 0,
late: pct(presents),
decay: { first: pct(presents.slice(0, third)), last: pct(presents.slice(-third)) },
lagP50: at(lags, 0.5),
lagP95: at(lags, 0.95),
lagMax: +maxOf(lags).toFixed(3),
audioLeadS: at(t.audioLead, 0.5),
audioLatencyS: at(t.audioLatency, 0.5),
sources: maxOf(t.liveSources),
held: maxOf(t.liveSamples),
warmMb: maxOf(t.warmMb),
memMb: maxOf(t.memMb),
longTaskMs: Math.round(maxOf(t.longTasks.map((l) => l.ms))),
};
}
/**
* The preview's own report card, for the machines we cannot reproduce.
*
* The trace above answers a question asked in a lab: a script drives the
* editor, reads every frame back, and holds the run to a budget. This answers
* the same question about someone's own machine, where nobody is driving and
* nothing can be read back — an integrated GPU with no video overlay support,
* a Windows audio buffer several times the size of CoreAudio's, a codec the
* hardware decoder does not take. Those preview badly in ways that are
* invisible here, and a driver dump only narrows the guess.
*
* So the meter counts what the trace measures, in fixed memory: a handful of
* running totals per played frame, flushed as one summary every half minute of
* playback. It is off unless the account turned it on, and while it is off the
* cost on the engine's hot path is a null check.
*
* Nothing here reads the project. No frame, no sound, no clip name, no file
* name — the numbers are timings, sizes and counts of what the machine did.
*/
/** What the decoders on this machine can do in hardware. Probed once, because
* a stutter on footage the hardware refuses is a different bug from a stutter
* on footage it takes. */
export interface DecodeCaps {
h264: boolean;
hevc: boolean;
vp9: boolean;
av1: boolean;
}
export interface PerfSample {
/** Why this session is sending — see perfLog. */
reason: PerfUploadReason;
/** Which summary this is in the session, and how long the editor had been
* open when it closed — a preview that is smooth for a minute and choppy
* after ten is two samples that say so. */
sample: number;
openedForS: number;
/** Playback this summary covers. */
seconds: number;
frames: number;
fps: number;
/** Share of frames that were not the picture belonging at that moment: the
* stutter, as the viewer sees it. */
lateShare: number;
/** Share with no decoded picture at all — the preview holding a frame. */
staleShare: number;
/** Share more than a quarter second behind: the hitches a viewer calls out. */
hitchShare: number;
/** Seconds the picture sat behind the moment asked for. */
lagMeanS: number;
lagMaxS: number;
/** Seconds the picture is held back for the output device, and what the
* device says it holds. These agree when the preview is reading the clock
* its sound leaves on; a lead of zero against a device holding a fifth of a
* second is a picture running that far ahead of its own audio. */
audioLeadS: number;
audioLatencyS: number;
/**
* Sound that missed its moment: windows the mixer had to start late, and
* the worst by how much; and the times the clock re-anchored because the
* audio graph fell away from the wall — an output that dropped out, a
* device that stalled under load. A picture that keeps time while these
* climb is the "audio cuts out" that no frame count shows.
*/
audioLate: number;
audioLateMaxS: number;
clockJumps: number;
/**
* Walks the preview started while playing, and the worst one's cost.
*
* A walk is a decoder reading forward from a keyframe, and holding on to one
* is what makes playback cheap. A window that started dozens of them is a
* reader that could not hold on to any — the picture then sits on whatever
* frame it last had while the sound runs on, which is the shape every report
* of choppy playback has turned out to be.
*/
walks: number;
walkMs: number;
/**
* The worst and the average wait for one frame off a walk, in milliseconds.
*
* This is the number that says which kind of starvation it was. A decoder
* that is merely slow answers every pull in tens of milliseconds and falls
* behind gradually; a reader whose bytes have not arrived waits seconds on
* one pull and nothing at all on the next. From the outside the two look
* identical, and the fix for them is not the same.
*/
pullMaxMs: number;
pullMeanMs: number;
/** The file behind the picture: what it really is, which `decodeHeight` —
* the height the preview asked for — cannot say. A frame rate above thirty
* halves what a fixed lookahead buys, and a size far above the stage says
* the decode is paying for pixels nothing shows. */
srcW: number;
srcH: number;
srcFps: number;
srcCodec: string;
/** What the preview was holding open at its peak. */
sources: number;
heldFrames: number;
warmMb: number;
/** Main thread blocked: the worst one, and how many there were. */
longTaskMs: number;
longTasks: number;
/** The shape of the cut and the size of the picture, since both decide how
* much work a frame is. */
clips: number;
decodeHeight: number;
canvasHeight: number;
dpr: number;
/**
* The worst the memory got during the window, modeled in megabytes: the
* total, where it went, and what this machine allows. A preview that
* stutters against a total sitting on its ceiling is a different fault from
* one that stutters with room to spare, and only the pair says which.
*/
memMb: number;
memCeilingMb: number;
decoderMb: number;
canvasMb: number;
readMb: number;
audioMb: number;
pictureMb: number;
/** The JavaScript heap at its worst, where the browser reports one. */
heapMb: number;
/** Buckets the ceiling sized: the machine is what is holding them down. */
memBound: string;
/** What the machine brought. */
cores: number;
memoryGb: number;
hwH264: boolean;
hwHevc: boolean;
hwVp9: boolean;
hwAv1: boolean;
}
/** Playback frames in one summary: about half a minute at sixty a second. */
const SAMPLE_FRAMES = 1800;
/** Fewest frames worth reporting when a play ends early. */
const SAMPLE_MIN_FRAMES = 240;
/** Summaries one editor session will send. A day-long session is interesting
* for its first few, and this is not a firehose. */
const SAMPLE_CAP = 8;
/** A frame this far behind is a hitch a person would name. */
const HITCH_S = 0.25;
/** A play with this share of hitches, or a picture this far behind its sound,
* is trouble the session sends about — see perfLog for what that starts. */
const TROUBLE_HITCH_SHARE = 0.2;
const TROUBLE_LAG_S = 1;
/** Sound starting late this many times in one window, or the clock
* re-anchoring this many, is trouble too. */
const TROUBLE_AUDIO_LATE = 3;
const TROUBLE_CLOCK_JUMPS = 2;
interface Meter {
frames: number;
late: number;
stale: number;
hitches: number;
lagSum: number;
lagMax: number;
walks: number;
walkMs: number;
pullMax: number;
pullSum: number;
pulls: number;
srcW: number;
srcH: number;
srcFps: number;
srcCodec: string;
audioLead: number;
audioLatency: number;
audioLate: number;
audioLateMax: number;
clockJumps: number;
sources: number;
held: number;
warmMb: number;
memBytes: number;
usage: MemoryUsage;
heapBytes: number;
bound: Set<MemoryBucket>;
longTaskMs: number;
longTasks: number;
clips: number;
decodeHeight: number;
canvasHeight: number;
startedAt: number;
}
let meter: Meter | null = null;
let sink: ((sample: PerfSample) => void) | null = null;
let sampleCount = 0;
let openedAt = 0;
let caps: DecodeCaps = { h264: false, hevc: false, vp9: false, av1: false };
const emptyMeter = (): Meter => ({
frames: 0,
late: 0,
stale: 0,
hitches: 0,
lagSum: 0,
lagMax: 0,
walks: 0,
walkMs: 0,
pullMax: 0,
pullSum: 0,
pulls: 0,
srcW: 0,
srcH: 0,
srcFps: 0,
srcCodec: "",
audioLead: 0,
audioLatency: 0,
audioLate: 0,
audioLateMax: 0,
clockJumps: 0,
sources: 0,
held: 0,
warmMb: 0,
memBytes: 0,
usage: { decoders: 0, canvases: 0, reads: 0, audio: 0, pictures: 0, total: 0 },
heapBytes: 0,
bound: new Set(),
longTaskMs: 0,
longTasks: 0,
clips: 0,
decodeHeight: 0,
canvasHeight: 0,
startedAt: performance.now(),
});
/** Whether anything is counting. The engine's hot path checks this first. */
export const metering = (): boolean => meter !== null;
/**
* Start counting, and send each summary to `report`.
*
* Calling again replaces the sink and leaves the counts alone, so a flag read
* that resolves twice does not restart the session's numbering.
*/
export function meterPerf(report: (sample: PerfSample) => void): void {
sink = report;
if (meter) return;
openedAt = performance.now();
meter = emptyMeter();
void probeDecodeCaps();
}
/** Stop counting and forget the sink. */
export function stopMeter(): void {
meter = null;
sink = null;
}
/** One played frame: how far behind the moment asked for the picture was, and
* whether there was a decoded picture for it at all. */
export function meterFrame(lagS: number, stale: boolean): void {
if (!meter) return;
meter.frames++;
if (stale) meter.stale++;
if (stale || lagS > SAME_TIME) meter.late++;
if (lagS > HITCH_S) meter.hitches++;
meter.lagSum += lagS;
meter.lagMax = Math.max(meter.lagMax, lagS);
if (meter.frames >= SAMPLE_FRAMES) flushMeter();
}
/** What the preview is holding open, and the size it is working at. */
export function meterState(state: {
sources: number;
held: number;
warmMb: number;
clips: number;
decodeHeight: number;
canvasHeight: number;
}): void {
if (!meter) return;
meter.sources = Math.max(meter.sources, state.sources);
meter.held = Math.max(meter.held, state.held);
meter.warmMb = Math.max(meter.warmMb, state.warmMb);
meter.clips = Math.max(meter.clips, state.clips);
meter.decodeHeight = state.decodeHeight;
meter.canvasHeight = state.canvasHeight;
// Every caller of this is on the frame path, and reading the memory total
// walks every cache that reports one. Twice a second is often enough to
// catch a peak that lasts long enough to matter and rare enough that the
// walk never shows up in a frame.
if (++memTick % MEM_EVERY) return;
for (const b of takeMemoryPressure()) meter.bound.add(b);
const usage = memoryUsage();
if (usage.total > meter.memBytes) {
meter.memBytes = usage.total;
meter.usage = usage;
}
meter.heapBytes = Math.max(meter.heapBytes, heapBytes());
}
/** Frames between memory reads — see `meterState`. */
const MEM_EVERY = 30;
let memTick = 0;
/** A walk was anchored, and — once it lands — what reaching its first frame
* cost. Counted only while playing, since a scrub anchors walks by design. */
export function meterWalk(costMs?: number): void {
if (!meter) return;
if (costMs === undefined) meter.walks++;
else meter.walkMs = Math.max(meter.walkMs, Math.round(costMs));
}
/** How long one pull waited for its frame. */
export function meterPull(ms: number): void {
if (!meter) return;
meter.pulls++;
meter.pullSum += ms;
meter.pullMax = Math.max(meter.pullMax, ms);
}
/** The shape of the file a landed frame came from. */
export function meterSource(
width: number,
height: number,
fps: number,
codec: string
): void {
if (!meter || !(fps > 0)) return;
meter.srcW = Math.max(meter.srcW, Math.round(width));
meter.srcH = Math.max(meter.srcH, Math.round(height));
meter.srcFps = Math.max(meter.srcFps, Math.round(fps));
// A machine that decodes H.264 in hardware and refuses AV1 runs the same
// preview two entirely different ways, and the size and rate of the file
// cannot tell those apart. This is the field that does.
if (codec) meter.srcCodec = codec;
}
/** What the preview's clock is doing about the output device. */
export function meterAudioClock(lead: number, reported: number): void {
if (!meter) return;
meter.audioLead = Math.max(meter.audioLead, lead);
meter.audioLatency = Math.max(meter.audioLatency, reported);
}
/** A window of sound started after the moment it was for, by `lateS`. */
export function meterAudioLate(lateS: number): void {
if (!meter) return;
meter.audioLate++;
meter.audioLateMax = Math.max(meter.audioLateMax, lateS);
}
/** The mixer re-anchored its clock: the audio graph had fallen away from the
* wall, and everything scheduled was torn down and refilled. */
export function meterClockJump(): void {
if (!meter) return;
meter.clockJumps++;
}
/**
* Send what has been counted and start a fresh count.
*
* A play that ends before the window fills still reports, because a short play
* that stuttered is the whole complaint; a handful of frames is noise and is
* dropped instead.
*/
export function flushMeter(): void {
const m = meter;
if (!m || !sink) return;
meter = emptyMeter();
// Trouble is read before the window is judged too short to report. A play
// that froze draws few frames — the thread was blocked — so the shortest
// windows are the ones carrying the worst news.
if (
(m.frames > 0 && m.hitches / m.frames >= TROUBLE_HITCH_SHARE) ||
m.lagMax >= TROUBLE_LAG_S ||
m.audioLate >= TROUBLE_AUDIO_LATE ||
m.clockJumps >= TROUBLE_CLOCK_JUMPS
)
notePerfTrouble();
if (m.frames < SAMPLE_MIN_FRAMES) return;
const reason = perfUploadReason();
if (!reason || sampleCount >= SAMPLE_CAP) return;
const seconds = (performance.now() - m.startedAt) / 1000;
const round = (n: number, places = 3) => +n.toFixed(places);
sink({
reason,
sample: ++sampleCount,
openedForS: Math.round((performance.now() - openedAt) / 1000),
seconds: round(seconds, 1),
frames: m.frames,
fps: seconds > 0 ? round(m.frames / seconds, 1) : 0,
lateShare: round(m.late / m.frames),
staleShare: round(m.stale / m.frames),
hitchShare: round(m.hitches / m.frames),
lagMeanS: round(m.lagSum / m.frames),
lagMaxS: round(m.lagMax),
audioLeadS: round(m.audioLead),
audioLatencyS: round(m.audioLatency),
audioLate: m.audioLate,
audioLateMaxS: round(m.audioLateMax),
clockJumps: m.clockJumps,
walks: m.walks,
walkMs: m.walkMs,
pullMaxMs: Math.round(m.pullMax),
pullMeanMs: m.pulls ? Math.round(m.pullSum / m.pulls) : 0,
srcW: m.srcW,
srcH: m.srcH,
srcFps: m.srcFps,
srcCodec: m.srcCodec,
sources: m.sources,
heldFrames: m.held,
warmMb: m.warmMb,
memMb: mb(m.memBytes),
memCeilingMb: mb(memoryCeiling()),
decoderMb: mb(m.usage.decoders),
canvasMb: mb(m.usage.canvases),
readMb: mb(m.usage.reads),
audioMb: mb(m.usage.audio),
pictureMb: mb(m.usage.pictures),
heapMb: mb(m.heapBytes),
memBound: [...m.bound].join(","),
longTaskMs: m.longTaskMs,
longTasks: m.longTasks,
clips: m.clips,
decodeHeight: m.decodeHeight,
canvasHeight: m.canvasHeight,
dpr: typeof devicePixelRatio === "number" ? round(devicePixelRatio, 2) : 1,
cores: navigator.hardwareConcurrency || 0,
memoryGb: (navigator as unknown as { deviceMemory?: number }).deviceMemory ?? 0,
hwH264: caps.h264,
hwHevc: caps.hevc,
hwVp9: caps.vp9,
hwAv1: caps.av1,
});
}
/**
* Which codecs this machine decodes in hardware, at 1080p.
*
* The answer separates two very different stutters. A machine that takes the
* footage in hardware and still drops frames is spending its time somewhere
* after the decoder — converting frames, uploading them, compositing. A
* machine whose decoder refuses the codec is running every stream on the CPU,
* where a fast cut has no chance. Both look identical from the outside.
*/
async function probeDecodeCaps(): Promise<void> {
if (typeof VideoDecoder === "undefined") return;
const ask = async (codec: string): Promise<boolean> => {
try {
const support = await VideoDecoder.isConfigSupported({
codec,
codedWidth: 1920,
codedHeight: 1080,
hardwareAcceleration: "prefer-hardware",
});
return support.supported === true;
} catch {
return false;
}
};
const [h264, hevc, vp9, av1] = await Promise.all([
ask("avc1.640028"),
ask("hvc1.1.6.L120.90"),
ask("vp09.00.41.08"),
ask("av01.0.09M.08"),
]);
caps = { h264, hevc, vp9, av1 };
}
/**
* The main thread's report card, for the freezes that happen between plays.
*
* The meter above counts what the preview did per played frame, so it says
* nothing about a delete that took two seconds to land or an import that
* froze the page. This watches the thread itself: every animation frame the
* browser reports as long, with the script that ran it and what it was
* invoked by — the one attribution a person's own machine can give, since the
* profiler is never open when it happens.
*
* Long animation frames are Chromium's. Where the API is missing the long
* task list stands in, which names the cost and nothing about its cause.
*
* Nothing here reads the project. The script names are the page's own
* bundle; the "input" beside a frame is which control was pressed — a button's
* label, a key's name — and a key pressed into a text field is reported as
* text, never as the character.
*/
export interface MainThreadSample {
/** Why this session is sending — see perfLog. */
reason: PerfUploadReason;
sample: number;
openedForS: number;
/** Wall seconds this summary covers. */
seconds: number;
/** Frames the thread was blocked in, milliseconds blocked across them, and
* the longest of them. */
longFrames: number;
blockedMs: number;
worstMs: number;
/** The worst frame: how it split between script and layout, what invoked
* the script, and where in the bundle it lives. */
worstScriptMs: number;
worstLayoutMs: number;
worstInvoker: string;
worstFn: string;
worstSrc: string;
worstChar: number;
/** What the editor was doing when the worst frame hit, and what was pressed
* last, how long before. */
worstActivity: MainThreadActivity;
worstInput: string;
worstInputAgoMs: number;
/** The three scripts that blocked longest across the window, as
* "invoker>function:ms", pipe-separated. */
top: string;
/** The size of the cut at flush time. */
clips: number;
audioClips: number;
overlays: number;
assets: number;
cores: number;
memoryGb: number;
}
export type MainThreadActivity = "playing" | "dragging" | "idle";
/** What the editor tells the meter about itself when a frame lands. */
export interface MainThreadContext {
activity: MainThreadActivity;
clips: number;
audioClips: number;
overlays: number;
assets: number;
}
/** A long-animation-frame entry, as Chromium reports it. The lib has no
* type for it yet. */
interface LongFrameEntry extends PerformanceEntry {
blockingDuration?: number;
renderStart?: number;
styleAndLayoutStart?: number;
scripts?: LongFrameScript[];
}
interface LongFrameScript {
duration: number;
invoker?: string;
sourceURL?: string;
sourceFunctionName?: string;
sourceCharPosition?: number;
}
interface WorstFrame {
ms: number;
scriptMs: number;
layoutMs: number;
invoker: string;
fn: string;
src: string;
char: number;
activity: MainThreadActivity;
input: string;
inputAgoMs: number;
}
interface ThreadMeter {
longFrames: number;
blockedMs: number;
worst: WorstFrame | null;
/** Blocked milliseconds per "invoker>function", for the top list. */
byScript: Map<string, number>;
startedAt: number;
}
/** A window this long is one summary. */
const THREAD_FLUSH_MS = 30_000;
/** A window whose worst frame is under this reports nothing, and a frame
* under it is not kept in the log: a page that is merely busy is not the
* complaint. */
const THREAD_REPORT_MS = 100;
/** Summaries one editor session will send. */
const THREAD_SAMPLE_CAP = 8;
/** A single frame this long, or a window blocked for this long in total, is
* trouble the session sends about — see perfLog for what that starts. */
const TROUBLE_FRAME_MS = 1_000;
const TROUBLE_WINDOW_MS = 3_000;
/** An input older than this is not what a frame is answering. */
const INPUT_RECENT_MS = 5_000;
let threadMeter: ThreadMeter | null = null;
let threadSink: ((sample: MainThreadSample) => void) | null = null;
let threadContext: (() => MainThreadContext) | null = null;
let threadObserver: PerformanceObserver | null = null;
let threadTimer: ReturnType<typeof setInterval> | null = null;
let threadSamples = 0;
let threadOpenedAt = 0;
let lastInput: { at: number; what: string } | null = null;
let removeInputWatch: (() => void) | null = null;
const emptyThreadMeter = (): ThreadMeter => ({
longFrames: 0,
blockedMs: 0,
worst: null,
byScript: new Map(),
startedAt: performance.now(),
});
/** The last path segment of a bundle URL — the chunk's name, which is what a
* source map resolves against. */
const chunkName = (url: string | undefined): string => {
if (!url) return "";
const path = url.split(/[?#]/)[0];
return path.slice(path.lastIndexOf("/") + 1);
};
/**
* Which control an input landed on, read from the page's structure: a
* timeline selection's kind, the component slots around it, the tag and an
* input's type — every one of them a literal in this codebase.
*
* Nothing the page displays goes in. A label or a button's text carries what
* the person named, wrote, or was shown — a file name, a project, another
* user's email — and a performance record is no place for any of it.
*/
function describeTarget(target: EventTarget | null): string {
const el = target instanceof Element ? target : null;
if (!el) return "";
const sel = el.closest<HTMLElement>("[data-tl-sel]");
if (sel) return `timeline:${(sel.dataset.tlSel ?? "").split(":")[0]}`;
const self = el instanceof HTMLInputElement ? `input:${el.type}` : el.tagName.toLowerCase();
const slots: string[] = [];
for (let node: Element | null = el; node && slots.length < 2; node = node.parentElement) {
const slot = node instanceof HTMLElement ? node.dataset.slot : undefined;
if (slot) slots.unshift(slot);
}
return slots.length ? `${slots.join(">")} ${self}` : self;
}
function watchInputs(): () => void {
const onPointer = (e: PointerEvent) => {
lastInput = { at: performance.now(), what: `press ${describeTarget(e.target)}` };
};
const onKey = (e: KeyboardEvent) => {
const mods = [e.ctrlKey && "ctrl", e.metaKey && "cmd", e.altKey && "alt", e.shiftKey && "shift"]
.filter(Boolean)
.join("+");
const key = isTextEntry(e.target) ? "text" : e.key.length === 1 ? e.key.toLowerCase() : e.key;
lastInput = { at: performance.now(), what: `key ${mods ? `${mods}+` : ""}${key}` };
};
window.addEventListener("pointerdown", onPointer, true);
window.addEventListener("keydown", onKey, true);
return () => {
window.removeEventListener("pointerdown", onPointer, true);
window.removeEventListener("keydown", onKey, true);
};
}
/** The script that held a frame the longest, of those the browser named. */
function leadScript(entry: LongFrameEntry): LongFrameScript | null {
let lead: LongFrameScript | null = null;
for (const s of entry.scripts ?? []) if (!lead || s.duration > lead.duration) lead = s;
return lead;
}
function noteLongFrame(entry: LongFrameEntry): void {
const m = threadMeter;
if (!m) return;
const ms = entry.duration;
const blocked = entry.blockingDuration ?? Math.max(0, ms - 50);
m.longFrames++;
m.blockedMs += blocked;
if (meter) {
meter.longTasks++;
meter.longTaskMs = Math.max(meter.longTaskMs, Math.round(ms));
}
const scripts = entry.scripts ?? [];
let scriptMs = 0;
const lead = leadScript(entry);
for (const s of scripts) {
scriptMs += s.duration;
const fn = s.sourceFunctionName || chunkName(s.sourceURL);
const key = `${s.invoker ?? ""}>${fn}`;
m.byScript.set(key, (m.byScript.get(key) ?? 0) + s.duration);
}
const end = entry.startTime + ms;
const layoutMs =
entry.styleAndLayoutStart && entry.styleAndLayoutStart > 0 ? end - entry.styleAndLayoutStart : 0;
if (ms < THREAD_REPORT_MS && m.worst) return;
const at = performance.now();
const recent = lastInput && at - lastInput.at <= INPUT_RECENT_MS + ms ? lastInput : null;
const frame: WorstFrame = {
ms,
scriptMs,
layoutMs,
invoker: lead?.invoker ?? "",
fn: lead?.sourceFunctionName ?? "",
src: chunkName(lead?.sourceURL),
char: lead?.sourceCharPosition ?? -1,
activity: threadContext?.().activity ?? "idle",
input: recent?.what ?? "",
inputAgoMs: recent ? Math.max(0, Math.round(entry.startTime - recent.at)) : -1,
};
if (ms >= TROUBLE_FRAME_MS) notePerfTrouble();
if (ms >= THREAD_REPORT_MS) {
logPerfRecord({
at: Math.round(performance.timeOrigin + entry.startTime),
ms: Math.round(ms),
blockedMs: Math.round(blocked),
scriptMs: Math.round(scriptMs),
layoutMs: Math.round(layoutMs),
invoker: frame.invoker,
fn: frame.fn,
src: frame.src,
char: frame.char,
activity: frame.activity,
input: frame.input,
inputAgoMs: frame.inputAgoMs,
});
}
if (!m.worst || ms > m.worst.ms) m.worst = frame;
}
/** Whether the main thread is being watched. */
export const meteringMainThread = (): boolean => threadMeter !== null;
/**
* Start watching the main thread, sending each summary to `report` with what
* `context` says the editor was doing. Calling again replaces both and leaves
* the counts alone.
*/
export function meterMainThread(
report: (sample: MainThreadSample) => void,
context: () => MainThreadContext
): void {
threadSink = report;
threadContext = context;
if (threadMeter) return;
if (typeof PerformanceObserver === "undefined") return;
const types = PerformanceObserver.supportedEntryTypes ?? [];
const type = types.includes("long-animation-frame")
? "long-animation-frame"
: types.includes("longtask")
? "longtask"
: null;
if (!type) return;
threadOpenedAt = performance.now();
threadMeter = emptyThreadMeter();
try {
threadObserver = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) noteLongFrame(entry as LongFrameEntry);
});
threadObserver.observe({ type });
} catch {
threadObserver = null;
threadMeter = null;
return;
}
removeInputWatch = watchInputs();
threadTimer = setInterval(flushMainThreadMeter, THREAD_FLUSH_MS);
}
/** Send what has been counted and start a fresh window. A window with no
* frame worth naming sends nothing. */
export function flushMainThreadMeter(): void {
const m = threadMeter;
if (!m || !threadSink) return;
threadMeter = emptyThreadMeter();
// A window blocked for seconds is trouble however it got there: one long
// frame, or a hundred medium ones that never reach the reporting bar.
if (m.blockedMs >= TROUBLE_WINDOW_MS) notePerfTrouble();
const worst = m.worst;
if (!worst || worst.ms < THREAD_REPORT_MS) return;
const reason = perfUploadReason();
if (!reason || threadSamples >= THREAD_SAMPLE_CAP) return;
const ctx = threadContext?.() ?? { activity: "idle", clips: 0, audioClips: 0, overlays: 0, assets: 0 };
const top = [...m.byScript.entries()]
.sort((a, b) => b[1] - a[1])
.slice(0, 3)
.map(([key, ms]) => `${key}:${Math.round(ms)}`)
.join(" | ");
threadSink({
reason,
sample: ++threadSamples,
openedForS: Math.round((performance.now() - threadOpenedAt) / 1000),
seconds: +((performance.now() - m.startedAt) / 1000).toFixed(1),
longFrames: m.longFrames,
blockedMs: Math.round(m.blockedMs),
worstMs: Math.round(worst.ms),
worstScriptMs: Math.round(worst.scriptMs),
worstLayoutMs: Math.round(worst.layoutMs),
worstInvoker: worst.invoker,
worstFn: worst.fn,
worstSrc: worst.src,
worstChar: worst.char,
worstActivity: worst.activity,
worstInput: worst.input,
worstInputAgoMs: worst.inputAgoMs,
top,
clips: ctx.clips,
audioClips: ctx.audioClips,
overlays: ctx.overlays,
assets: ctx.assets,
cores: navigator.hardwareConcurrency || 0,
memoryGb: (navigator as unknown as { deviceMemory?: number }).deviceMemory ?? 0,
});
}
/** Stop watching, sending the window in hand first. */
export function stopMainThreadMeter(): void {
flushMainThreadMeter();
if (threadTimer) clearInterval(threadTimer);
threadTimer = null;
threadObserver?.disconnect();
threadObserver = null;
removeInputWatch?.();
removeInputWatch = null;
threadMeter = null;
threadSink = null;
threadContext = null;
lastInput = null;
}