3.12.0 — Buffered position for scrub-bar indicators

Added

clock.bufferedPosition — buffer-bar indicator surface (#54)

A new published value on engine.clock reports how far ahead the engine has buffered, on the same source axis as sourceTime. A host draws a YouTube-style buffer bar directly as bufferedPosition / duration:

player.clock.$bufferedPosition   // source-axis position buffered ahead of the playhead

Previously the buffered-ahead figure existed only inside the 30s memory probe and was never surfaced to hosts.

What "buffered" means per playback path:

• Native AVPlayer (HLS / direct play): the end of the contiguous loadedTimeRanges span covering the playhead, folded onto the source axis with the same seam shift as sourceTime. Disjoint ranges past a gap are ignored on purpose, so the bar shows the continuously playable span.
• Software (dav1d / libavcodec): the newest demuxed source PTS in session time, i.e. how far ahead bytes have been fetched and demuxed from the (possibly remote) source. This makes the indicator meaningful for the large / remote sources the request targets.
• Audio: mirrors currentTime (no separate buffer-ahead surface).

The value is clamped to never trail the rendered frame and resets on load / stop. It ticks on engine.clock (the ~10 Hz / 250 ms surface that is split off the engine's own objectWillChange), so observing it does not re-render menus or track lists.

This is an additive public API. No behavior changes to existing surfaces.

Thanks to @ijuniorfu for the request.

🤖 Generated with Claude Code