All Products
Search
Document Center

ApsaraVideo Media Processing:Video snapshots

Last Updated:Jan 29, 2024

You can use the video snapshot feature to capture snapshots of a specific size at specific points in time of a video. The snapshots are used for video thumbnails, sprites, and progress bar thumbnails. This topic describes how to submit a snapshot job to capture video snapshots in ApsaraVideo Media Processing (MPS).

Overview

Scenarios

  • Video thumbnail: You can capture the first frame of a video as the video thumbnail in a feed stream of short videos, or capture a snapshot at a specific point in time of a video as the video thumbnail.

  • Video preview: You can create thumbnails based on the video content. When a user moves the pointer over the timeline of a video in a player, a static thumbnail of the video at a specific point in time is displayed. This helps users quickly browse the video content and seek to the content they are interested in.

  • Video moderation: You can capture multiple snapshots of a video for manual or automated review.

Features

Feature

Description

Parameter of an API operation

MPS console

Static snapshot

This feature allows you to take snapshots of specific sizes at specific points in time of a video in the JPG format. The following snapshot modes are provided:

  • Single: A snapshot is taken at a specific point in time of a video. This type of snapshot can be taken synchronously or asynchronously.

  • Multiple: Snapshots are taken at a specific interval from a specific point in time until a specific number of snapshots are taken or the video ends. You can specify the interval in units of seconds. This type of snapshot is taken asynchronously.

  • Average: A specific number of snapshots are taken from a specific point in time of a video to the end of the video at a regular interval. This type of snapshot is taken asynchronously.

  • Time point (in beta testing): Snapshots are taken at the specified points in time of a video. This type of snapshot is taken asynchronously.

SnapshotConfig

Supported

Sprite snapshot

This feature allows you to create a sprite by merging the snapshots that are taken into a single image based on specific rules. The sprites are in the JPG format. This type of snapshot is taken asynchronously. Users can send a request to query the information about multiple images at a time. This greatly reduces the number of API requests for images and improves client performance.

TileOut and TileOutputFile

Not supported

WebVTT snapshot

This feature allows you to generate VTT files for the snapshots that are taken or the sprites that are created. VTT files contain the time when snapshots are taken, paths of snapshots, and coordinates of snapshots in sprites. When a client requests an image, the image is displayed after the corresponding VTT file is obtained and parsed. This feature can be used to display thumbnails on the progress bar.

SubOut

Supported

Keyframe snapshot

This feature allows you to capture only keyframes. If the frame at the specified point in time is not a keyframe, the adjacent keyframe is captured.

FrameType

Supported

Black screen detection

This feature allows you to detect whether the first snapshot is a black screen. To use this feature, set the Time parameter to 0, which specifies that the snapshots are taken from the start of a video. You can define a black screen by specifying the portion of black pixels in an image and the color value of black pixels. If the black screen detection feature is enabled, the system checks the frames in the first 5 seconds of a video. If a non-black frame exists, the non-black frame is captured. Otherwise, the job fails if the job is a single-snapshot job, or the first black frame is captured if the job is a multi-snapshot job.

BlackLevel and PixelBlackThreshold

Supported

Billing

The snapshot fee is charged based on the number of snapshots. For more information, see the Pricing for API calls section of the "Audio and video transcoding fees" topic.

Submit a snapshot job in the MPS console

Note

You can submit snapshot jobs only by using workflows in the MPS 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. On the Workflow Orchestration page, click Create Workflow.

  5. On the Create Workflow page, configure the Input node based on your business requirements.

  6. Add a Snapshot node.image.png

  7. Click the Pen icon next to the Snapshot node. In the Snapshot dialog box, configure the parameters that are described in the following table.

    Parameter

    Required

    Description

    Snapshot Mode

    Yes

    • Single: captures a snapshot of the video at a specific point in time.

    • Multiple: specifies a time interval to evenly capture multiple snapshots of the video. Each snapshot is an image file. Multi-frame snapshots are also called batch snapshots or ordinal snapshots.

    • Average: evenly splits the video and captures snapshots based on the specified number of snapshots.

    Snapshot Interval (Seconds)

    Yes if you set the Snapshot Mode parameter to Multiple

    The interval for capturing snapshots. Unit: seconds.

    Snapshots

    Yes if you set the Snapshot Mode parameter to Average

    The number of snapshots to be captured.

    Note
    • If the Snapshots parameter is not specified, snapshots are captured based on the specified interval until the end of the video.

    • If the value of the Snapshots parameter is greater than 1, snapshots are captured based on the specified interval until the number of snapshots reaches the specified number.

    • If only the Snapshots parameter is specified, snapshots are evenly captured based on the total duration divided by the number of snapshots.

    Name

    Yes

    The name of the Snapshot node.

    Output Path

    Yes

    The path of the output file to be stored in an OSS bucket. Click Select next to the Output Path field. In the Select Output Path dialog box, select an OSS bucket from the Bucket drop-down list. Then, folders in the OSS bucket are automatically displayed in the Path section. Select a folder as the output path.

    Note
    • If you set the Snapshot Mode parameter to Single, a snapshot is named in the format of {SnapshotTime}.jpg and is exported to the /path/{RunId} folder under the OSS bucket. For example, the output path may be http://bucket.oss-cn-hangzhou.aliyuncs.com/path/{RunId}/{SnapshotTime}.jpg.

    • If you set the Snapshot Mode parameter to Multiple or Average, a {Count} placeholder is used. In this case, the latter part of the output path is in the format of /{RunId}/{SnapshotTime}/{Count}.jpg.

    Start Time

    No

    The time when the workflow starts to capture a snapshot. Select the hour, minute, and second from the drop-down lists.

    Width x Height

    No

    The weight and height of the snapshot.

    Note
    • If neither the Width nor Height parameter is specified, the size of the output snapshots is the same as that of the input video.

    • If only one of the Width and Height parameters is specified, the unspecified side is scaled based on the aspect ratio of the input video. This prevents image deformation.

    Generate WebVTT Index File

    Yes if you set the Snapshot Mode parameter to Multiple or Average

    Specifies whether to use a thumbnail in the WebVTT format.

    Set as Thumbnail

    No

    Specifies whether to use the snapshot as the thumbnail of the media file. If you turn on the switch, the snapshot captured at the specified point in time is used as the thumbnail. If multiple snapshots are captured, the first one is used as the thumbnail by default.

    Keyframe

    No

    Specifies whether to capture only keyframes as snapshots. If you turn on the switch, only keyframes are captured as snapshots. If the frame at the specified point in time is not a keyframe, MPS captures the snapshot of the nearest keyframe.

    Black Screen Detection

    Yes if you set the Snapshot Mode parameter to Multiple or Average

    Specifies whether to detect the first 5 seconds of the video. If you turn on the switch and images appear in the first 5 seconds, the first non-black frame content is captured.

  8. Click OK. The Snapshot node is configured.

  9. Click Save.

    Note

    If a file is uploaded to the path specified by the Input Path parameter after the workflow is created, the workflow is triggered. For more information about how to trigger a workflow, see Trigger a workflow.

Submit a snapshot job by calling an API operation

  1. Upload a video to OSS.

  2. Submit a snapshot job. You can call the SubmitSnapshotJob operation to submit a snapshot job. You can configure the SnapshotConfig parameter to submit a snapshot job to capture a snapshot in synchronous or asynchronous mode, generate a sprite, or capture a Web Video Text Tracks Format (WebVTT) snapshot. For more information about the SnapshotConfig parameter, see Parameter details.

    Submit a snapshot job to capture a snapshot in synchronous mode

    Capture a keyframe at the 100th millisecond of the video. The width of the output snapshot is 1,280 pixels, and the height of the output snapshot is calculated based on the aspect ratio of the input video. The snapshot file is in the JPG format. 
    If you want to submit a snapshot job in synchronous mode, do not specify the Num or Interval parameter. A snapshot job in synchronous mode cannot be used to capture a WebVTT snapshot or generate a sprite. 
    {
      "Time":"100",
      "FrameType":"intra",
      "Width":"1280",
      "OutputFile":{
      	"Bucket":"example-bucket",
      	"Location":"oss-cn-hangzhou",
      	"Object":"example.jpg"
    	}
    }

    Submit a snapshot job to capture a snapshot in asynchronous mode

    Capture a keyframe at the beginning of the video and enable the black screen detection feature. The width and height of the output snapshot are the same as those of the input video. The snapshot file is in the JPG format. 
    {
      "Num":"1",
      "Time":"0",
      "FrameType":"intra",
      "BlackLevel":"100",
      "PixelBlackThreshold":"30",
      "OutputFile":{
      	"Bucket":"example-bucket",
      	"Location":"oss-cn-hangzhou",
      	"Object":"example.jpg"
    	}
    }

    Submit a snapshot job to capture multiple snapshots

    Capture regular frames every 10 seconds from the beginning of the video until 200 frames are captured or the video ends. 
    Enable the black screen detection feature for the first snapshot. The width and height of the output snapshots are the same as those of the input video. The format of the snapshot name is example{Count}.jpg. 
    {
      "Num":"200",
      "Time":"0",
      "Interval":"10",
      "FrameType":"normal",
      "BlackLevel":"100",
      "PixelBlackThreshold":"30",
      // To prevent output files from overwriting each other when you capture multiple snapshots at a time, you must specify a placeholder {Count} when you configure the OutputFile parameter.
      "OutputFile":{
      	"Bucket":"example-bucket",
      	"Location":"oss-cn-hangzhou",
      	"Object":"example{Count}.jpg"
    	}
    }

    Submit a snapshot job to capture snapshots in an even manner

    Capture 200 regular frames in an even manner from the 100th millisecond to the end of the video. The width and height of the output snapshots are 1280 pixels and 720 pixels. The format of the snapshot name is example{Count}.jpg. 
    {
      "Num":"200",
      "Time":"100",
      "Interval":"0",
      "FrameType":"normal",
      "Width":"1280",
      "Height":"720",
      // To prevent output files from overwriting each other when you capture multiple snapshots at a time, you must specify a placeholder {Count} when you configure the OutputFile parameter.
      "OutputFile":{
      	"Bucket":"example-bucket",
      	"Location":"oss-cn-hangzhou",
      	"Object":"example{Count}.jpg"
    	}
    }

    Submit a snapshot job to generate sprites

    Capture 200 regular frames in an even manner from the 100th millisecond to the end of the video. The width and height of the output snapshots are 1280 pixels and 720 pixels. 
    Merge the snapshots into sprites in a 10*10 layout. The sprites are saved in the bucket named example-bucket002, and the original snapshots are saved in the bucket named example-bucket001. 
    {
      "Num":"200",
      "Time":"100",
      "Interval":"0",
      "FrameType":"normal",
      "Width":"1280",
      "Height":"720",
      // To prevent output files from overwriting each other when you capture multiple snapshots at a time, you must specify a placeholder {Count} when you configure the OutputFile parameter.
      "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 output files from overwriting each other when you capture snapshots and generate sprites at the same time, set the OutputFile and TileOutputFile parameters to different paths. You must specify a placeholder {TileCount} when you configure the TileOutputFile parameter.
      "TileOutputFile":{ 
      	"Bucket":"example-bucket002",
      	"Location":"oss-cn-hangzhou",
      	"Object":"example{TileCount}.jpg"
    	}
    }

    Submit a snapshot job to capture a WebVTT snapshot

    Capture 200 regular frames in an even manner from the 100th millisecond to the end of the video. The width and height of the output snapshot are 1280 pixels and 720 pixels. The output snapshot is a WebVTT snapshot. 
    {
      "Num":"200",
      "Time":"100",
      "Interval":"0",
      "FrameType":"normal",
      "Width":"1280",
      "Height":"720",
      // Generate a WebVTT snapshot. The file name extension in the value of the Object parameter must be set to .vtt. The storage path of the snapshot file is example/snapshot-tile-{Count}.jpg
      "OutputFile": {
      	"Bucket":"example-bucket",
      	"Location":"oss-cn-hangzhou",
      	"Object":"example.vtt"
    	},
      "Format":"vtt",
      "SubOut":{
        "IsSptFrag":"true"
      }
    }
    1. If you call an operation to submit a snapshot job in synchronous mode to capture a single snapshot, the result of the job is returned in the response of the operation. For a snapshot job in asynchronous mode, you must configure Message Service (MNS) callback or call an operation to query the result.

      Note

      A timeout error may occur if the size of the input file is too large. Configure a retry mechanism based on your business requirements.

    2. Recommended. Configure a callback notification.

      If the notification feature is enabled for the snapshot job, you can receive a notification in the specified MNS queue or topic after the snapshot job is complete. For more information, see Receive notifications.

    3. Query the results of the snapshot job.

      You can call the QuerySnapshotJobList operation to query the results of the snapshot job by job ID. You can also perform a paged query based on conditions such as the status of the snapshot job, the time when the job was created, and the MPS queue to which the job was submitted. In this case, you do not need to specify the ID of a snapshot job.

    Submit a snapshot job by using an SDK

    SDK

    References

    MPS SDK for Java

    Submit a snapshot job and query the job result

    MPS SDK for Python

    Manage snapshot jobs

    MPS SDK for PHP

    Manage snapshot jobs

    MPS SDK for PHP (updated version)

    Manage snapshot jobs

    MPS SDK for Node.js

    Manage snapshot jobs

    MPS SDK for Go

    Manage snapshot jobs

    FAQ

    For more information, see FAQ about snapshot capture.