How to add a snapshot template - ApsaraVideo VOD - Alibaba Cloud Documentation Center

ApsaraVideo VOD provides snapshot templates with preset parameters to automatically capture video snapshots in media processing workflows. This topic describes how to select a snapshot type, create and manage templates, and use templates in workflows for automated snapshots.

Comparison of snapshot types

The snapshot types are Normal Snapshot, WebVTT, and Image Sprite. For more information, see Video Snapshots.

Snapshot type	Scenarios	Pros and cons
Normal Snapshot	Video thumbnails, content moderation, and sharing highlights.	Pros: Highly flexible. Suitable for scenarios that require single images. Cons: Many snapshots generates many files and HTTP requests, which affects loading performance.
WebVTT	Displaying preview thumbnails when hovering over the progress bar in Web/H5 players.	Pros: Compatible with progress bar previews in Web/H5 players. Cons: Has a single purpose. Cannot be used as a standalone image.
Image Sprite	Scenarios that require preview thumbnails on mobile clients or in players that need optimal loading performance.	Pros: Reduces the number of HTTP requests and optimizes frontend loading performance. Ideal for mobile scenarios. Cons: The configuration process is relatively complex. Individual small images cannot be directly referenced.

Create a snapshot template

Log on to the ApsaraVideo VOD console.
In the left navigation bar, choose Configuration Management > Media Processing > Snapshot Templates to go to the Snapshot Templates page.

Click Create Snapshot Template. On the Add Snapshot Template page, configure the snapshot template based on your business needs.

Important

The snapshot type (Normal Snapshot, WebVTT, or Image Sprite) cannot be modified after the template is created. Confirm your selection before saving.

Configuration

General parameters

The following parameters apply to all snapshot types.

Parameter	Description
Template Name	A custom name for the template. Used for identification and reference in workflows.
Start Time	The time to start capturing snapshots, in HH:MM:SS format.
Snapshot Count	The total number of snapshots to generate.
Snapshot Interval	The time interval between multiple snapshots. If you set this parameter to 0 or leave it empty, snapshots are captured at even intervals based on the video duration.
Size (Width × Height)	The width and height of the snapshot. Unit: pixel. Note If you do not set the width and height, the snapshot has the same dimensions as the input video. If you set only the width or height, the other dimension is scaled based on the video's aspect ratio to prevent distortion.
Frame Type	The frame types for snapshots include keyframes and normal frames. Note If you select Keyframe, only keyframes are captured. If the specified time point is not a keyframe, the nearest keyframe is automatically selected. Under the same conditions, capturing keyframes is faster than capturing normal frames.

WebVTT-specific parameters

Parameter	Description
Generate Large Image	Specifies whether to combine the multiple thumbnails required for WebVTT into a single large image for storage.

Image sprite-specific parameters

Parameter	Description
Arrangement (Rows × Columns)	The width and height settings for the small images in the image sprite. Note If you do not set these parameters, the small images have the same dimensions as normal snapshots. If you set only one dimension, the other is scaled proportionally.
Row Spacing	The vertical space between rows of small images in the image sprite. Unit: pixel.
Column Spacing	The horizontal space between columns of small images in the image sprite. Unit: pixel.
Background Color	The background color of the image sprite.
Retain Small Images	Specifies whether to retain the original images that make up the image sprite when the sprite is generated.

After you complete the configuration, click Save.

Use a snapshot template in a workflow

After a snapshot template is created, you must add it to a workflow to use it during media uploads or processing.

Attach the template to a workflow.
Log on to the ApsaraVideo VOD console, go to Configuration Management > Media Processing > Workflows, add or edit a workflow, insert a Snapshots node, and select the created snapshot template in the node settings on the right.
Trigger the workflow.
After you attach the template, you can trigger the workflow in the following ways.
1. Automatic trigger: Specify the workflow when you upload an audio or video file. After the upload is complete, the workflow is automatically executed. For more information, see Upload files using the ApsaraVideo VOD console.
2. Manual trigger: On the Media Files > Audio/Video page, select the target media asset, click Processing, select Use Workflow, and specify the workflow.
3. API trigger: Call the Submit Video-on-Demand Workflow Job operation to specify this workflow job.
Get snapshot results.
You can obtain screenshot results through the Video Screenshot Completion event notification. After the video screenshot succeeds, the system sends a callback message to the configured address, and the message body contains a list of screenshot data.

Billing

The snapshot feature of ApsaraVideo VOD is free of charge.

FAQ

What do I do if I do not receive a SnapshotComplete event?

You can troubleshoot the issue as follows:

Confirm that the status of the input video is Normal and that the video file is not corrupted.
Confirm that the parameters in the snapshot template are valid. For example, check whether the start time exceeds the video duration.
Verify that the event notification callback configuration is correct. For more information, see Event Notifications.

How do I use a snapshot template directly through an API?

You can call the Submit Media Snapshot Job operation to initiate a snapshot job independently.