How to add a snapshot template-ApsaraVideo VOD(VOD)-阿里云帮助中心

Comparison of snapshot methods

Snapshot methods include Normal Snapshot, WebVTT, and Image Sprite. For more information, see Video snapshots.

Snapshot method	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. This can affect loading performance.
WebVTT	Displaying thumbnails when you hover over the progress bar of a web or H5 player.	Pros: Compatible with thumbnail previews on the progress bars of web and H5 players. Cons: Has a single purpose. Cannot be used as a standalone image.
Sprite	Scenarios that require thumbnail previews on mobile clients or players with high loading performance requirements.	Pros: Reduces the number of HTTP requests. Optimizes frontend loading performance. Suitable for mobile scenarios. Cons: The configuration process is relatively complex. Individual thumbnails within the sprite cannot be referenced directly.

Create a snapshot template

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

Click Create Snapshot Template. On the Add Snapshot Template page, configure the template parameters.

Important

The snapshot method (Normal Snapshot, WebVTT, or Sprite) cannot be changed after the template is created. Confirm your selection before you save the template.

General parameters

The following parameters apply to all snapshot methods.

Parameter	Description
Template Name	The custom name of the template, used for identification and reference in workflows.
Start Time	The time when the snapshot process starts (HH:MM:SS).
Number of Snapshots	The number of snapshots to generate.
Snapshot Interval	The time interval between snapshots. If you set this to 0 or leave it empty, snapshots are evenly distributed across the video duration.
Dimensions (Width × Height)	The width and height of the snapshot in pixels. Note If you do not set the width and height, the snapshot dimensions are the same as the input video. If you set only the width or height, the other dimension is scaled proportionally to the video's aspect ratio to prevent distortion.
Frame Type	The type of frame to capture. Options include keyframes and regular frames. Note If you select keyframes, only keyframes are captured. If no keyframe exists at the specified time, the nearest keyframe is selected. Capturing keyframes is faster than capturing regular frames.

WebVTT-specific parameters

Parameter	Description
Generate a large image	Whether to combine the thumbnails required for WebVTT into a single large image for storage.

Sprite-specific parameters

Parameter	Description
Layout (Rows × Columns)	The width and height of the individual thumbnails within the sprite. Note If not set, the thumbnail dimensions match a normal snapshot. If only one dimension is set, the other is scaled proportionally.
Row Spacing	The vertical spacing between rows of thumbnails in the sprite, in pixels.
Column Spacing	The horizontal spacing between columns of thumbnails in the sprite, in pixels.
Background Color	The background color of the sprite.
Keep Individual Images	Whether to keep the individual images that make up the sprite after the sprite is generated.

After you complete the configuration, click Save.

Use a snapshot template in a workflow

After you create a snapshot template, add it to a workflow to use it during media upload or processing.

Attach the template to a workflow.

Log on to the ApsaraVideo VOD console. In the navigation pane on the left, choose Configuration Management > Media Processing > Workflows. Add or edit a workflow. Insert a Snapshots node into the workflow. In the node configuration pane on the right, select the snapshot template that you created.
Trigger the workflow.

After you attach the template, trigger the workflow in one of the following ways.
1. Automatic trigger: When you upload an audio or video file, specify this workflow. The workflow automatically runs after the file is uploaded. For more information, see Upload files in 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 then specify this workflow.
3. API trigger: Call the SubmitWorkflowJobs operation to specify this workflow.
Retrieve the snapshot results.

You can retrieve the snapshot results from a SnapshotComplete event notification. When a snapshot is captured, the system sends a callback to the configured URL. The message body contains a list of snapshot 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 notification?

Perform the following steps to troubleshoot the issue:

Confirm that the input video status is Normal and the video file is not corrupted.
Verify that the snapshot template parameters are valid. For example, the start time must not exceed the video duration.
Confirm that event notification callbacks are correctly configured. For more information, see Event notifications.

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

Call the SubmitSnapshotJob operation to start a snapshot job independently.