perf(docs): stop docs pages auto-downloading 266 MB of video

[AlexBodner]

Stacked on #585. Base is fix/docs-video-poster so the diff shows only the new work; GitHub retargets to develop when #585 merges.

Problem

Ten of the twenty <video> elements in the docs were autoplay muted loop, which makes browsers fetch the entire file on page load. Measured against the live sources, that is 266 MB downloaded per visit across five pages, with evaluations/results.md alone pulling 147.8 MB before the reader interacts with anything. Nineteen of the twenty videos also had no poster, so the element stays blank until enough data arrives.

Fix

For all 20 videos: add a poster frame, set preload="none", and pin the element's aspect ratio so it reserves its final height before the poster decodes.

For the 10 autoplay videos, also drop autoplay. A poster does not help there, because autoplay downloads the file regardless. Removing it is the only thing that stops the transfer, so these are now muted loop with click-to-play.

That is a real trade: a looping demo shows motion, and a still frame does not. The measured difference on evaluations/results.md, same machine and network, 12s after load:

	Before	After
mp4 requests	4	0
Video buffered	63.0s of 120.3s	0.0s
Bytes pulled	~77 MB	228 KB
Window load	3,283 ms	55 ms

The usability gain is the argument here, not the SEO one. Core Web Vitals are a ranking signal and four videos saturating the connection delays every other resource, but that effect is indirect and modest, and I could not capture a clean LCP delta to quote.

If we want the motion back later, lazy autoplay via IntersectionObserver would start each video when it scrolls into view, keeping the loop without loading all four upfront. That costs JS in the docs and is not part of this PR.

Auto-downloaded MB per page load

Page	Videos	autoplay	Before	After	Saved
evaluations/results.md	4	Y	147.80	0.218	147.58
evaluations/evaluate.md	1	Y	37.01	0.057	36.95
evaluations/download.md	1	Y	36.67	0.056	36.62
guides/detection-quality.md	3	Y	31.91	0.166	31.74
guides/track.md	1	Y	13.13	0.033	13.10
autoplay subtotal	10		266.5	0.53	266.0
guides/iou.md	4	n	50.24	0.229	50.01
trackers/sort.md	1	n	8.99	0.055	8.94
trackers/ocsort.md	1	n	8.94	0.054	8.89
trackers/botsort.md	1	n	8.85	0.053	8.80
guides/state-estimators.md	1	n	4.28	0.053	4.23

The non-autoplay rows previously fetched a metadata range rather than the whole file, so their "before" is an upper bound. preload="none" takes them to zero video bytes until click either way.

Aspect ratios

Taken from each source rather than assumed, since two are not 16/9:

• guides/iou.md comparison renders are 2560x720, so aspect-ratio: 32/9
• guides/state-estimators.md is 1060x2160 portrait, so aspect-ratio: 53/108, kept alongside its existing width: 50%; height: auto

The rest are 1280x720 or 1920x1080.

Also: the ByteTrack demo video was dead

docs/trackers/bytetrack.md pointed at a GitHub user-attachment returning a hard 404, so that page has shown a dead video since 2026-05-08.

It was not an expiry. All four tracker videos were added in one commit, 351fe5c (#401). Cross-checking that PR's body against what landed in the docs:

Asset	In #401 body	Used in docs	Live
98c73178...	yes	sort.md	206
9ccae3a0...	yes	ocsort.md	206
7dfa0326...	yes	nowhere	206
9c9736c9...	no	bytetrack.md	404

The UUID in bytetrack.md was never uploaded to that PR, while a valid video uploaded in the same PR was referenced nowhere. A UUID was transcribed incorrectly.

I checked the orphaned asset against the original ByteTrack render from our 2026-05-08 thread: it is the same clip. It is already h264 High, 1280x720, 25fps, 4.9 Mbps, 16.000s, matching its sibling tracker demos, so no re-upload or re-encode is needed. All 20 videos now have a poster.

Validation

• mkdocs build runs clean. The one INFO line is a pre-existing dead anchor (trackers/cbiou.md#buffer-ordering), unrelated to this change.
• All 20 poster= paths resolve relative to their built page, and all 20 videos carry preload="none" in the built site.
• On the built site, /guides/iou/ and /evaluations/results/ report readyState: 0 and networkState: 1 on every video, with zero mp4 requests until play. Playback and the captions track on index.md still work.
• No <source> URL changed except the ByteTrack fix above. The diff touches <video> tags only, no prose.
• 17 posters, 971 KB total, largest 59.9 KB.

🤖 Generated with Claude Code