> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Preload and precache videos

> Preload and precache upcoming videos in the FastPix Flutter Player to shorten the tap-to-first-frame time. Both are best effort and never block or fail playback.

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.

|             | Preloading                                      | Precaching                        |
| ----------- | ----------------------------------------------- | --------------------------------- |
| Lives in    | Memory, this app session                        | Disk, survives a restart          |
| Warms       | Connection, manifest, optionally a whole player | Manifest and segment bytes        |
| Entry point | `FastPixPreloadManager.instance`                | `FastPixPrecacheManager.instance` |

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.

```dart
await FastPixPreloadManager.instance.preload(
  upcomingSources,                 // the next few items, in order
  configuration: playerConfiguration,
  strategy: FastPixPreloadStrategy.player,
  window: 3,
  warmDrm: true,
);
```

**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.

```dart
FastPixPreloadManager.instance.statusOf(playbackId);  // queued | loading | ready | failed | cancelled
FastPixPreloadManager.instance.isReady(playbackId);
FastPixPreloadManager.instance.cancel(playbackId);    // on eviction, never on mount
FastPixPreloadManager.instance.clearAll();
FastPixPreloadManager.instance.dispose();             // releases every warm player; the manager stays usable
```

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:

```dart
FastPixPreloadManager.instance.isCastActive = () => castController.isConnected;
```

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.

```dart
final status = await FastPixPrecacheManager.instance.precacheManifest(source);
final bytes = FastPixPrecacheManager.instance.bytesWrittenFor(source.playbackId);

await FastPixPrecacheManager.instance.precacheAll(upcomingSources);
await FastPixPrecacheManager.instance.stop(source);   // abandon a warm in flight
FastPixPrecacheManager.instance.statusOf(playbackId); // idle | cached | failed | unsupported
FastPixPrecacheManager.instance.clearStatuses();
```

`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`.

```bash
flutter run | grep -E "preloading|precaching"
adb logcat  | grep -E "preloading|precaching"
```

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](/docs/flutter-player/manage-a-playlist) to queue the videos you preload.
* [Prerender the next video](/docs/flutter-player/prerender-the-next-video) to decode the first frame ahead of time.