Thumbnails generation transforms are created using the transform endpoint from MK.IO API.

⚠️
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.

Thumbnails preset must use the #MediaKind.ThumbnailGeneratorPreset value for @data.type attribute.

Configuration parameters

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

Parameter	Description
`format`	The output file format for the thumbnail. Can be either `Png` or `Jpeg`. Only `Jpeg` can be used to produce sprite files.
`width`	The 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 ratio. If either width/height is defined as percentage, the other dimension must be the same percentage.
`height`	The 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 ratio. If either width/height is defined as percentage, the other dimension must be the same percentage.
`start`	The position in the input video from where to start generating thumbnails. The value can be in ISO8601 format with second-level precision (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.
`range`	The position relative to start time in the input video at which to stop generating thumbnails. The value can be in ISO8601 format with second-level precision (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 the start time.
`step`	The interval at which thumbnails are generated. The value can be in ISO8601 format with second-level precision (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 specified or if range is set to `1`, a single thumbnail will be generated.
`label`	Used to create the output filename as `{BaseFilename}_{Label}{Index}{Extension}`. When generating sprites, the output VTT file will be named `{BaseFilename}_{Label}.vtt`
`quality`	The compression quality of the JPEG images between 0 and 100. Default value is 70.
`spriteColumn`	Multiple thumbnails can be aggregated in a sprite image.

Transform examples

Below are sample transforms that illustrate how to use these parameters.

Once the transform is in place, it can be used to create a job on a given VOD asset.

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.mk.io/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 ratio:

curl --request PUT \
     --url https://api.mk.io/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.IO will 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.mk.io/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.

Combined generation of thumbnail and sprite files

MK.IO allows generating multiple thumbnail configuration in a single operation.

The transform below generates one JPEG image every 1% of the content and organize them in a 10x10 sprite file. It also generates a single PNG thumbnail with a fixed 1920x960 size.

curl --request PUT \
     --url https://api.mk.io/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,
              "quality": 90,
              "label": "Sprite"
            },
            {
              "format": "Png",
              "start": "PT01S",
              "width": "1920",
              "height": "960",
              "label": "Thumbnail"
            }
          ]
        }
      }
    ]
  }
}
'