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.
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 requiredSpecifies 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
andheight
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: autoDefinition 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
, andunknown
. 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. Thesquare
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.