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

# Prerender the next video

> Prerender the next playlist item in the FastPix Flutter Player so it appears at once, with no black frame between items. On by default.

Preloading makes the next item start faster. Prerendering makes it appear at once. Once the active item shows its first frame, the SDK builds the next item's player, positions it at its start, and holds it paused and muted on a hidden surface beneath the active video until its first frame is drawn. A next, autoplay-next, or a `jumpTo` that lands on it then swaps to that frame, with no black frame between items.

It is on by default and needs no code. Turn it off, or keep it off cellular:

```dart
FastPixPlayerConfiguration(
  workspaceId,
  viewerId,
  beaconUrl,
  prerenderConfiguration: const FastPixPlayerPrerenderConfiguration(
    enablePrerender: true,       // default true; false restores the old transitions
    prerenderOnCellular: false,  // default true; a prerender spends data on a video the viewer may never reach
  ),
);

// At runtime, without reloading anything:
controller.updatePrerenderConfiguration(
  const FastPixPlayerPrerenderConfiguration(prerenderOnCellular: false),
);
```

`updatePrerenderConfiguration` applies at once: a prerender the new settings rule out is released, and one they now allow is made. A later `setPlaylist` or `initialize` with its own configuration replaces it. Prerender settings never reach the engine, so they are not part of the [preload](/docs/flutter-player/preload-and-precache-videos) adoption fingerprint, and changing them leaves the active and warm players alone.

**What is prerendered.** Always the next item: the first item again after the last with repeat `all`, nothing past the end with repeat `off`, and nothing with repeat `one`. One prerender at a time per controller. Moving anywhere else releases it, and an item that is already a warm preloaded player is reused rather than built again.

\


## Prerender outside a playlist

Ask for a source yourself, then load it:

```dart
final result = await controller.prerender(nextSource);  // FastPixPrerenderResult
controller.prerenderStatusOf(nextSource.playbackId);    // idle | preparing | frameReady | skipped | failed | released
controller.cancelPrerender(nextSource.playbackId);
await controller.loadPlaybackId(nextSource);            // promotes it when ready
```

`prerender` never throws. A refusal completes with status `skipped` and an `errorCode` saying why.

\


## When it is skipped

Each skip is reported with a `FastPixPrerenderErrorCode`, and the transition falls back to the normal path, a warm player when one exists, otherwise a cold start:

| Case                                                              | Code               |
| ----------------------------------------------------------------- | ------------------ |
| Prerendering off                                                  | `disabled`         |
| On cellular with `prerenderOnCellular: false`                     | `networkPolicy`    |
| The slot is taken, or a build is still in flight                  | `decoderBudget`    |
| DRM-protected source                                              | `drm`              |
| Live source, or the active item is live                           | `live`             |
| Picture-in-Picture active                                         | `pip`              |
| A Cast session                                                    | `externalPlayback` |
| App not in the foreground                                         | `background`       |
| No next item, or repeat `one`                                     | `navigationPolicy` |
| No `FastPixPlayer` / `FastPixVideoSurface` mounted, or fullscreen | `noSurface`        |
| Native first-frame hook unavailable on this build                 | `featureDisabled`  |

A prerender that started and could not finish fails with `loadFailed`, `timedOut` (no first frame within `FastPixPreloadManager.warmTimeout`), `seekFailed`, or `surfaceUnavailable`. A prerender already held is released when a policy above starts to apply, such as PiP opening, a Cast session starting, the app leaving the foreground, or memory pressure, and made again once it no longer does.

The hidden player is kept out of Picture-in-Picture and Now Playing. Only the active item is ever seen or heard there.

\


## Events

`prerenderRequested` (`FastPixPrerenderRequestedEvent`, with `automatic` true when the playlist asked for it), `prerenderReady` (`FastPixPrerenderReadyEvent`, with `timeToFirstFrame`), and `prerenderFailed` (`FastPixPrerenderFailedEvent`, with `code` and `message`, for skips and failures alike; `prerenderStatusOf` tells them apart). Each names the prerendered source's `playbackId` and `playlistIndex`, not the active item's, and none of them is a playback error.

```dart
controller.addEventListener(FastPixPlayerEventTypes.prerenderReady, (event) {
  final ready = event as FastPixPrerenderReadyEvent;
  debugPrint('${ready.playbackId} ready in ${ready.timeToFirstFrame.inMilliseconds} ms');
});
```

Decisions are logged under the `preloading` tag. Grep for `PRERENDER`, and for `PRERENDER promoted` to confirm a transition used it.

\


## What's next

* [Manage a playlist](/docs/flutter-player/manage-a-playlist) to set the queue prerendering looks ahead in.
* [Preload and precache videos](/docs/flutter-player/preload-and-precache-videos) to warm the next item's bytes.