Skip to content

Open source CapCut alternative.

TypeScript

feat(site): the diagnostics carry what the editor is holding

David Le03ca7798c8e5
diff --git a/site/scripts/eval-cut-perf.ts b/site/scripts/eval-cut-perf.ts
index 730b8856..bae954e6 100644
--- a/site/scripts/eval-cut-perf.ts
+++ b/site/scripts/eval-cut-perf.ts
@@ -236,6 +236,12 @@ const BASE_GATE = {
// churn for memory, and this is the side of that trade a change could
// quietly blow.
warmMb: 400,
+ // Everything the editor is modeled to be holding, not the shelf alone:
+ // decoders, every canvas behind them, the file bytes they were decoded from,
+ // sound and pictures. The shelf's own number says nothing about a change
+ // that moves memory from the shelf into a cache beside it, and this is the
+ // total a machine actually has to find.
+ memMb: 1600,
};
/** The budget this run is judged against: the tight one, with the picture-lag
@@ -298,6 +304,7 @@ interface Trace {
liveSources: number[];
keptSources: number[];
warmMb: number[];
+ memMb: number[];
audioLead: number[];
audioLatency: number[];
startedAt: number;
@@ -858,6 +865,8 @@ interface CaseResult {
longTasks?: Agg;
liveSamples?: number;
liveSources?: number;
+ /** What the editor was modeled to be holding at its peak, in megabytes. */
+ memMb?: number;
/** Sources the pool kept, and the canvas backing on its warm shelf. */
keptSources?: number;
warmMb?: number;
@@ -1227,6 +1236,8 @@ async function judgePlay(
}
const warmMb = Math.max(0, ...trace.warmMb);
if (warmMb > GATE.warmMb) notes.push(`warm shelf holding ${warmMb}MB of canvas`);
+ const memMb = Math.max(0, ...(trace.memMb ?? []));
+ if (memMb > GATE.memMb) notes.push(`editor holding ${memMb}MB`);
// Long tasks are reported, not gated: this case judges sync, decay and
// memory, and the stray dev-build hiccup that leaves every frame exact is
// not a fail.
@@ -1246,6 +1257,7 @@ async function judgePlay(
liveSources: Math.max(0, ...trace.liveSources),
keptSources: Math.max(0, ...trace.keptSources),
warmMb,
+ memMb,
decoders: decoders ?? undefined,
machine: MACHINE.name,
};
@@ -2400,7 +2412,7 @@ const detailOf = (r: CaseResult) =>
: r.idleTicks !== undefined
? `ticks=${r.idleTicks}`
: r.lag
- ? `late=${r.drops}/${r.presented} lagP95=${r.lag.p95}s hitch=${((r.stallShare ?? 0) * 100).toFixed(1)}% lagMax=${r.lag.max}s sources=${r.liveSources} sw=${r.decoders?.softwarePeak ?? "-"}/${r.decoders?.software ?? "-"} busy=${r.decoders?.busyPeak ?? "-"} clock=${Math.round((r.clock?.lead ?? 0) * 1000)}/${Math.round((r.clock?.reported ?? 0) * 1000)}ms warm=${r.warmMb}MB decay=${r.decay?.first}→${r.decay?.last}`
+ ? `late=${r.drops}/${r.presented} lagP95=${r.lag.p95}s hitch=${((r.stallShare ?? 0) * 100).toFixed(1)}% lagMax=${r.lag.max}s sources=${r.liveSources} sw=${r.decoders?.softwarePeak ?? "-"}/${r.decoders?.software ?? "-"} busy=${r.decoders?.busyPeak ?? "-"} clock=${Math.round((r.clock?.lead ?? 0) * 1000)}/${Math.round((r.clock?.reported ?? 0) * 1000)}ms warm=${r.warmMb}MB mem=${r.memMb}MB decay=${r.decay?.first}→${r.decay?.last}`
: `late=${r.drops}/${r.presented} atCut=${r.boundaryDrops}`;
async function main(): Promise<void> {
diff --git a/site/src/cut/lib/perfLog.ts b/site/src/cut/lib/perfLog.ts
index ec6d1356..3235bfa7 100644
--- a/site/src/cut/lib/perfLog.ts
+++ b/site/src/cut/lib/perfLog.ts
@@ -29,6 +29,8 @@
* which control was pressed — see perfTrace's meter for what is kept out.
*/
+import { heapBytes, mb, memoryCeiling, memoryTotalCached, memoryUsage } from "./memoryBudget";
+
export interface PerfLogRecord {
/** Monotonic across page loads on this machine, so a batch sent twice —
* once by a beacon that did land, once by the next open that could not
@@ -49,6 +51,12 @@ export interface PerfLogRecord {
activity: string;
input: string;
inputAgoMs: number;
+ /** What the editor was holding when the frame blocked, modeled in megabytes.
+ * A machine short of memory stalls for a page fault, which looks from here
+ * exactly like a machine short of processor — this is what tells them
+ * apart. Absent on records a build before this one wrote and left in
+ * storage. */
+ memMb?: number;
}
export interface PerfLogBatch {
@@ -60,6 +68,11 @@ export interface PerfLogBatch {
records: PerfLogRecord[];
cores: number;
memoryGb: number;
+ /** What the editor is holding as this sends, what it is allowed to hold on
+ * this machine, and what the JavaScript heap says — see `memoryBudget`. */
+ memMb: number;
+ memCeilingMb: number;
+ heapMb: number;
}
/** Why a session uploads: it drew the sample, or it saw trouble. */
@@ -160,10 +173,10 @@ function scheduleWrite(): void {
}
/** Keep one frame. Cheap enough to call from a performance observer. */
-export function logPerfRecord(rec: Omit<PerfLogRecord, "id" | "open">): void {
+export function logPerfRecord(rec: Omit<PerfLogRecord, "id" | "open" | "memMb">): void {
if (typeof window === "undefined") return;
const s = load();
- s.records.push({ ...rec, open: openedAt, id: s.nextId++ });
+ s.records.push({ ...rec, open: openedAt, id: s.nextId++, memMb: mb(memoryTotalCached()) });
if (s.records.length > CAP) s.records.splice(0, s.records.length - CAP);
scheduleWrite();
}
@@ -201,6 +214,7 @@ export function drainPerfLog(): void {
const of = Math.ceil(pending.length / BATCH);
const cores = navigator.hardwareConcurrency || 0;
const memoryGb = (navigator as unknown as { deviceMemory?: number }).deviceMemory ?? 0;
+ const usage = memoryUsage();
for (let i = 0; i < of; i++) {
sink({
batch: i + 1,
@@ -209,6 +223,9 @@ export function drainPerfLog(): void {
records: pending.slice(i * BATCH, (i + 1) * BATCH),
cores,
memoryGb,
+ memMb: mb(usage.total),
+ memCeilingMb: mb(memoryCeiling()),
+ heapMb: mb(heapBytes()),
});
}
s.sentThrough = pending[pending.length - 1].id;
diff --git a/site/src/cut/lib/perfTrace.ts b/site/src/cut/lib/perfTrace.ts
index bcc10df7..2440e860 100644
--- a/site/src/cut/lib/perfTrace.ts
+++ b/site/src/cut/lib/perfTrace.ts
@@ -1,5 +1,14 @@
"use client";
+import {
+ heapBytes,
+ mb,
+ memoryCeiling,
+ memoryUsage,
+ takeMemoryPressure,
+ type MemoryBucket,
+ type MemoryUsage,
+} from "./memoryBudget";
import { logPerfRecord, notePerfTrouble, perfUploadReason, type PerfUploadReason } from "./perfLog";
/**
@@ -83,6 +92,9 @@ export interface Trace {
/** 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.
@@ -141,6 +153,7 @@ export function startTrace(): void {
liveSources: [],
keptSources: [],
warmMb: [],
+ memMb: [],
audioLead: [],
audioLatency: [],
startedAt: performance.now(),
@@ -223,8 +236,15 @@ export function markLiveSources(active: number, kept: number, warmPixels: number
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. */
@@ -252,6 +272,9 @@ export interface TraceReport {
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;
}
@@ -295,6 +318,7 @@ export function traceReport(t: Trace): TraceReport {
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))),
};
}
@@ -410,6 +434,23 @@ export interface PerfSample {
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;
@@ -461,6 +502,10 @@ interface Meter {
sources: number;
held: number;
warmMb: number;
+ memBytes: number;
+ usage: MemoryUsage;
+ heapBytes: number;
+ bound: Set<MemoryBucket>;
longTaskMs: number;
longTasks: number;
clips: number;
@@ -499,6 +544,10 @@ const emptyMeter = (): Meter => ({
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,
@@ -559,8 +608,24 @@ export function meterState(state: {
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 {
@@ -669,6 +734,15 @@ export function flushMeter(): void {
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,