Skip to navigation

Prerender the next video

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:

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

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:

CaseCode
Prerendering offdisabled
On cellular with prerenderOnCellular: falsenetworkPolicy
The slot is taken, or a build is still in flightdecoderBudget
DRM-protected sourcedrm
Live source, or the active item is livelive
Picture-in-Picture activepip
A Cast sessionexternalPlayback
App not in the foregroundbackground
No next item, or repeat onenavigationPolicy
No FastPixPlayer / FastPixVideoSurface mounted, or fullscreennoSurface
Native first-frame hook unavailable on this buildfeatureDisabled

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.

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