Thumbnails

PRESTOplay for Apple includes a thumbnails plugin that provides preview images for any point in your content’s timeline. Use it to display seek-bar previews so viewers can visually navigate to the moment they’re looking for.

Setup

Register the ThumbnailsPlugin when initializing the SDK:

import PRESTOplay
import CastlabsThumbnails

let res = PRESTOplaySDK.shared.setup("LICENSE", [ThumbnailsPlugin()])

Review Thumbnails first for shared thumbnail formats, manifest signaling, and authoring patterns.

Loading thumbnails

Once the player session is created, load the thumbnail data:

PRESTOplaySDK.shared.thumbnails(for: player)?
    .loadThumbnailsFrom(webVTTtrack: url) { error in
    if let error = error {
        // Handle error
    } else {
        // Thumbnails are ready to use
    }
}

Retrieving a thumbnail

Retrieve the image for a specific point in time:

if let thumbnail = PRESTOplaySDK.shared.thumbnails(for: player)?
    .getThumbnail(atTimestamp: timestamp) {
    // Use the thumbnail image data
}

You can use the returned data to construct a UIImageView and display it when the viewer interacts with the seek bar.

Master grid images

For a more compact approach, you can configure a GridThumbnail that describes a set of tiled images using a URL template, grid dimensions, and timing information:

let gridInfo = GridThumbnail(
    baseUrl: "https://demo.cf.castlabs.com/media/Route66/dash/thumbs",
    pathTemplate: "$index$_7.jpg",
    gridHeight: 10,
    gridWidth: 10,
    durationMs: 1000,
    maxIndex: 7)

PRESTOplaySDK.shared.thumbnails(for: player)?
    .loadThumbnailsFrom(gridThumbnail: gridInfo) { error in
    if let error = error {
        // Handle error
    } else {
        // Thumbnails are ready to use
    }
}

You can also pass the template as part of the base URL:

let gridInfo = GridThumbnail(
    baseUrl: "https://demo.cf.castlabs.com/media/Route66/dash/thumbs/$index$_7.jpg",
    gridHeight: 10,
    gridWidth: 10,
    durationMs: 1000)

Caching

When loadThumbnailsFrom() is called, the plugin stores the downloaded thumbnail images and WebVTT file on the device file system. They remain available for future playback sessions, including offline playback. Clean up the cache when it is no longer needed:

PRESTOplaySDK.shared.thumbnails(for: player)?.deleteLocalCache()

Apple TV

To display thumbnails on the Apple TV player using ApplePlayerViewController, I-Frames must be present in the HLS manifest:

# I-Frame Playlists
#EXT-X-I-FRAME-STREAM-INF:AVERAGE-BANDWIDTH=241218,BANDWIDTH=1074106,CODECS="avc1.4D401F",RESOLUTION=1280x720,URI="media-1/iframes.m3u8"

Native Apple thumbnails (experimental)

This experimental feature uses AVPlayer track selection to generate thumbnails from I-Frame tracks or the current playback track. A dedicated UIView is required for rendering.

let thumbnails = PRESTOplaySDK.shared.thumbnails(
    for: player, engine: .apple)

DispatchQueue.main.async {
    thumbnails?.getThumbnail(
        atTimestamp: position,
        renderOn: thumbnailsView)
}

I-Frame track requirements are described in the HLS specification (I-Frame playlists) and the Apple HLS authoring specification.

Next topic: PRESTOplay for web

Previous topic: Getting started