Update a preview file
Update the default preview file for a video.
You can now use the Platform Management API v2 to manage a media poster.
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:
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.
Item | Notes |
---|---|
Accepted file formats | • .jpg • .png |
Image dimensions | 1920x1080 |
A custom video preview file should adhere to the following requirements.
Item | Notes |
---|---|
Accepted file formats | • .mp4 • .avi • .3gp • .wmv • .flv • .mov |
File duration | 5-6 seconds (ideal) If the video file is >10 seconds, only the first 10 seconds will be used for the thumbnail. |
Audio | N/A If the video file has audio, the audio will not be included in the thumbnail. |
Process
Use the following steps to upload a custom preview file:
- Add one of JW Player's client libraries to your codebase and import the
jwplatform
library. - Make an API
GET
request to/videos/list
to return a list of your videos. From the response, locate thevideo.key
of the video whose thumbnail and poster you want to update. - Make an API
GET
request to/videos/thumbnails/update?video_key={video_key}
. A successful request returns a response that contains alink
object. - 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}
- 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.
- Make a
/videos/list
call to return a list of your videos. From the response, locate thevideo.key
of the video whose thumbnail and poster you want to update. - Identify the timestamp of a frame from the video.
- Convert the timestamp value into seconds.
- Make a
GET
call to/videos/thumbnails/update?position={timestamp_in_seconds}
.
Updated 9 months ago