This topic provides answers to frequently asked questions (FAQ) about snapshot capture in ApsaraVideo Media Processing (MPS).
Common errors for snapshot jobs
One of the following error codes may be returned for a snapshot job: SnapshotTimeOut, InvalidParameter.ResourceNotFound, and InvalidParameter.ResourceContentBad. If a snapshot job fails to be submitted, you can call the QuerySnapshotJobList operation to query the cause of the failure. For more information, see QuerySnapshotJobList.
What do I do if the error code "SnapshotTimeOut" is returned?
This error code is returned if a snapshot job in synchronous mode times out. The timeout period for a snapshot job in synchronous mode is 5 seconds. If the input file is oversized, the snapshot job may time out. If the snapshot job frequently times out, we recommend that you submit a snapshot job in asynchronous mode.
What do I do if the error code "InvalidParameter.ResourceNotFound" is returned?
This error code is returned if a snapshot job fails to be submitted or the snapshot job fails because the input file is not found. Troubleshoot the error based on the causes that are described in the following table.
Cause | Solution |
The input file is not uploaded when you submit the snapshot job or the input file is deleted. | Make sure that the input file is uploaded before you submit the snapshot job. |
The Object Storage Service (OSS) path of the input file is invalid. | Check the OSS path of the input file. |
URL encoding is not performed on the OSS path of the input file. | For more information, see URL encoding. |
The OSS bucket in which the input file resides is not in the same region as MPS. | Make sure that the OSS bucket and MPS reside in the same region. |
The input file is stored in OSS by using the Cold Archive or Deep Cold Archive storage. | Restore Cold Archive data before you access the data. |
The input file is stored in OSS by using the Archive storage and the real-time access feature is disabled for the input file or the input file is not restored. | Enable the real-time access feature for Archive data or restore the data before you access the data. |
The referer-based hotlink protection feature is enabled for the OSS bucket in which the input file resides. | To automatically trigger a workflow, you must configure a referer for the OSS bucket in which the input file resides. If you submit the snapshot job by using another method, you must add the Referer parameter to the Input parameter. |
What do I do if the error code "InvalidParameter.ResourceContentBad" is returned?
This error code is returned if a snapshot job fails to be submitted or the snapshot job fails because parameter configuration conflicts occur or the input file is damaged. Troubleshoot the error by performing the following steps:
Check whether the input file is normal.
Check whether the parameters are correctly configured for the snapshot job, especially the Time, FrameType, and OutputFile parameters.
If the error persists, contact Alibaba Cloud technical support and provide your region ID and request ID for troubleshooting.
What do I do if I fail to submit a snapshot job in synchronous mode for an M3U8 file?
If you submit a snapshot job in synchronous mode for an M3U8 file, make sure that the Transport Stream (TS) files referenced in the M3U8 index are in the same directory as the M3U8 file. If you submit a snapshot job in asynchronous mode for an M3U8 file, the TS files referenced in the M3U8 index and the M3U8 file can be in different directories.
What do I do if I fail to submit a snapshot job to capture a single snapshot because the point in time at which the snapshot is captured is greater than the video length?
Error code: InvalidParameter.ResourceContentBad
Error message: The resource operated InputFile is bad
Cause | Solution |
If you submit a snapshot job to capture a single regular frame and set the Time parameter to a value that is greater than the video length, the snapshot job fails to be submitted. | Set the Time parameter to a value that is smaller than the video length. Alternatively, you can submit a snapshot job to capture a single keyframe. If you set the Time parameter to a value that is greater than the video length, the keyframe that is closest to the specified point in time is captured. |
What do I do if I fail to submit a snapshot job and the error message indicates that format of the Object parameter in the OutputFile parameter is invalid?
Error code: InvalidParameter.ResourceContentBad
Error message: The format of parameter "SnapshotConfig:OutputFile:Object" is invalid
Cause | Solution |
The value of the Object parameter in the OutputFile parameter does not contain the {count} placeholder when you submit a snapshot job to capture multiple snapshots. In this case, the snapshot job fails to be submitted due to the invalid parameter setting. | Add {Count} to the value of the Object parameter in the OutputFile parameter to prevent multiple snapshots in the same path from overwriting each other. |
The Format parameter is set to vtt to capture Web Video Text Tracks Format (WebVTT) snapshots, but the file name extension in the value of the Object parameter is not .vtt in the OutputFile parameter. In this case, the snapshot job fails to be submitted due to the invalid parameter setting. | Change the file name extension in the value of the Object parameter to .vtt in the OutputFile parameter. |
What do I do if I fail to submit a snapshot job and the error message indicates that the format of the Object parameter in the TileOutputFile parameter is invalid?
Error code: InvalidParameter.ResourceContentBad
Error message: The format of parameter "SnapshotConfig:TileOutputFile:Object" is invalid
Cause | Solution |
The value of the Object parameter in the OutputFile parameter does not contain the {TileCount} placeholder when you submit a snapshot job to generate sprites. In this case, the snapshot job fails to be submitted due to the invalid parameter setting. | Add {TileCount} to the value of the Object parameter in the TileOutputFile parameter to prevent the sprites in the same path from overwriting each other. |
FAQ about snapshot job configurations
How do I distinguish between snapshot jobs in synchronous mode and snapshot jobs in asynchronous mode?
If the Interval or Num parameter is specified in the SnapshotConfig parameter of a snapshot job, the snapshot job is in asynchronous mode regardless of whether the PiplineId parameter is specified.
What happens if I set the point in time at which a snapshot is captured to a value that is greater than the video length?
If you submit a snapshot job to capture a single snapshot and set the Time parameter to a value that is greater than the video length, the following results are returned based on the type of the frame that you want to capture:
Regular frame: The snapshot job fails. The error code "InvalidParameter.ResourceContentBad" and the error message "The resource operated InputFile is bad" are returned.
Keyframe: The snapshot job is successful. The keyframe that is closest to the specified point in time is captured.
If you submit a snapshot job to capture multiple snapshots and the value of the Time parameter plus the value of the Interval parameter times the value of the Num parameter is greater than the video length, the snapshot job is successful. If the point in time at which a snapshot is captured is equal to or smaller than the video length, the snapshot is captured. If the point in time at which a snapshot is captured is greater than the video length, the snapshot is not captured. After the snapshot job is complete, the number of captured snapshots is returned.
FAQ about snapshots that do not meet requirements
What do I do if the number of snapshots is different from the value of the Num parameter?
Troubleshoot the error based on the causes that are described in the following table.
Cause | Solution |
When you submit a snapshot job to generate both snapshots and sprites, the same path in an OSS bucket is specified for the snapshots and sprites. As a result, the snapshots and sprites overwrite each other. | Specify different OSS buckets or paths for sprites and snapshots. |
Both the Interval and Num parameters are specified to capture snapshots in sampling mode. The number of captured snapshots may be different from the value of the Num parameter if the video is not long enough. | The result is normal. |
The black frame detection feature is enabled when you submit a snapshot job to capture a single snapshot. No snapshot is captured if black frames are filtered out. | If you do not want to filter out black frames, you can change the values of the BlackLevel and PixelBlackThreshold parameters. |
The FrameType parameter is set to intra to capture I frames. The number of captured snapshots may be different from the value of the Num parameter due to the following causes:
| If you want to capture snapshots at precise points in time, set the FrameType parameter to normal. |
What do I do if the point in time at which the snapshot is captured is different from the value of the Time parameter?
Cause | Solution |
The FrameType parameter is set to intra to capture I frames. Keyframes appear at an interval in the video. Therefore, the points in time at which the snapshots are captured are not precise. The keyframes that are closest to the points in time are captured. | If you want to capture snapshots at precise points in time, set the FrameType parameter to normal. |
What do I do if the snapshots are blurry?
Cause | Solution |
The FrameType parameter to normal to capture regular frames. Regular frames are not as clear as keyframes. | If you want to capture clearer snapshots, set the FrameType parameter to intra. |
What do I do if the snapshots are distorted or the aspect ratio of the snapshots is not that specified in the parameter settings?
Troubleshoot the error based on the causes that are described in the following table.
Cause | Solution |
Both the width and height of the snapshots are specified, but the aspect ratio is different from that of the input video. | We recommend that you specify only the width or height of the snapshots. The aspect ratio remains unchanged based on the resolution of the input video. This prevents image distortion. |
Both the width and height of cells in sprites are specified, but the aspect ratio is different from that of the input video. As a result, the snapshots in a sprite are distorted. | We recommend that you specify only the width or height of cells in sprites. The aspect ratio remains unchanged based on the resolution of the input video. This prevents image distortion. |
MPS is incompatible with the display aspect ratio (DAR) or sample aspect ratio (SAR) of the input video. | Contact Alibaba Cloud technical support and provide your region ID and snapshot job ID for troubleshooting. |
What do I do if the input video is in portrait mode but snapshots are in landscape mode?
An input MP4 video in portrait mode has a rotation identifier. Therefore, the snapshots are in landscape mode. In most cases, videos that are captured by mobile devices have a rotation identifier.
To check whether an input video has a rotation identifier, perform the following operation:
Call the SubmitMediaInfoJob operation to view the value of the Rotate parameter. If the value is -90 or 90, the video is rotated 90 degrees to the left or right. As a result, the display mode of the snapshots is different from that of the input video.
What do I do if no sprite is generated or no WebVTT snapshot is captured when I submit a snapshot job in synchronous mode?
Parameters related to sprites or WebVTT snapshots are specified when you submitted a snapshot job in synchronous mode to capture a single snapshot. You can submit a snapshot job in synchronous mode to capture only one snapshot. The snapshot job cannot generate a sprite or capture a WebVTT snapshot. To generate sprites or capture WebVTT snapshots, submit a snapshot job in asynchronous mode.