Skip to content

perf(core): hold a clip at 0 inside a later scene until it is due - #5716

Merged
miguel-heygen merged 1 commit into
mainfrom
perf/defer-nested-media
Oct 16, 2026
Merged

miguel-heygen merged 1 commit into
mainfrom
perf/defer-nested-media

Conversation

@miguel-heygen

Copy link
Copy Markdown
Collaborator

What

In a preview, a video or audio clip that starts at 0 inside a scene that starts later now parses at preload="none", like any other clip that is not due yet. Before, the parse-time deferral read only the clip's own data-start, so these clips started downloading at open and kept their buffers. Renders are unchanged: the deferral only runs in a preview.

Why

deferMediaUntilDue gives later clips preload="none" before Chromium can start fetching them, because a none set mid-fetch is ignored. It decided "later" from the clip's own data-start, which is local to its scene. A clip at 0 in a scene at 5:00 looked like it was due now, so the parser started it, and the runtime's later preload="none" could not stop it. On a 9-minute film with 91 sub-compositions, 24 such clips were downloading at open, about 64 s of buffered media for scenes nowhere near the playhead.

How

  • The deferral asks the start resolver for the clip's start in the film (resolveMediaStartForElement), the same owner the runtime's preload window uses, instead of reading data-start.
  • It still defers only clips with a numeric own data-start and an authored length, so it never holds a clip the runtime's preload window does not manage.
  • A fresh resolver per mutation batch: a start that references an element not parsed yet resolves to its fallback in that batch instead of staying cached.

Test plan

  • Unit test added in entry.test.ts: a clip at 0 in a scene at 0 keeps its default preload and a clip at 0 in a scene at 5 parses at none. Passes 3 runs in a row with the rest of the file (34 of 34). Fails without the fix: expected [ '', '' ] to deeply equal [ '', 'none' ].
  • Core: 210 test files, all tests pass; core typecheck, oxlint, oxfmt, package cycles and the comment ratchet pass.
  • Manual: the 9-minute film in hyperframes preview (headless Chrome). Clips starting more than 10 s in that had fetched anything 5 s after the preview was ready: 24 (64 s buffered) before, 0 (0 s) after, in two runs. The 3 clips near the playhead still load. 12 seeks across the film all land on their frame, and seek times and playback frame rates are within run-to-run noise of the build without this change.
  • Comments follow CONTRIBUTING.md "Comments"

@github-actions

Copy link
Copy Markdown
Contributor

Edit accuracy: accurate 271 (base branch 271), smooth 192 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (2)

  • crop-scale-px-r0-root-z100-after: tracking 0.03, pressJump 0, drop 40.03, reload 40.03, render 40, renderKey 40, undo true, teleport true / tracking 0.03, pressJump 0, drop 0.05, reload 0.05, render 0.02, renderKey 0.02, undo true, teleport true / tracking 0.03, pressJump 0, drop 0.05, reload 0.05, render 0.02, renderKey 0.02, undo true, teleport true
  • crop-tween-px-r0-nested-z100: tracking 0.04, pressJump 0, drop 40.07, reload 40.07, render 40.02, renderKey -, undo true, teleport true / tracking 0.04, pressJump 0, drop 0.09, reload 0.09, render 0.26, renderKey -, undo true, teleport true / tracking 0.04, pressJump 0, drop 0.09, reload 0.09, render 0.26, renderKey -, undo true, teleport true

@terencecho terencecho left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed HEAD 8699ac52329322b7030f9aa6195565c88974b1b0 against effective merge-base d05bc4215d5757da86956217f4a8a4b2ab11b1fd (API base eace3d28b6cb721ec1f9a96d7d2ea76bf215551a). No introduced reachable blocker found in the audited source scope.

The parse-time hold now uses the existing canonical media-start resolver while preserving numeric-own-start and authored-length eligibility. That population remains within runtime-managed media; the inspected discovery, preload-window and active-sync paths provide takeover. The resolver is fresh per mutation callback, and the existing preview discriminator remains in place. The added regression reaches the real entry/observer/resolver and distinguishes local-zero clips in opening and later scenes.

Scope: all changed BASE versions read before HEAD, both changed files fully read, plus bounded producer/resolver/preload/transport/capture integration and independent correctness and contracts/test-boundary audits. Shared resolver ownership does not imply identical parse-time/runtime inputs or retrospective reclassification when a reference appears later. This is a source-only review: tests were not run, and native parser fetching, buffering and performance claims were not independently verified. No whole-repository semantic-coverage claim.

— tai

@miguel-heygen
miguel-heygen added this pull request to the merge queue Oct 16, 2026
Merged via the queue into main with commit 13ea834 Oct 16, 2026
78 checks passed
@miguel-heygen
miguel-heygen deleted the perf/defer-nested-media branch October 16, 2026 23:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants