Generate a preview thumbnail

This feature is still in an experimental stage. Its exact behavior, its parameters, and its pricing might change while we continue to work on it. If you encounter any bugs or odd behavior, please contact us.

This Robot's purpose is to generate a meaningful preview image for any file, in such a way that the resulting thumbnail highlights the file's content. The goal is not to losslessly present the original media in a smaller way. Instead, it is to maximize the chance of a person recognizing the media at a glance, while being visually pleasing and consistent with other previews. The generation process depends on the file type. For example, the Robot can extract artwork from media files, frames from videos, generate a waveform for audio files, and preview the content of documents and images. The details of all available strategies are provided in the next section.

If no file-specific thumbnail can be generated because the file type is not supported, a generic icon containing the file extension will be generated.

The default parameters ensure that the Robot always generates a preview image with the predefined dimensions and formats, to allow an easy integration into your application's UI.

Strategies

The Robot groups each file into one category based on its type: audio, video, image, document (PDFs, Word documents, PowerPoint presentations etc.), archive (ZIP, RAR etc.), webpage (HTML), or unknown (for all unsupported files types).

For each category, multiple thumbnail generation strategies are available. Using the strategy parameter, you can define a list of strategies per file category. The Robot will go through the list, attempting each strategy until one succeeds. This approach allows you to customize the preview generation process to your application's needs.

The available strategies are:

• For audio files:
  • artwork: extract artwork embedded in the audio file, if available, using the 🤖/audio/artwork Robot.
  • waveform: generate a waveform visualizing the audio intensity over time, using the 🤖/audio/waveform Robot.
• For video files:
  • artwork: extract artwork embedded in the video file, if available, using the 🤖/video/artwork Robot.
  • frame: extract a frame from the video to preview its content, using the 🤖/video/thumbs Robot.
• For image files:
  • image: resize the image to the specified dimensions and format, using the 🤖/image/resize Robot.
• For document files:
  • page: display the first page of a text document or presentation, using the 🤖/document/thumbs (for PDFs) and 🤖/document/convert Robots.
• For webpage files:
  • render: render the HTML in a browser and take a screenshot of the web page, using the 🤖/html/convert Robot.

For all categories (including unknown and archive), the icon strategy is available as well. It generates a generic thumbnail featuring a category-specific icon and optionally the file's extension, using the 🤖/image/resize Robot. This way, the file type is visualized, but its exact content is not. The icon strategy is especially useful as a fallback method when other strategies are not available.

Pricing

The /file/preview Robot internally uses other Robots for generating the desired thumbnail, as listed in the description of the available strategies in the section above. To account for the varying computational effort between different strategies, the /file/preview Robot does not have a fixed pricing, but is billed according to the Robot that is used under the hood. For example, if an Assembly generated a thumbnail using /file/preview's frame strategy for videos, it will be billed as a 🤖/video/thumbs Step. It will then also show up as 🤖/video/thumbs usage on your invoice.

For the artwork, waveform, page, and render strategies, an additional charge is billed for the image resizing, because the underlying Robots are not capable of performing a resize operation. Thus, an additional 🤖/image/resize Step is necessary, which will show up as 🤖/image/resize usage on your invoice.

As an example, if a 1 MB audio file generates a 0.5 MB waveform with the waveform strategy and this waveform is then resized into a 0.1 MB thumbnail, 1.5 MB (= 1 MB + 0.5 MB) will be billed according to 🤖/audio/waveform's rules and 0.6 MB (= 0.6 MB + 0.1 MB) will be billed according to 🤖/image/resize's rules.

Usage example

Generate a preview thumbnail for any uploaded file:

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

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.

• format

  String ⋅ default: "png"

  The output format for the generated thumbnail image. Possible formats are "jpg", "png", and "gif".

• width

  Integer(1-5000) ⋅ default: 300

  Width of the thumbnail, in pixels.

• height

  Integer(1-5000) ⋅ default: 200

  Height of the thumbnail, in pixels.

• resize_strategy

  String ⋅ 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: "#ffffff"

  The hexadecimal code of the color used to fill the background (only used for the pad resize strategy).

• strategy

  Object ⋅ default: auto

  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 parameters

• waveform_center_color

  String ⋅ default: "000000ff"

  The color used in the center of the waveform's gradient. The format is "rrggbbaa" (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 "rrggbbaa" (red, green, blue, alpha). Only used if the waveform strategy for audio files is applied.

• waveform_height

  Integer(1-5000) ⋅ 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

  Integer(1-5000) ⋅ 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 parameters

• icon_style

  String ⋅ 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 the file extension (e.g. MP4, JPEG) below it. 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. 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.