Generate a preview thumbnail

Usage example

{
  "steps": {
    "previewed": {
      "robot": "/file/preview",
      "use": ":original",
      "height": 400,
      "width": 300,
      "format": "png"
    }
  }
}

Parameters

• output_meta

  Record<string, boolean> | boolean

  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.

• result

  boolean (default: false)

  Whether the results of this Step should be present in the Assembly Status JSON

• queue

  "batch"

  Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times

• force_accept

  boolean (default: false)
  

    Force a Robot to accept a file type it would have ignored.
  

  By default Robots ignore files they are not familiar with. 🤖/video/encode, for example, will happily ignore input images.

  With the force_accept parameter set to true you can force Robots to accept all files thrown at them. This will typically lead to errors and should only be used for debugging or combatting edge cases.

• use

  string | Array<string> | Array<object> | object

  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"
      ]
    }
    

  Tip

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

• format

  "gif" | "jpg" | "png" (default: "png")

  The output format for the generated thumbnail image. If a short video clip is generated using the clip strategy, its format is defined by clip_format.

• width

  number (default: 300)

  Width of the thumbnail, in pixels.

• height

  number (default: 200)

  Height of the thumbnail, in pixels.

• resize_strategy

  … (default: "pad")

  To achieve the desired dimensions of the preview thumbnail, the Robot might have to resize the generated image. This happens, for example, when the dimensions of a frame extracted from a video do not match the chosen width and height parameters.

  See the list of available resize strategies for more details.

• background

  string (default: "#ffffffff")

  The hexadecimal code of the color used to fill the background (only used for the pad resize strategy). The format is #rrggbb[aa] (red, green, blue, alpha). Use #00000000 for a transparent padding.

• strategy

  object

  Definition of the thumbnail generation process per file category. The parameter must be an object whose keys can be one of the file categories: audio, video, image, document, archive, webpage, and unknown. The corresponding value is an array of strategies for the specific file category. See the above section for a list of all available strategies.

  For each file, the Robot will attempt to use the first strategy to generate the thumbnail. If this process fails (e.g., because no artwork is available in a video file), the next strategy is attempted. This is repeated until either a thumbnail is generated or the list is exhausted. Selecting the icon strategy as the last entry provides a fallback mechanism to ensure that an appropriate strategy is always available.

  The parameter defaults to the following definition:

  

  {
    "audio": ["artwork", "waveform", "icon"],
    "video": ["artwork", "frame", "icon"],
    "document": ["page", "icon"],
    "image": ["image", "icon"],
    "webpage": ["render", "icon"],
    "archive": ["icon"],
    "unknown": ["icon"]
  }
  

• waveform_center_color

  string (default: "#000000ff")

  The color used in the center of the waveform's gradient. The format is #rrggbb[aa] (red, green, blue, alpha). Only used if the waveform strategy for audio files is applied.

• waveform_outer_color

  string (default: "#000000ff")

  The color used in the outer parts of the waveform's gradient. The format is #rrggbb[aa] (red, green, blue, alpha). Only used if the waveform strategy for audio files is applied.

• waveform_height

  string | number (default: 100)

  Height of the waveform, in pixels. Only used if the waveform strategy for audio files is applied. It can be utilized to ensure that the waveform only takes up a section of the preview thumbnail.

• waveform_width

  string | number (default: 300)

  Width of the waveform, in pixels. Only used if the waveform strategy for audio files is applied. It can be utilized to ensure that the waveform only takes up a section of the preview thumbnail.

• icon_style

  "square" | "with-text" (default: "with-text")

  The style of the icon generated if the icon strategy is applied. The default style, with-text, includes an icon showing the file type and a text box below it, whose content can be controlled by the icon_text_content parameter and defaults to the file extension (e.g. MP4, JPEG). The square style only includes a square variant of the icon showing the file type. Below are exemplary previews generated for a text file utilizing the different styles:

  
  
  with-text style:
  
  
  square style:
  

• icon_text_color

  string (default: "#a2a2a2")

  The color of the text used in the icon. The format is #rrggbb[aa]. Only used if the icon strategy is applied.

• icon_text_font

  string (default: "Roboto")

  The font family of the text used in the icon. Only used if the icon strategy is applied. Here is a list of all supported fonts.

• icon_text_content

  "extension" | "none" (default: "extension")

  The content of the text box in generated icons. Only used if the icon_style parameter is set to with-text. The default value, extension, adds the file extension (e.g. MP4, JPEG) to the icon. The value none can be used to render an empty text box, which is useful if no text should not be included in the raster image, but some place should be reserved in the image for later overlaying custom text over the image using HTML etc.

• optimize

  boolean (default: true)

  Specifies whether the generated preview image should be optimized to reduce the image's file size while keeping their quaility. If enabled, the images will be optimized using 🤖/image/optimize.

• optimize_priority

  "compression-ratio" | "conversion-speed" (default: "conversion-speed")

  Specifies whether conversion speed or compression ratio is prioritized when optimizing images. Only used if optimize is enabled. Please see the 🤖/image/optimize documentation for more details.

• optimize_progressive

  boolean (default: false)

  Specifies whether images should be interlaced, which makes the result image load progressively in browsers. Only used if optimize is enabled. Please see the 🤖/image/optimize documentation for more details.

• clip_format

  … (default: "webp")

  The animated image format for the generated video clip. Only used if the clip strategy for video files is applied.

  Please consult the MDN Web Docs for detailed information about the image formats and their characteristics. GIF enjoys the broadest support in software, but only supports a limit color palette. APNG supports a variety of color depths, but its lossless compression produces large images for videos. AVIF is a modern image format that offers great compression, but proper support for animations is still lacking in some browsers. WebP on the other hand, enjoys broad support while offering a great balance between small file sizes and good visual quality, making it the default clip format.

• clip_offset

  string | number (default: 1)

  The start position in seconds of where the clip is cut. Only used if the clip strategy for video files is applied. Be aware that for larger video only the first few MBs of the file may be imported to improve speed. Larger offsets may seek to a position outside of the imported part and thus fail to generate a clip.

• clip_duration

  string | number (default: 5)

  The duration in seconds of the generated video clip. Only used if the clip strategy for video files is applied. Be aware that a longer clip duration also results in a larger file size, which might be undesirable for previews.

• clip_framerate

  string | number (default: 5)

  The framerate of the generated video clip. Only used if the clip strategy for video files is applied. Be aware that a higher framerate appears smoother but also results in a larger file size, which might be undesirable for previews.

• clip_loop

  boolean (default: true)

  Specifies whether the generated animated image should loop forever (true) or stop after playing the animation once (false). Only used if the clip strategy for video files is applied.

Related blog posts