Skip to navigation

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


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

TierWarmsPays decode cost earlyBest for
PreloadingAVFoundation byte cache (shadow AVPlayer)NoFaster initial buffering of the next item
Smart CachingWhole asset on diskNoInstant start and offline availability
Pre-renderingFirst decoded frame (held in memory)YesFlash-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.

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

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

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

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

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

What is the difference between preloading and pre-rendering?

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.

Does pre-rendering work with DRM-protected videos?

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.

Do I need to consume the pre-rendered frame myself?

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.

How many items are pre-rendered at once?

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