All Products
Document Center

FAQs about screenshots

Last Updated: Apr 20, 2018

General questions

What is a screenshot?

A screenshot is an image captured from an input file, generally a video file, based on the corresponding screenshot configurations.

Screenshot methods supported by MTS

MPS uses the following two methods to take a screenshot:

Screenshot modes

  • Synchronous mode

    A screenshot result is synchronously returned over the API, and a screenshot is generated in the corresponding bucket during result returning.

  • Asynchronous mode

    A screenshot may not be generated when a screenshot result is returned over the API. The screenshot task queues at the background, and the screenshot is taken asynchronously. If either the Interval or Num parameter is set, the asynchronous mode is used. Set PipelineId to ensure that the corresponding message is configured in the MTS queue and an asynchronous message is sent after the screenshot is taken.

Screenshot types

  • Normal frame: normal

  • I frame, which is also called key frame: intra. A key frame screenshot is a key frame image that is taken at the time closest to the input screenshot time.

Screenshot scenarios

  • Single screenshot: Num = 1 or not set

  • Multiple screenshot: Num > 1 or Interval > 0

  • Average screenshot: Interval = 0 and Num > 1

Screenshot-supported image format

JPG images are supported currently.


How can I distinguish the synchronous and asynchronous modes when submitting a screenshot task?

If either of Interval and Num is set, the asynchronous mode is used, which is nothing to do with PipelineId. For details, see “11 SnapshotConfig parameters” in Parameters details.

What can I do if the snapshot taken at the specified screenshot time is not a key frame screenshot?

Obtain the key frame closest to the screenshot time. If multiple screenshots are taken, the corresponding key frame image close to the screenshot time cannot be found. In this case, the image at the corresponding time is not returned, and the number of returned images is different from that of set images.

What will happen if the specified screenshot time exceeds the video duration?

  • Single screenshot

    • An error is returned for a common screenshot.

    • According to the definition of the key frame screenshot, the key frame image that is taken at the time closest to the input screenshot time is returned.

  • Multiple screenshots

    If the screenshot time calculated using the formula Time + Interval x Num exceeds the video duration, the subsequent snapshots are automatically invalid, and the number of actually taken screenshots is returned after screenshot taking is completed.

How can I take an M3U8 screenshot?

When screenshots are taken in synchronous mode, the TS and M3U8 files must be in the same path in the M3U8 index. No requirement is set for the asynchronous mode.

Why is the number of returned sequence screenshot is smaller than the setvalue?

No key frame image exists near the corresponding time point, or the subsequent screenshot time exceeds the total duration of the input file.

How can I set the image size?

  • You can set the size of an output image. For details, see Width and Height of “11 SnapshotConfig parameters” in Parameters details.

  • If you do not set Width and Height, the image size is set based on the video resolution.

  • If you set either of Width and Height, the image size is scaled based on the aspect ratio of the input file.

How can I diagnose a screenshot task error?

The screenshot task error codes include SnapshotTimeOut, InvalidParameter.ResourceNotFound, and InvalidParameter.ResourceContentBad. For details, see Submits a screenshot task.

  • Method to obtain the error code

    • If a screenshot task fails to be submitted, query the snapshot task API to obtain the failure cause. For details, see the Return result of the QuerySnapshotJobList API in View screenshot task.

    • If a screenshot fails to be taken using a workflow, log on to the MPS console. In the media repository, select the corresponding executed instance and check the screenshot activity failure cause.

  • Common cause of main errors

    • InvalidParameter.ResourceNotFound

      The input file cannot be found. Ensure that the input file contains the bucket corresponding to the specified region and data of each region is independent.

    • SnapshotTimeOut

      The screenshot times out. This error is returned with the screenshot result in synchronous mode. Currently, after a screenshot task is submitted, the result is returned within six seconds. If timeout occurs frequently in synchronous mode, we recommend that the asynchronous mode be used to prevent timeout. Retry is not recommended.

    • InvalidParameter.ResourceContentBad

      The snapshot file is damaged, or the screenshot fails to be taken because it does not meet the specifications. Ensure that the input file content is normal and the screenshot configuration meets the specifications by referring to FAQs in this document. Pay special attention to the screenshot time, key frame, and other information.