Open source CapCut alternative.
TypeScript
docs: performance guide
David Leaeddf2f792f6
diff --git a/docs/README.md b/docs/README.mdindex a9b06cf7..d915ce0f 100644--- a/docs/README.md+++ b/docs/README.md@@ -16,6 +16,7 @@ Supported product and engineering guides live in `docs/guides/`. This list is th- [Donkey Cut's AI Assistant](guides/cut/ai-assistant.md) — how a chat turn runs: the providers, the tool bridge into the editor, what the model knows, and the context budgets.- [Brief to Video](guides/cut/brief-to-video.md) — the director pipeline's strategy: story planning, the identity ladder that keeps a cast consistent, and where audio goes next.- [Local Compute](guides/cut/local-compute.md) — why a project the engine doesn't store still uses the Mac when there is one, and the rule that keeps its data where it lives regardless.+- [Performance](guides/performance.md) — the frame budget, the four ways we keep the main thread clear, the memory budget, and how a change is measured before it ships.**Site and backend**diff --git a/docs/guides/performance.md b/docs/guides/performance.mdnew file mode 100644index 00000000..8a1672ee--- /dev/null+++ b/docs/guides/performance.md@@ -0,0 +1,130 @@+# Performance++Donkey Cut has to feel instant on the laptops people edit on. The editor lives in one+browser tab, and that tab has one main thread: it runs our scripts, lays out the page, and+paints every frame. When that thread is busy, the picture freezes, the playhead sticks,+and a click waits. Every feature we ship is judged first by what it costs that thread and+the machine's memory, and only then by what it adds.++**The one rule:** work scales with what is on screen and what the person is doing, never+with the size of the project. If you are tempted to loop over every clip on every frame,+or decode a file nobody is looking at, that work belongs behind the visible part or+nowhere at all.++## The frame budget++The browser draws a frame only between our tasks. At 60Hz a frame has about 10ms for our+code; at 120Hz, about 5ms. A task that runs longer than that skips frames, and one that+runs past 50ms is a long task the browser reports as a stall.++The code that stalls is rarely slow on its own. It is whatever happens to be holding the+thread when a frame was due. So the questions to ask of any change are the same two: how+long does this hold the thread at once, and how often.++The model for this section, and for the split, batch, defer and move techniques below, is+[The Expensive Main Thread](https://kciter.so/posts/the-expensive-main-thread/en/).++## Techniques++We keep the thread clear four ways, in the order to reach for them.++| Technique | What it means | Where Cut does it |+| --- | --- | --- |+| Remove | Do not do the work at all: cache the answer, draw only what shows, skip what nothing reads | The preview answers every frame from a ring of already-decoded frames; the timeline draws the visible span; a background tab lets its decoders go |+| Move | Take it off the main thread: the compositor for motion, the GPU for pixels, a hidden or headless surface for whole jobs | The skim line moves by a transform on its own compositor layer; grades and masks run as GPU passes; rendering and transcription go to the engine or the cloud worker |+| Defer | Do it later, when the thread is quiet | Waveforms, filmstrips and scene probes wait for play to stop; the perf log reaches storage at idle |+| Split and batch | Break a long job into steps that yield between frames, and fold bursts of events into one run | Cutout bakes run in bounded chunks; drag and scroll handlers coalesce into the next animation frame; saves and search debounce |++**Remove first.** A cache that answers in memory beats any amount of scheduling. The+preview is the model: playing walks each file forward and keeps frames ahead of the+playhead, so drawing is a lookup and never a wait. If the exact frame is not there yet,+the nearest decoded one goes up. A held frame is worth more than a stall.++**Then move.** Anything that animates every frame moves by CSS transform so the+compositor carries it while the thread is busy. Anything that touches many pixels runs on+the GPU. Anything that is a whole job, like an export, leaves the tab.++**Then defer.** A play is the urgent read. Everything that opens the same file for+another reason takes what the picture needs, so it waits until the play stops and picks up+where it was.++**Split last.** Yielding has a cost of its own, and some work cannot be cut, so split+only what remains after the three above. Yield by time against the frame budget, and+never so finely that the switching costs more than the work.++## Rules++1. **One animation frame per tick.** The frame loop books exactly one request per tick+ and everything that draws hangs off it. A second loop doubles the work and fights the+ first for the same frame.+2. **Nothing synchronous in a hot path.** No decode, no layout read, no storage call+ inside the frame loop, a pointer handler, or a scroll handler. Read layout once, before+ the loop starts.+3. **No allocation per frame.** Rings, buffers and canvases are made once and reused. A+ fresh canvas per reopen floods the GPU process until frames stop arriving.+4. **Every cache is bounded in bytes.** A cache registers what it holds with the memory+ budget and asks what it may hold. The answer is the smaller of its tuned size and its+ share of a quarter of the machine's memory, so on a small machine every cache sheds+ together and no one subsystem eats the room the others needed.+5. **Whoever opens it closes it.** A reader, a decoder, or a canvas is released by the+ code that created it. Leaving the pool is suspension before closure: an idle source+ drops its decoder but keeps its parsed file and canvases, so waking it costs one+ keyframe seek.+6. **Read the file once.** Forty segments of one recording share one parsed file and one+ reader cache. Sound, filmstrip and preview all join that same open file.+7. **Measure before you ship.** A change to the preview, the timeline, or the frame loop+ runs the perf evals, and the summary says what moved.++## Memory++The memory that runs a machine out is memory the page cannot see: decoded frames inside+the platform decoder, canvas backing in the GPU process. The browser reports the size of+neither. So the accounting happens at the allocation sites, where the sizes are known+exactly, and one place adds them up.++| Bucket | Holds |+| --- | --- |+| decoders | Frames inside the platform decoder |+| canvases | Frame rings and the warm shelf of stood-down sources |+| reads | File bytes held by open readers |+| audio | Decoded sound waiting to be scheduled |+| pictures | Element bitmaps, thumbnails, mattes |++The ceiling is a quarter of what the browser reports the machine has. Past that the+machine swaps, and a swapping machine previews worse than one decoding at half the size.++## Measuring++Nothing about a stutter can be settled by watching. Two things settle it with numbers.++**The frame trace** records when a time was asked for and when a frame for it reached+the screen. It is off until armed. On a machine we cannot reproduce, a person opens the+console and runs:++```js+__cutPerf.start() // play the part that stutters+__cutPerf.report() // a summary small enough to paste into a bug report+```++**The perf evals** open a real browser on a fixture project, drive it, and read that+trace. They count in frames, so a report reads the same on a 60Hz and a 120Hz display,+and they run under machine profiles that throttle the CPU and the network.++```sh+npm run eval:cut-perf # every case, this machine+npm run eval:cut-perf-lowend # playback cases, throttled to a cheap laptop+```++A nightly run gates the scrub cases on a CI machine profile.++Every editor session also meters its own main thread. A frame over a second, or a half+minute mostly blocked, marks the session as trouble and the frames leading up to it are+sent to analytics with the script that held the thread and the control that was pressed.+A small random share of sessions send regardless, as the baseline trouble is measured+against.++## Where it lives++The frame loop and decoders live in the preview's frame source and playback hook, the+memory budget in its own module beside them, the trace and meter in the perf trace and+perf log modules, and the evals in the site's scripts folder.