This topic describes the parameters that you can configure to capture video snapshots and provides examples.

Usage notes

  • When you capture video snapshots, you are charged for the number of captured images. For more information about billing, see Data processing fees.
  • Object Storage Service (OSS) can capture images from video objects only in the H.264 and H.265 formats.
  • By default, OSS does not automatically store captured images. You must manually download the captured images to your local storage devices.

Parameters

Operation type: video

Operation name: snapshot

Parameter Description Value value
t The time when the image is to be captured. [0, video duration]

Unit: milliseconds

w The width based on which to capture the image. If this parameter is set to 0, the width based on which to capture the image is automatically calculated. [0, video width]

Unit: pixels

h The height based on which to capture the image. If this parameter is set to 0, the height based on which to capture the image is automatically calculated. If w and h are set to 0, the width and height of the source image are used. [0, video height]

Unit: pixels

m The mode used to capture the image. If this parameter is not specified, the image is captured in the default mode. In other words, the image at the specified point in time in the video is captured. If this parameter is set to fast, the most recent key image before the specified time is captured. fast
f The format of the captured image. jpg and png
ar Specifies whether to automatically rotate the image based on the video information. auto, h, and w

  • auto indicates that the captured image is automatically rotated based on the video information.
  • h indicates that the captured image is automatically rotated based on the mode in which the height is greater than the width.
  • w indicates that the captured image is automatically rotated based on the mode in which the width is greater than the height.

Examples

  • Use the fast mode to capture the image at the seventh second of the video. Export the captured image as a JPG image whose width is 800 pixels and height is 600 pixels.

    The URL of the processed image is in the following format: <Video URL>?x-oss-process=video/snapshot,t_7000,f_jpg,w_800,h_600,m_fast.

  • Capture the image at the fiftieth second of the video accurately. Export the captured image as a JPG image whose width is 800 pixels and height is 600 pixels.

    The URL of the processed image is in the following format: <Video URL>? x-oss-process=video/snapshot,t_50000,f_jpg,w_800,h_600.

Generate a signed URL to capture a video snapshot

You can use OSS SDKs to generate a signed URL to capture a video snapshot. The following code provides an example on how to use OSS SDK for Java to generate a signed URL to capture a video snapshot:

// In this example, the endpoint of the China (Hangzhou) region is used. Specify the endpoint based on your business requirements. 
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Specify the name of the bucket. Example: examplebucket. 
String bucketName = "examplebucket";
// Specify the full path of the video object. If the video object is not stored in the root directory of the bucket, you must include the directory of the object in the path. Example: examplefolder/videotest.mp4. 
String objectName = "examplefolder/videotest.mp4";
// Create an OSSClient instance. 
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
Capture the image at the fiftieth second of the video accurately. Export the captured image as a JPG image whose width is 800 pixels and height is 600 pixels. 
String style = "video/snapshot,t_50000,f_jpg,w_800,h_600";
// Set the validity period of the URL to 10 minutes. 
Date expiration = new Date(new Date().getTime() + 1000 * 60 * 10 );
GeneratePresignedUrlRequest req = new GeneratePresignedUrlRequest(bucketName, objectName, HttpMethod.GET);
req.setExpiration(expiration);
req.setProcess(style);
URL signedUrl = ossClient.generatePresignedUrl(req);
System.out.println(signedUrl);
// Shut down the OSSClient instance. 
ossClient.shutdown();

The method used to generate signed URLs to capture snapshots is similar to that used to generated signed URLs to process images by using Image Processing (IMG). To use the following OSS SDKs to generate a signed URL to capture a snapshot, replace the IMG operations in the code with the snapshot operation.