Beta

Generate a preview thumbnail

🤖/file/preview generates a thumbnail for any uploaded file to preview its content, similar to the thumbnails in desktop file managers.

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. In addition, the generated preview images are optimized by default to reduce their file size while keeping their quality.

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.
- clip: extract a short clip from the video's beginning as an animated image to preview its first few seconds, using the 🤖/video/encode 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.

The clip, page (for non-PDF files), and render strategies are still under development and are not fully optimized yet. Assemblies using these strategies might experience longer execution times, making them not yet suitable for on-demand execution using our Smart CDN, where the first request would be slow but subsequent ones fast. This situation will improve as we further optimize the performance.

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.

If the optimize parameter is enabled, images will be optimized to reduce their file size and a corresponding charge for the use of 🤖/image/optimize will be billed.

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". If a short video clip is generated using the clip strategy, its format is defined by clip_format.
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: "#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 ⋅ 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 #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

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 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

String ⋅ 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.

Image optimization parameters

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

String ⋅ 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 generation parameters

clip_format

String ⋅ default: "webp"

The animated image format for the generated video clip. Only used if the clip strategy for video files is applied. Possible formats are "webp", "apng", "avif" and "gif".
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

Float ⋅ 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

Float ⋅ 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

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

Generate a preview thumbnail

Strategies

Pricing

Usage example

Parameters

`use`

`format`

`width`

`height`

`resize_strategy`

`background`

`strategy`

Waveform parameters

`waveform_center_color`

`waveform_outer_color`

`waveform_height`

`waveform_width`

Icon parameters

`icon_style`

`icon_text_color`

`icon_text_font`

`icon_text_content`

Image optimization parameters

`optimize`

`optimize_priority`

`optimize_progressive`

Clip generation parameters

`clip_format`

`clip_offset`

`clip_duration`

`clip_framerate`

`clip_loop`

Related blog posts