v10/internal/design/spf/features/buffer-management.md

status, date, definition

status	date	definition
implemented	2026-05-20	sketched

Buffer management

Buffer management is the segment-level policy between loading gates and MediaSource operations.

Implemented decisions

• Plan a bounded amount of media ahead of current time and evict old back-buffer data.
• Deduplicate work by media type, segment, and selected quality while still permitting gap repair and seek-back recovery.
• Continue useful in-flight work and preempt work that no longer serves the current plan.
• Stream media chunks to the buffer actor while treating initialization data atomically.
• Give each media type a shared loading gate derived from preload and source state.
• Keep planning policy separate from the SourceBuffer actor that serializes browser operations.

These choices make seeks, quality changes, and playback-rate changes inputs to the same planner rather than special loading pipelines.

Deferred scope

Rate- or network-aware buffer targets, learned quota policy, loop anticipation, cross-codec changeType(), and a public buffer-health model require separate evidence and design.

Current sources of truth

• Segment planner and loading behavior: packages/spf/src/playback/behaviors/dom/load-segments.ts
• Segment and SourceBuffer actors plus tests: packages/spf/src/playback/actors/dom/
• Loading gates: packages/spf/src/playback/behaviors/sync-preload.ts and packages/spf/src/playback/behaviors/dom/track-load-triggers.ts