All Products
Search
Document Center

Object Storage Service:Video snapshots

Last Updated:Feb 22, 2024

You can upload videos to an Object Storage Service (OSS) bucket and use the video snapshot feature to extract video thumbnails, keyframes, or specific frames from the videos.

Usage notes

  • When you capture snapshots from videos, you are charged based on the number of captured snapshots. For more information, see Data processing fees.

  • OSS can capture snapshots from videos only in the H.264 and H.265 formats.

  • By default, OSS does not automatically store captured snapshots. You need to manually download captured snapshots to your local storage devices.

Parameters

Category: video

Action: snapshot

Parameter

Description

Valid value

t

The time at which you want to capture the snapshot. If the value exceeds the length of the video, the last frame is returned.

Note

If you want to capture a video thumbnail, set t to 0.

[0, video duration]

Unit: milliseconds

w

The width of the snapshot to capture. If this parameter is set to 0, the width of the captured snapshot is calculated based on the proportion of the height of the captured snapshot to the video height.

[0, video width]

Unit: pixel

h

The height of the snapshot to capture. If this parameter is set to 0, the height of the captured snapshot is calculated based on the proportion of the width of the captured snapshot to the video width. If both w and h are set to 0, the snapshot width and height are the same as the video width and height.

[0, video height]

Unit: pixel

m

The mode used to capture the snapshot. If this parameter is not specified, the snapshot is captured in the default mode. In other words, the snapshot at the specified point in time of the video is captured. If this parameter is set to fast, the most recent keyframe before the specified point in time is captured.

fast

f

The format of the snapshot to return.

jpg and png

ar

The mode that you want to use to automatically rotate the captured snapshot.

  • auto: specifies that the captured snapshot is automatically rotated based on the video information.

  • h: specifies that the captured snapshot is automatically rotated based on the mode in which the height is greater than the width.

  • w: specifies that the captured snapshot is automatically rotated based on the mode in which the width is greater than the height.

Examples

This section provides examples on how to capture snapshots from a video that is stored in the oss-console-img-demo-cn-hangzhou bucket in the China (Hangzhou) region. The video is hosted at the following URL:

https://oss-console-img-demo-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/video.mp4

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 sample 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 your actual endpoint. 
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// For security purposes, we recommend that you do not save access credentials in the project code. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the environment variables are configured. 
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// Specify the name of the bucket in which the video object is stored. 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 provide the full path to the object. Example: examplefolder/videotest.mp4. 
String objectName = "examplefolder/videotest.mp4";
// Create an OSSClient instance. 
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
// Capture the snapshot right at the 17th second of the video. Export the captured snapshot as a JPG image whose width is 800 pixels and height is 600 pixels. 
String style = "video/snapshot,t_17000,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.

FAQ

Can I process a video object whose ACL is private by directly adding parameters to the URL of the object?

No, you cannot. If the ACL of the video object that you want to process is private, you can use OSS SDKs to add video processing operations to the signed URL of the object. You cannot process a video object whose ACL is private by directly adding parameters to the object URL.

How do I check the width and height of a video object that is stored in OSS?

You can use the video information extraction feature to obtain the width and height of a video.

Why is a captured video snapshot distorted?

The video from which you capture the snapshot uses the BT.2020 color gamut. The video snapshot feature does not support videos that use the BT.2020 color gamut.