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, default1) 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
AVPlayerItemthat 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.
- A playlist added to the player. See Manage playlists.
- Preloading set up, so pre-rendering can reuse the same warmed bytes. See Preload and precache videos.
How pre-rendering compares to the other look-ahead tiers
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.
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
Check status and cancel
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.
Release
Things to know
- Pre-rendering is opt-in.
isPreRenderEnableddefaults tofalse, 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(default1) 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
- Preload and precache videos to warm the next item’s bytes before pre-rendering decodes its first frame.
- Manage playlists to set up the queue that pre-rendering looks ahead in.