Add preview thumbnails

Add preview images that appear when a user hovers over the control bar or seeks through a media asset.


The iOS SDK supports the loading of preview thumbnails for individual shots or scenes in a video. These thumbnails are displayed in a tooltip when a viewer hovers the control bar.

Preview thumbnails gives the user an indication of where they are seekingPreview thumbnails gives the user an indication of where they are seeking

Preview thumbnails gives the user an indication of where they are seeking

You can define your preview thumbnails in a single .vtt file. Set the .vtt file with JWThumbnailTrackBuilder(), which creates a JWMediaTrack. You can then set the JWMediaTrack with JWPlayerItemBuilder().


For an optimal user experience, the thumbnails should adhere to the following:

  • URLs must point to individual thumbnail files (filename.jpg) or to the spacial media fragment (filename.jpg#xywh=0,0,120,90) in a thumbnail sprite.
  • URLs must be relative to the .vtt file
  • Thumbnail width of 100-150 px
WEBVTT

00:00.000 --> 00:02.000
5s2afBXZ-120.jpg#xywh=0,0,120,90

00:02.000 --> 00:05.005
5s2afBXZ-120.jpg#xywh=120,0,120,90
WEBVTT

00:00.000 --> 00:02.000
scene1_0.jpg

00:02.000 --> 00:05.005
scene1_1.jpg

📘

TIP

When a media asset is uploaded to your JW Player account, a thumbnail track file is created as part of the transcoding process. So, instead of creating a new .vtt file for a video asset, you can copy the URL of the thumbnail track file from your JW Player dashboard.

To locate the thumbnail track of a specific video asset, follow these steps:

  1. Click the name of the video in your JW Player dashboard Media Library.
  2. Under Media Summary, click the View Assets.
  3. On the Tracks tab in the Thumbnail Preview row, click to reveal the DIRECT URL.
  4. Copy the DIRECT URL.
  5. Click Close.


Add a preview thumbnail

Use the following steps to associate a preview thumbnail with a player item:

  1. Use JWThumbnailTrackBuilder()to create a JWMediaTrack object. Set the URL of your .vtt file as the value of the file property.
  2. Use JWPlayerItemBuilder() to add the JWMediaTrack to a JWPlayerItem. Set the JWMediaTrack as the value of the mediaTracks property.
import UIKit
import JWPlayerKit

class CustomPlayerViewController: JWPlayerViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        do {
            // Create a JWMediaTrack with the thumbnails .vtt file
            let thumbnailTrack = try JWThumbnailTrackBuilder()
                .file(URL(string:<#.vtt URL String#>)!)
                .build()

            // Create a JWPlayerItem, setting the thumbnail track
            // using the `mediaTracks` method.
            let item = try JWPlayerItemBuilder()
                .file(URL(string:<#Video URL String#>)!)
                .mediaTracks([thumbnailTrack])
                .build()

            // Create a config, and give it the item as a playlist.
            let config = try JWPlayerConfigurationBuilder()
                .playlist([item])
                .build()

            // Set the config
            player.configurePlayer(with: config)
        }
        catch {
            // Handle Error
        }
    }
}
@interface CustomPlayerViewController: JWPlayerViewController

@end

@implementation CustomPlayerViewController

- (void)viewDidLoad
{
    [super viewDidLoad];
    
    // Create a JWMediaTrack with the thumbnails .vtt file
    JWError *mediaTrackError;
    JWThumbnailTrackBuilder *thumbnailTrackBuilder = [[JWThumbnailTrackBuilder alloc] init];
    [thumbnailTrackBuilder file: [NSURL URLWithString:@”yourvtttrackurl.vtt”]];
    JWMediaTrack *thumbnailTrack = [thumbnailTrackBuilder buildAndReturnError:&mediaTrackError];
    if (mediaTrackError != nil) {
        // Handle media track error
    }

    // Create a JWPlayerItem, setting the thumbnail track
    // using the `mediaTracks` method.
    JWError *playerItemError;
    JWPlayerItemBuilder *playerItemBulider = [[JWPlayerItemBuilder alloc] init];
    [playerItemBulider file:[NSURL URLWithString:@"file.mp4"]];
    [playerItemBuilder mediaTracks:@[thumbnailTrack]];
    JWPlayerItem *playerItem = [playerItemBulider buildAndReturnError:&playerItemError];
    if (playerItemError != nil) {
        // Handle error
    }

    // Create a config, and give it the item as a playlist.
    JWError *playerConfigError;
    JWPlayerConfigurationBuilder *playerConfigBuilder = [[JWPlayerConfigurationBuilder alloc] init];
    [playerConfigBuilder playlist:@[playerItem]];
    JWPlayerConfiguration *playerConfig = [playerConfigBuilder buildAndReturnError:&playerConfigError];
    if (playerConfigError != nil) {
        // Handle error
    }

    // Set the config
    [self.player configurePlayerWith:playerConfig];
}

@end


Did this page help you?