Generate thumbnail images

MK.IO supports thumbnail generation transforms that allow extraction of images from the source content.

☝️

Thumbnail generation is only available for MP4 content and requires a server manifest (.ism) file provided as input to the job.

Depending on your use case, you can extract a single image, extract multiple images or generate a sprite image.

The following table lists the configuration parameters for the thumbnail generation:

ParameterDesrciption
formatThe output file format for the thumbnail. Can be either Png or Jpeg.
Only Jpeg can be used to produce sprite files.
widthThe width of the output video for this layer. The value can be absolute (in pixels) or relative (in percentage). For example 50% means the output video has half as many pixels in width as the input.
If only width is given and value is in pixels, the height will be calculated to preserve aspect ration.
If either width/height is defined as percentage, the other dimension must be the same percentage.
heightThe height of the output video for this layer. The value can be absolute (in pixels) or relative (in percentage). For example 50% means the output video has half as many pixels in height as the input.
If only height is given and value is in pixels, the width will be calculated to preserve aspect ration.
If either width/height is defined as percentage, the other dimension must be the same percentage.
startThe position in the input video from where to start generating thumbnails. The value can be in ISO8601 format (For example, PT05S to start at 5 seconds) or a relative value to asset duration (For example, 10% to start at 10% of stream duration).
The default value is 0, which means to start at the beginning of the asset.
rangeThe position relative to start time in the input video at which to stop generating thumbnails. The value can be in ISO8601 format (For example, PT5M30S to stop at 5 minutes and 30 seconds from start time) or a relative value to the asset duration (For example, 50% to stop at half of stream duration from start time).
The default value is 100%, which means to stop at the end of the asset.
If this value is 1, only a single thumbnail will be generated at start time.
stepThe intervals at which thumbnails are generated. The value can be in ISO8601 format (For example, PT05S for one image every 5 seconds) or a relative value to asset duration (For example, 10% for one image every 10% of stream duration).
If step is not specificed or if range is set to 1, a single thumbnail will be generated.
labelUsed to create the output filename as {BaseFilename}_{Label}{Index}{Extension}.
When generating sprites, the output VTT file will be named {BaseFilename}_{Label}.vtt
qualityThe compression quality of the JPEG images between 0 and 100. Default value is 70.
spriteColumnMultiple thumbnails can be aggregated in a sprite image

Below are sample transforms that illustrate how to use those parameters. Once the transform is in place, it can be used by creating a job on a given VOD asset Run VOD processing jobs

Transform to generate a single thumbnail

Below is a sample transform that will generate a single PNG image 10s after the start of the content.
The image will be half the size of the top resolution of the input content.

curl --request PUT \
     --url https://api.io.mediakind.com/api/ams/project_name/transforms/transform_name \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer bearer-token' \
     --data '
{
  "properties": {
    "outputs": [
      {
        "preset": {
          "@odata.type": "#MediaKind.ThumbnailGeneratorPreset",
          "thumbnails": [ 
            {
              "format": "Png",
              "start": "PT10S",
              "width": "50%",
              "height": "50%"
            }
          ]
        }
      }
    ]
  }
}
'

Transform to generate multiple thumbnails

The transform below generates one JPEG image every 30s during 80% of the input content.
The size of the image is defined by its width and the height will be calculated to maintain aspect ration:

curl --request PUT \
     --url https://api.io.mediakind.com/api/ams/project_name/transforms/transform_name \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer bearer-token' \
     --data '
{
  "properties": {
    "outputs": [
      {
        "preset": {
          "@odata.type": "#MediaKind.ThumbnailGeneratorPreset",
          "thumbnails": [
            {
              "format": "Jpeg",
              "start": "10%",
              "range": "90%",
              "step": "PT30S",
              "width": "480",
              "quality": 70
            }
          ]
        }
      }
    ]
  }
}
'

When multiple thumbnails are generated, MK.IOwill also generate a VTT file to reference the associated timing.

Transform to generate a sprite file

MK.IO also gives the ability to generate a sprite file along with the associated VTT file.

The transform below generates one JPEG image every 1% of the content and organize them in a 10x10 sprite file.

curl --request PUT \
     --url https://api.io.mediakind.com/api/ams/project_name/transforms/transform_name \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer bearer-token' \
     --data '
{
  "properties": {
    "outputs": [
      {
        "preset": {
          "@odata.type": "#MediaKind.ThumbnailGeneratorPreset",
          "thumbnails": [
            {
              "format": "Jpeg",
              "start": "PT0S",
              "range": "100%",
              "step": "1%",
              "width": "10%",
              "height": "10%",
              "spriteColumn": 10
            }
          ]
        }
      }
    ]
  }
}
'

Sprite files can then be side loaded into players for scrubbing as describe in this article Playout of a VOD asset with thumbnails seeking