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

# Pre-render upcoming videos

> Pre-render the first frame of the next playlist item in the FastPix iOS Player so promotion is visually instant, with no black flash.

Pre-render the first frame of the next playlist item in the FastPix iOS Player so promotion is visually instant, with no black flash.

Pre-rendering decodes and holds the first displayable frame of the upcoming item off-screen, so when it becomes the active player the first frame appears at once. Where preloading warms AVFoundation's byte cache and smart caching persists whole assets to disk, pre-rendering goes one step further and pays the decode cost ahead of time. It uses a shadow `AVPlayer` held at rate `0` plus an `AVPlayerItemVideoOutput`, and retains the decoded `CVPixelBuffer` until you promote the item.

What it gives you:

* Decodes and retains the first frame of the very next item, so promotion never shows a black flash.
* Opt-in and off by default. Enable it per player with `isPreRenderEnabled`.
* Bounded concurrency (`maxConcurrent`, default `1`) keeps decode and memory cost predictable.
* The SDK auto-schedules the immediate next item and auto-consumes the ready frame on promotion, so there is no manual wiring in the playback path.
* On consume, it vends a fresh, unbonded `AVPlayerItem` that is never attached to the shadow player, which avoids AVFoundation single-owner crashes.
* DRM and FairPlay content, and items whose bytes are still cold, fall back to preload-only byte warming instead of pre-rendering.
* Retained frames and shadow players are released automatically on memory pressure and backgrounding.

All access goes through the shared singleton `FastPixPreRenderManager.shared`.

\


## Before you begin

Make sure you have the following:

* The FastPix iOS Player SDK installed in your project. See [Install FastPix iOS player](/docs/ios-player/install-fastpix-ios-player).
* A playlist added to the player. See [Manage playlists](/docs/ios-player/manage-playlists).
* Preloading set up, so pre-rendering can reuse the same warmed bytes. See [Preload and precache videos](/docs/ios-player/preload-and-precache-videos).

\


## How pre-rendering compares to the other look-ahead tiers

| Tier              | Warms                                       | Pays decode cost early | Best for                                  |
| ----------------- | ------------------------------------------- | ---------------------- | ----------------------------------------- |
| **Preloading**    | AVFoundation byte cache (shadow `AVPlayer`) | No                     | Faster initial buffering of the next item |
| **Smart Caching** | Whole asset on disk                         | No                     | Instant start and offline availability    |
| **Pre-rendering** | First **decoded** frame (held in memory)    | **Yes**                | Flash-free promotion in scroll feeds      |

\


## Enable pre-rendering

Enable it before you add the playlist, so the SDK can schedule the first look-ahead item as playback begins. Wire the shared manager to the player and, optionally, set yourself as the delegate to observe the lifecycle.

```swift
import FastPixPlayerSDK

let preRenderManager = FastPixPreRenderManager.shared

// Observe lifecycle callbacks (optional).
preRenderManager.delegate = self

// Let pre-render reuse the same warmed bytes as preloading.
preRenderManager.preloadManager = preloadManager

// Wire the manager to the player and turn the feature on (default: off).
playerViewController.preRenderManager = preRenderManager
playerViewController.isPreRenderEnabled = true

// Enable BEFORE adding the playlist so the first look-ahead item is scheduled.
playerViewController.addPlaylist(playlist)
```

Once enabled, the SDK owns scheduling and consumption end to end. It pre-renders the immediate next item, cancels stale entries as you scroll past them, and swaps in the ready first frame automatically when you navigate to a pre-rendered item. You do not need to consume it manually in your navigation handlers.

\


## Bound the decode cost

```swift
// Number of items pre-rendered concurrently. Heavier than preload's byte
// warming, so this defaults to 1. Raise only if you have the memory headroom.
FastPixPreRenderManager.shared.maxConcurrent = 1
```

\


## Check status and cancel

```swift
// Current pre-render status for an item.
let status = playerViewController.preRenderStatus(forId: playbackId) // PreRenderStatus

// Cancel an in-flight pre-render (e.g. the user scrolled away).
playerViewController.cancelPreRender(forId: playbackId)
```

`PreRenderStatus` is one of `.idle`, `.loading`, `.buffering`, `.frameReady`, `.failed(Error?)`, or `.cancelled`. Only a `.frameReady` item vends a decoded frame. Every other state degrades safely to normal loading.

\


## Observe the pre-render lifecycle

Conform to `FastPixPreRenderManagerDelegate` to observe when an item starts pre-rendering, becomes frame-ready, fails, or is cancelled.

```swift
extension VideoPlayerViewController: FastPixPreRenderManagerDelegate {
    func videoPreRenderDidStart(forId id: String) {
        print("[PreRender] started \(id)")
    }
    func videoPreRenderDidBecomeReady(forId id: String) {
        // First frame decoded and retained. Promotion of this item is now flash-free.
        print("[PreRender] frame ready \(id)")
    }
    func videoPreRenderDidFail(forId id: String, error: Error?) {
        // Degrades to normal loading. Not fatal.
        print("[PreRender] failed \(id): \(String(describing: error))")
    }
    func videoPreRenderDidCancel(forId id: String) {
        print("[PreRender] cancelled \(id)")
    }
}
```

\


## Release

```swift
// Release all retained frames and shadow players. Call in deinit.
FastPixPreRenderManager.shared.clearAll()
```

\


## Things to know

* Pre-rendering is opt-in. `isPreRenderEnabled` defaults to `false`, and when it is off, playback behaves exactly as before.
* DRM and FairPlay items, and items whose bytes are still cold, are not pre-rendered. They degrade to preload-only byte warming and load normally, so there is no failure or crash.
* Concurrency is bounded by `maxConcurrent` (default `1`) to keep decode and memory cost predictable. A second look-ahead item waits for a free slot.
* On consume, the SDK hands back a fresh, unbonded `AVPlayerItem`. The shadow item stays owned by the manager, which avoids "player item already associated with another player" crashes.
* Retained frames and shadow players are released on memory pressure and backgrounding. A released item reloads normally on next use.
* The best way to test is scroll-feed promotion: pre-render the next item, scroll to it, and confirm the first frame appears with no black flash. A very fast switch before the frame is ready degrades to preload-only warm bytes.

\


#### Frequently asked questions

Preloading warms AVFoundation's byte cache so the next item buffers faster. Pre-rendering goes further and decodes the first frame ahead of time, so the first frame appears with no black flash when the item is promoted. Pre-rendering reuses the bytes that preloading warms.

No. DRM and FairPlay items fall back to preload-only byte warming and load normally, so there is no failure or crash. They just do not get the flash-free first frame.

No. The SDK auto-schedules the immediate next item and swaps in the ready first frame when you navigate to it. You do not wire consumption into your navigation handlers.

One by default, set by `maxConcurrent`. Pre-rendering pays a decode cost, so raise this only if you have the memory headroom.

\


## What's next

* [Preload and precache videos](/docs/ios-player/preload-and-precache-videos) to warm the next item's bytes before pre-rendering decodes its first frame.
* [Manage playlists](/docs/ios-player/manage-playlists) to set up the queue that pre-rendering looks ahead in.