Our /video/thumbs Robot

Extract thumbnails from videos

🤖/video/thumbs extracts any number of images from videos for use as previews.

Note: Even though thumbnails are extracted from videos in parallel, we sort the thumbnails before adding them to the Assembly results. So the order in which they appear there reflects the order in which they appear in the video. You can also make sure by checking the thumb_index meta key.

Usage example

Extract 10 thumbnails from each uploaded video:

{
  "steps": {
    "thumbnailed": {
      "robot": "/video/thumbs",
      "use": ":original",
      "count": 10,
      "ffmpeg_stack": "v6.0.0"
    }
  }
}

Parameters

  • use

    String / Array of Strings / Object required

    Specifies which Step(s) to use as input.

    • You can pick any names for Steps except ":original" (reserved for user uploads handled by Transloadit)

    • You can provide several Steps as input with arrays:

      "use": [
  ":original",
  "encoded",
  "resized"
]

    💡 That’s likely all you need to know about use, but you can view Advanced use cases.

  • output_meta

    Object / Boolean ⋅ default: {}

    Allows you to specify a set of metadata that is more expensive on CPU power to calculate, and thus is disabled by default to keep your Assemblies processing fast.

    For images, you can add "has_transparency": true in this object to extract if the image contains transparent parts and "dominant_colors": true to extract an array of hexadecimal color codes from the image.

    For videos, you can add the "colorspace: true" parameter to extract the colorspace of the output video.

    For audio, you can add "mean_volume": true to get a single value representing the mean average volume of the audio file.

    You can also set this to false to skip metadata extraction and speed up transcoding.

  • count

    Integer(1-999) ⋅ default: 8

    The number of thumbnails to be extracted. As some videos have incorrect durations, the actual number of thumbnails generated may be less in rare cases. The maximum number of thumbnails we currently allow is 999.

    The thumbnails are taken at regular intervals, determined by dividing the video duration by the count. For example, a count of 3 will produce thumbnails at 25%, 50% and 75% through the video.

    To extract thumbnails for specific timestamps, use the offsets parameter.

  • offsets

    Array of Integers / Array of Strings ⋅ default: []

    An array of offsets representing seconds of the file duration, such as [ 2, 45, 120 ]. Millisecond durations of a file can also be used by using decimal place values. For example, an offset from 1250 milliseconds would be represented with 1.25. Offsets can also be percentage values such as [ "2%", "50%", "75%" ].

    This option cannot be used with the count parameter, and takes precedence if both are specified. Out-of-range offsets are silently ignored.

  • format

    String ⋅ default: "jpeg"

    The format of the extracted thumbnail. Supported values are "jpg", "jpeg" and "png". Even if you specify the format to be "jpeg" the resulting thumbnails will have a "jpg" file extension.

  • width

    Integer(1-1920) ⋅ default: Width of the video

    The width of the thumbnail, in pixels.

  • height

    Integer(1-1080) ⋅ default: Height of the video

    The height of the thumbnail, in pixels.

  • resize_strategy

    String ⋅ default: "pad"

    One of the available resize strategies.

  • background

    String ⋅ default: "00000000"

    The background color of the resulting thumbnails in the "rrggbbaa" format (red, green, blue, alpha) when used with the "pad" resize strategy. The default color is black.

  • rotate

    Integer ⋅ default: auto [?]

    Forces the video to be rotated by the specified degree integer. Currently, only multiples of 90 are supported. We automatically correct the orientation of many videos when the orientation is provided by the camera. This option is only useful for videos requiring rotation because it was not detected by the camera.

FFmpeg parameters

  • ffmpeg_stack

    String ⋅ default: "v5.0.0"

    Selects the FFmpeg stack version to use for encoding. These versions reflect real FFmpeg versions. We currently recommend to use "v6.0.0".

    Supported values: "v5.0.0", "v6.0.0".

    A full comparison of video presets, per stack, can be found here.

Demos

Related blog posts