Preload and precache videos
The FastPix Flutter Player can warm up the next videos ahead of time, so a viewer who taps the next item sees it start faster. There are two independent optimizations, and both are best effort: a failure, such as a timeout or a refused adoption, falls through to normal playback. Neither can make playback fail or wait, and each reports on its own event channel.
They share no state, so use them together rather than choosing between them.
Preload the next videos
Declare what is coming next. preload takes the state of the world rather than a command: it diffs against what it already holds, cancels departures, keeps survivors, and starts only arrivals, so it is safe to call on every scroll frame.
Strategies. network (the default) fetches the manifest so DNS and the CDN edge are hot. It allocates no platform player, and its window is unbounded. player builds a real, detached player and acquires the DRM license, so playback can adopt it and start immediately.
Warm depth is set once on the manager, not per call. FastPixPreloadManager.instance.warmDepth takes FastPixWarmDepth.master (the default, one request), variant (the master plus the chosen rendition playlist), or segments (the variant plus its opening segments, two by default). Deeper is warmer and costs more bandwidth against the video already playing.
Every warm is capped at twelve seconds (FastPixPreloadManager.warmTimeout). A warm that overruns is failed and logged, and playback cold-starts. Network warms run one at a time.
The window is capped for player: one on Android, three on iOS (FastPixPreloadManager.maxPlayerWindow). Requests past the cap are dropped rather than queued, and the clamp is logged.
Adoption requires a matching configuration. Pass initialize the same FastPixPlayerConfiguration you passed preload. A mismatch is refused and logged, and playback cold-starts. Set adoptPreloaded: false on initialize to force a cold start when measuring baseline latency.
A player warm is skipped, with a logged reason, while a Cast session is active, for live streams, and for DRM when warmDrm: false. A network warm is subject to none of these. A source already in the window is left alone rather than re-warmed.
Do not call cancel when the player mounts. Adoption happens after mount, so cancelling there throws away exactly the work about to be used.
If you cast, wire up Cast awareness once:
Lifecycle events arrive as FastPixPreloadStartedEvent, FastPixPreloadReadyEvent, FastPixPreloadFailedEvent, FastPixPreloadCancelledEvent, and FastPixPreloadConsumedEvent on FastPixPreloadManager.instance.eventManager. All five carry the playback ID, the strategy, and the network type. The ready event adds elapsed, and the failed event adds reason.
Precache to disk
Precaching writes bytes to disk ahead of playback, in the cache the player reads from.
precacheManifest never throws. It returns idle, cached, failed, or unsupported. A platform that reports success but writes zero bytes is treated as a failure, and bytesWrittenFor exposes the byte count. A repeat request for something already cached or in flight is coalesced and returns cached. precacheAll runs a list sequentially, since these requests share bandwidth with the video currently playing. A manifest is read up to FastPixPrecacheManager.manifestByteCeiling, which is 512 KB.
Precaching is refused, with the reason reported, on platforms other than Android and iOS, for live sources, for cacheEnabled: false, and for DRM on iOS.
- Android: the master playlist is written into the same media3 cache playback reads from, so a warm feeds the next start. This pays off while the URL is stable. If the playback token is re-resolved between the warm and playback, the warm is silently unused. Preloading is unaffected, because it keys by playback ID in Dart.
- iOS: playlists and the opening segments are stored on disk keyed by playback ID, which survives a token refresh. Playback does not yet read from that store, so on iOS precaching currently costs bandwidth and disk without shortening a later start. Prefer preloading there today.
Events arrive as FastPixPrecacheStartedEvent, FastPixPrecacheCachedEvent, and FastPixPrecacheFailedEvent on FastPixPrecacheManager.instance.eventManager. The cached event carries bytesWritten, and the failed event carries the refusal status alongside its reason.
See what happened
Both features fail silently by design, so every decision is logged, skips and refusals as well as successes. Logging is on in debug builds and silent in release. Force it with FastPixWarmLog.enabled = true.
The line worth grepping for is ADOPTED. Its absence is the difference between preloading working and preloading merely running.
What’s next
- Manage a playlist to queue the videos you preload.
- Prerender the next video to decode the first frame ahead of time.