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 you want to capture the image. If the time that you specify is longer than the duration of the video, the last keyframe of the video is returned. | [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
|
Examples
This section provides examples on how to capture snapshots for a video that is stored in the bucket named oss-console-img-demo-cn-hangzhou in the China (Hangzhou) region. The video is hosted in the following URL:
https://oss-console-img-demo-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/video.mp4- 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 used to apply the preceding parameters is https://oss-console-img-demo-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/video.mp4?x-oss-process=video/snapshot,t_7000,f_jpg,w_800,h_600,m_fast.
- Capture the image at the seventeenth 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 used to apply the preceding parameters is https://oss-console-img-demo-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/video.mp4?x-oss-process=video/snapshot,t_17000,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 your actual endpoint.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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 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 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 seventeenth 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_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 adding parameters to the URL of the object?
No. 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 to process the video object. You cannot process a video object whose ACL is private by adding parameters to the object URL.
How do I view the width and height of a video object that is stored in OSS?
You can deploy the ffmpeg tool on your local computer and run the ffprobe command to obtain the width and height of a video.