Video snapshot

Overview

Use cases

• Video covers: Select the first frame of a short video in a feed as its cover, or capture a frame at a specific time point to use as the cover.

• Video previews: Create thumbnails from your video content. When a user hovers over the player's timeline, the player displays a static thumbnail from that time point. This helps users quickly browse the video content and jump to sections of interest.

• Video moderation: Sample video content by taking snapshots for manual or automated review.

Features

Billing

You are charged for API calls based on the number of snapshots generated. For more information, see Pricing for API calls.

Submit snapshot jobs in the console

1. Log on to the MPS console.

2. In the top navigation bar, select a region from the drop-down list.

3. In the left-side navigation pane, choose Workflow > Workflow Orchestration.

4. Click Create Workflow.

5. Configure the Input node as required.

6. Add a Snapshot node. Click the + icon to the right of the Input node and select Snapshot from the drop-down menu.

7. Click the pen icon to the right of the Snapshot node to configure its parameters.

   Parameter	Required	Description
   Snapshot mode	Required	Single: Captures a snapshot at a specific time point. Multiple: Captures multiple frames at a specified interval. Each frame is saved as a separate image file. Also known as batch or sequential snapshots. Average: Evenly divides the video and captures the specified number of snapshots.
   Snapshot interval (seconds)	Required when there are multiple snapshots.	Enter the interval between snapshots in seconds.
   Snapshots	Required for uniform snapshotting.	Enter the number of snapshots to capture. Note If you do not specify a number, snapshots are captured at the specified interval until the end of the video. If the value is greater than 1, snapshots are captured at the specified interval until the specified number is reached. If you only specify the number of snapshots, they are captured at an interval equal to the total duration divided by the number of snapshots.
   Name	Required	Enter a name for the node.
   Output path	Required	Click Select. From the bucket drop-down list, select a bucket. The folders in the bucket are displayed under Path. Select a folder as the output path. Note Single snapshot URL format: http://bucket.oss-cn-hangzhou.aliyuncs.com/path/{RunId}/{SnapshotTime}.jpg. The path format for multiple or average snapshots must include the {Count} placeholder, such as /{RunId}/{SnapshotTime}/{Count}.jpg.
   Start time	Optional	Select the time (hour, minute, and second) from the drop-down lists.
   Width x height	Optional	Enter the width and height values. Note If you leave both width and height empty, the snapshot dimensions will match the video dimensions. If you set only the width or the height, the other dimension is scaled proportionally to the video's resolution to prevent distortion.
   Generate WebVTT index file	Optional for multiple snapshots and average snapshot.	Turn on the switch to generate a WebVTT index file.
   Set as thumbnail	Optional	Turn on the switch to automatically set the captured snapshot as the media's thumbnail in the media library. If multiple snapshots are captured, the first one is set as the thumbnail by default.
   Keyframe	Optional	Turn on the switch to capture only keyframes. If the specified time point is not a keyframe, the system captures the nearest keyframe instead.
   Black screen detection	Available for multiple snapshots or average snapshots.	Turn on the switch to scan the first 5 seconds of the video. If content is detected within the first 5 seconds, the first non-black frame is captured.

8. Click OK to finish configuring the snapshot node.

9. Click Save to complete the workflow configuration.

   Note

   After the workflow is created, it triggers automatically when a new file that meets the input criteria is uploaded to the specified path. For more information about how to trigger a workflow, see Trigger a workflow.

Submit snapshot jobs by API

1. Upload a video to OSS.

2. Submit a snapshot job. Call the SubmitSnapshotJob API and configure the SnapshotConfig parameter to submit jobs for synchronous single snapshot, asynchronous single snapshot, sprites, or WebVTT snapshots. The following sections show examples of the SnapshotConfig parameter structure. For more information, see Parameter details.

   Synchronous single snapshot

   // Capture one keyframe at 100 ms into the video. The output image width is 1280 px, and the height is adaptive. The image is saved in JPG format.
   // Synchronous mode does not support the Num or Interval parameters, nor does it support sprite or WebVTT output.
   {
     "Time":"100",
     "FrameType":"intra",
     "Width":"1280",
     "OutputFile":{
     	"Bucket":"example-bucket",
     	"Location":"oss-cn-hangzhou",
     	"Object":"example.jpg"
   	}
   }

   Asynchronous single snapshot

   // Capture one keyframe at the beginning of the video, with first-frame black screen detection enabled. The output image has the same dimensions as the source video and is saved in JPG format.
   {
     "Num":"1",
     "Time":"0",
     "FrameType":"intra",
     "BlackLevel":"100",
     "PixelBlackThreshold":"30",
     "OutputFile":{
     	"Bucket":"example-bucket",
     	"Location":"oss-cn-hangzhou",
     	"Object":"example.jpg"
   	}
   }

   Sampled snapshot

   // Starting from the beginning of the video, capture one normal frame every 10 seconds for a maximum of 200 frames or until the video ends.
   // First-frame black screen detection is enabled. The output images have the same dimensions as the source video and are saved as example{Count}.jpg.
   {
     "Num":"200",
     "Time":"0",
     "Interval":"10",
     "FrameType":"normal",
     "BlackLevel":"100",
     "PixelBlackThreshold":"30",
     // To prevent files from being overwritten, you must use the {Count} placeholder in the OutputFile object for multiple snapshots.
     "OutputFile":{
     	"Bucket":"example-bucket",
     	"Location":"oss-cn-hangzhou",
     	"Object":"example{Count}.jpg"
   	}
   }

   Evenly-spaced snapshot

   // Capture 200 normal frames, spaced evenly, from 100 ms to the end of the video. The output images are 1280 px wide and 720 px high. The images are saved as example{Count}.jpg.
   {
     "Num":"200",
     "Time":"100",
     "Interval":"0",
     "FrameType":"normal",
     "Width":"1280",
     "Height":"720",
     // To prevent files from being overwritten, you must use the {Count} placeholder in the OutputFile object for multiple snapshots.
     "OutputFile":{
     	"Bucket":"example-bucket",
     	"Location":"oss-cn-hangzhou",
     	"Object":"example{Count}.jpg"
   	}
   }

   Sprite

   // Capture 200 normal frames, spaced evenly, from 100 ms to the end of the video. The output images are 1280 px wide and 720 px high.
   // The small images are stitched into a sprite with a 10x10 layout. The sprite is saved in example-bucket002, and the individual small images are saved in example-bucket001.
   {
     "Num":"200",
     "Time":"100",
     "Interval":"0",
     "FrameType":"normal",
     "Width":"1280",
     "Height":"720",
     // To prevent files from being overwritten, you must use the {Count} placeholder in the OutputFile object for multiple snapshots.
     "OutputFile":{
    		"Bucket":"example-bucket001",
   	  "Location":"oss-cn-hangzhou",
   	  "Object":"example{Count}.jpg"
   	},
     "TileOut":{
       "Lines":10,
       "Columns":10,
       "Padding":"2",
       "Margin":"4",
       "Color":"black",
       "IsKeepCellPic":"true"
     },
     // To prevent files from being overwritten, set OutputFile and TileOutputFile to different buckets or object paths. You must also use the {TileCount} placeholder in the TileOutputFile object for the sprite.
     "TileOutputFile":{ 
     	"Bucket":"example-bucket002",
     	"Location":"oss-cn-hangzhou",
     	"Object":"example{TileCount}.jpg"
   	}
   }

   WebVTT snapshot

   // Capture 200 normal frames, spaced evenly, from 100 ms to the end of the video. The output images are 1280 px wide and 720 px high. A VTT file is generated.
   {
     "Num":"200",
     "Time":"100",
     "Interval":"0",
     "FrameType":"normal",
     "Width":"1280",
     "Height":"720",
     // To output a VTT file, the Object must have a .vtt extension. The corresponding image path is example/snapshot-tile-{Count}.jpg.
     "OutputFile": {
     	"Bucket":"example-bucket",
     	"Location":"oss-cn-hangzhou",
     	"Object":"example.vtt"
   	},
     "Format":"vtt",
     "SubOut":{
       "IsSptFrag":"true"
     }
   }

3. For a synchronous single snapshot job, the API returns the result directly in its response. For asynchronous jobs, you must configure message notifications or proactively query the results.

   Note

   If the input file is too large, the job may time out and fail. We recommend implementing a retry mechanism.

4. (Recommended) Receive callback notifications.

   After an asynchronous job is completed, if message notifications are configured, the system sends a message to the specified queue or topic in Simple Message Queue (formerly MNS). For more information, see Receive message notifications.

5. Query the job results.

   Call the QuerySnapshotJobList API to query the results of one or more snapshot jobs by specifying their IDs. Alternatively, you can perform a paged query by filtering jobs based on status, creation time, or the MPS queue, without specifying job IDs.

Submit snapshot jobs by SDK

FAQ

For frequently asked questions about snapshots, see Snapshot FAQ.