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 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:
- Click the name of the video in your JW Player dashboard Media Library.
- Under Media Summary, click the View Assets.
- On the Tracks tab in the Thumbnail Preview row, click ∨ to reveal the DIRECT URL.
- Copy the DIRECT URL.
- Click Close.
Add a preview thumbnail
Use the following steps to associate a preview thumbnail with a player item:
- Use
JWThumbnailTrackBuilder()
to create aJWMediaTrack
object. Set the URL of your .vtt file as the value of thefile
property. - Use
JWPlayerItemBuilder()
to add theJWMediaTrack
to aJWPlayerItem
. Set theJWMediaTrack
as the value of themediaTracks
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
Updated 10 months ago