# Viewing thumbnails of the source video Monitoring with thumbnails AWS Elemental MediaConnect can generate JPEG-format thumbnails of the video that is in the source in any type of flow except for CDI flows. The thumbnail provides a visual verification that the content contains video. You can view the thumbnails on the console or retrieve them programmatically. ## How thumbnails are generated When you have enabled thumbnails in a flow and when the flow is active, MediaConnect generates a JPEG thumbnail with a 480 x 270 resolution. The rate for generating the thumbnail is as follows: + The fastest possible rate is one image every second. + The rate might be slower, depending on the characteristics of the source video. For example, one image every 6 seconds. ## How thumbnails are displayed As soon as the thumbnail is generated, MediaConnect displays it in the flow **Details** page, in the **Preview** section. It also makes the thumbnail available as base 64 binary data. You can use an AWS API to work with the binary data programmatically. MediaConnect encrypts thumbnails during retrieval to the console Preview window or in transit for API responses. The retrieval rate for thumbnails is as follows: + The refresh rate for the MediaConnect console is every 2 seconds. If the rate is faster than the generation rate, the same thumbnail is displayed more than once on the console. + The API retrieve rate is constrained by the [maximum TPS](quotas.md#limits-api). This constraint only matters if you are trying to retrieve thumbnails for multiple flows. If you are retrieving thumbnails for only one flow, there is no point retrieving the thumbnail more often than every second (the fastest possible generation rate). **Topics** + [ ## How thumbnails are generated ](#thumbnails-how-generated) + [ ## How thumbnails are displayed ](#thumbnails-how-displayed) + [ # Requirements for thumbnails ](thumbnails-specifications.md) + [ ## Limit on thumbnails in MediaConnect ](#thumbnails-api-limits) + [ # Enabling and viewing thumbnails in the console ](thumbnails-enable-view-console.md) + [ # Enabling and retrieving thumbnails programmatically ](thumbnails-enable-retrieve-programatically.md) # Requirements for thumbnails Requirements ## Requirements for the video source For MediaConnect to successfully generate thumbnails, make sure that the video source meets the following requirements. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediaconnect/latest/ug/thumbnails-specifications.html) ## Requirements for the flow To successfully generate thumbnails, make sure that your flow meets the following requirements. | Characteristic of the flow | Requirement | | --- | --- | | Type of flows that support thumbnails | Any type of flow except CDI flows. | | Maximum number of outputs that can be attached to the flow | 10If the flow exceeds this limit, then MediaConnect won't generate any thumbnails for this flow. | | Maximum bitrate for all the outputs that are attached to the flow | 400 MbpsIf the flow exceeds this limit, then MediaConnect won't generate any thumbnails for this flow. | ## Limit on thumbnails in MediaConnect There is a limit to the number of thumbnails that you can view or retrieve. This limit is the TPS (transactions per second). The thumbnails feature shares the global limits for MediaConnect. For more details, see [Limits for API requests](quotas.md#limits-api). # Enabling and viewing thumbnails in the console View thumbnails using the console You enable thumbnails separately in each flow. You can enable thumbnails when you are creating the flow, or you can enable them in an existing flow. After you have enabled thumbnails, MediaConnect automatically starts to generate them whenever the flow is active. ## Enabling when you create a flow In the flow that you are creating, go to the **Source monitor configuration** section, and move the **Thumbnails state** slider to **Enabled**. When you start the new flow, MediaConnect will start to generate thumbnails. ## Enabling in an existing flow 1. On the left navigation bar, choose **Flows**. Select the flow by its name. 1. On the flow **Details** page, choose the **Sources** tab. In the **Source monitoring configuration** section, choose **Edit**. 1. Move the **Thumbnails state** slider to **Enabled**, then choose **Update**. If the flow is currently active, MediaConnect starts to generate thumbnails. You can enable and disable the thumbnails as often as you want, when the flow is active or inactive. ## Viewing thumbnails When thumbnails are enabled in an active flow, MediaConnect automatically generates thumbnails and displays them in the flow **Details** page, in the **Preview** section. If the flow becomes inactive, the thumbnail preview stops refreshing. After a few seconds, the preview is replaced by a message. **Viewing thumbnails on several flows** You might open several instances of the MediaConnect console, one instance for each active flow. You can do this, but if you enable thumbnails in all the instances, there might be issues with displaying thumbnails in one or more of the instances. We recommend that you enable thumbnails on only one active flow at a time, and disable it on other active flows. ## Disabling thumbnails You can disable thumbnails on an active or inactive flow. If the flow is active, you don't have to stop it first. Go to the flow **Details** page, choose the **Sources** tab, and move the **Thumbnails state** slider to **Disabled**. Then choose **Update**. # Enabling and retrieving thumbnails programmatically You can use the AWS CLI to work with thumbnails programmatically. The following information assumes that you are familiar with the basics of using the AWS CLI. For information about the basics, see the [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/). You enable thumbnails separately in each flow. You can enable thumbnails when you first create a flow or you can enable them in an existing flow. After thumbnails are active, MediaConnect automatically starts to generate them whenever the flow is active. It generates one thumbnail at most once every second. (For more information about the generation rate, see [How thumbnails are generated](monitor-with-thumbnails.md#thumbnails-how-generated).) You can retrieve the most recently generated thumbnail. ## Enabling thumbnails Use the `CreateFlow` or `UpdateFlow` command. This command is represented differently in different interfaces: + In the AWS CLI, the commands are `create-flow` or `update-flow`. + In the API, the command is an `HTTP POST` on `CreateFlow` or by an `HTTP PUT` on `UpdateFlow`. + In the AWS SDKs, the command is represented by constructs that are suitable to that SDK language. **To enable thumbnails using the AWS CLI** Enter the `create-flow` or `update-flow` command. This example illustrates the `update-flow` command. Replace the ARN with your ARN. ``` aws mediaconnect update-flow --flow-arn arn:aws:mediaconnect:us-east-1:111122223333:flow:1-23aBC45dEF67hiJ8-12AbC34DE5fG:AwardsShow --source-monitoring-config ThumbnailState=ENABLED ``` ## Retrieving thumbnails To retrieve thumbnails with the AWS CLI, use the `DescribeFlowSourceThumbnail` command. This command is represented differently in different interfaces: + In the AWS CLI, the command is `describe-flow-source-thumbnail`. + In the API, the command is an `HTTP GET` on `Source-thumbnail`. + In the AWS SDKs, the command is represented by constructs that are suitable to that SDK language. **To retrieve thumbnails using the AWS CLI** Enter the `describe-flow-source-thumbnail` command. Replace the ARN with your ARN. ``` aws mediaconnect describe-flow-source-thumbnail --flow-arn arn:aws:mediaconnect:us-east-1:111122223333:flow:1-23aBC45dEF67hiJ8-12AbC34DE5fG:AwardsShow ``` **The response** The request results in a status code and a response. + **Status code 200**: The request was processed successfully. This typically means that the response includes the flow source thumbnail in base64 encoding. However, in some cases, MediaConnect might return a 200 status code even when a thumbnail couldn't be retrieved. In these situations, the response includes an error message explaining why the thumbnail couldn't be generated: + `ThumbnailDecodeError`: The video source doesn't meet [the requirements](thumbnails-specifications.md#thumbnails-source-video-requirements), or there is no ingress traffic on the flow. Therefore, MediaConnect can't generate a thumbnail. + `ThumbnailGenerationInProgress`: The thumbnail is still being generated. Wait a few seconds and try again. + `ThumbnailSuppressed`: Typically this error occurs because the CPU and memory required to process the flow is currently high. If MediaConnect generated thumbnails now, the flow handling would slow down. Try again after a few seconds. If the problem persists, see the information in [Requirements for the flow](thumbnails-specifications.md#thumbnails-flow-requirements). + **Status code 202**: The request is valid, but MediaConnect is still preparing the flow. As a result, a thumbnail can't be generated yet. Wait a few seconds and try again. + **Status code 4xx:** The request isn't valid. + **Status code 5xx**: The request is valid but MediaConnect couldn't fulfill the request.