Update a preview file

A thumbnailthumbnail - Preview content that appears in search results or playlists and a posterposter - Preview content that appears in the player before a viewer or a piece of code initiates media playback show a preview of the media content in your player. These previews can increase a viewer's engagement with your media.

For a consistent user experience, a thumbnail and poster for a video are generated from the same preview file. The preview file for a video can be managed by the /videos/thumbnails route.

Each time you upload a video to your JW Player account, the following preview files are created for a thumbnail and poster:

• A static preview file created from the 10th second of your video
• A video preview file created from the first 5 seconds of your video

After uploading a video, you can use one of the following approaches to change the default preview images:

• Upload a custom preview file
• Choose a video frame for the static preview file

Each option is explained in the following sections.

📘

TIP

You can also update a video thumbnail within your JW Player dashboard.

Upload a custom preview file

Standards

A custom static preview file should adhere to the following standards.

A custom video preview file should adhere to the following requirements.

Process

Use the following steps to upload a custom preview file:

1. Add one of JW Player's client libraries to your codebase and import the jwplatform library.
2. Make an API GET request to /videos/list to return a list of your videos. From the response, locate the video.key of the video whose thumbnail and poster you want to update.
3. Make an API GET request to /videos/thumbnails/update?video_key={video_key}. A successful request returns a response that contains a link object.
4. From the response, construct the upload URL by concatenating all properties of the link object.

📘

NOTE

Although the API response returns "link.protocol": "http", you can use either the HTTP or HTTPS protocol for the upload URL.

{
  "status": "ok",
  "media": {
    "type": "video",
    "key": "{video_key}"
  },
  "link": {
    "path": "/v1/videos/upload",
    "query": {
      "token": "{query_token}",
      "key": "{video_key}"
    },
    "protocol": "http",
    "address": "upload.jwplatform.com"
  },
  "rate_limit": {
    "reset": 1573744740,
    "limit": 60,
    "remaining": 59
  }
}

link.protocol + "://" + link.address + link.path + "?api_format=json" + "&key=" + link.query.key + "&token=" + link.query.token

https://upload.jwplatform.com/v1/videos/upload?api_format=json&key={video_key}&token={query_token}

5. Make an API POST request to the upload URL that includes the location of your static or video thumbnail.

curl POST "{upload_url}" \
-F "[email protected]_PATH"

'use strict';

const JWPlatformAPI = require('jwplatform');
const resolve = require('path').resolve;
const axios = require('axios');
const FormData = require('form-data');
const concat = require("concat-stream");
const fs = require('fs');

// TODO: Enter API V1 credentials
const jwApiInstance = new JWPlatformAPI({
    apiKey: '',
    apiSecret: '',
});

// TODO: Enter file path and video key (media ID)
const filePath = '';
const videoKey = '';

jwApiInstance.videos.thumbnails
    .update({ video_key: videoKey })
    .then(response => {
        console.log(response);
        const { path, protocol, address, query } = response.link;
        const uploadUrl = `https://${address}${path}?api_format=json&key=${query.key}&token=${query.token}`;
        const formData = new FormData();
        formData.append("file", fs.createReadStream(resolve(filePath)));
        formData.pipe(
            concat({encoding:'buffer'}, (data) => {
                axios.post(uploadUrl, data, {
                    headers: formData.getHeaders()
                }).then(response => console.log(response))
            })
        )
    });

Choose a video frame for the static preview file

👍

IMPORTANT

You cannot use this approach to create a custom video preview file.

1. Make a /videos/list call to return a list of your videos. From the response, locate the video.key of the video whose thumbnail and poster you want to update.
2. Identify the timestamp of a frame from the video.
3. Convert the timestamp value into seconds.
4. Make a GET call to /videos/thumbnails/update?position={timestamp_in_seconds}.