1. Overview of All Available Robots

Our robots import, convert and store your files, and each Assembly Step uses one robot. You can set parameters in your Assembly Step that define what each robot does with your files.

1.1 File Import Robots

These robots are available for importing your files from external resources. Please note that there is no special robot for uploading. Uploading is handled directly. Please check the minimal integration to learn how that is done.

Name Responsible for Description Documentation

/http/import

Importing files from web URLs

This robot is able to import any file that is publicly available via a web URL into Transloadit.

Documentation

/s3/import

Importing files from your Amazon S3 bucket

This robot is able to import whole directories of files from your S3 account.

Documentation

/sftp/import

Importing files from your server over sftp

This robot is able to import whole libraries of files from your SFTP servers into Transloadit. This robot relies on public key authentication.

Documentation

/ftp/import

Importing files from your server over ftp

This robot is able to import whole libraries of files from your FTP servers into Transloadit. No public key authentication is required. This robot relies on password access.

Documentation

1.2 Video Conversion Robots

Name Responsible for Description Documentation

/video/encode

Video encoding

This robot encodes videos into all kinds of formats for you. It can also apply watermarks to videos and handle HTTP Live Segmentation.

Documentation

/video/thumbs

Extracting thumbnail images or frames from videos.

This robot extracts a specific number of images from videos. You can determine their dimensions, rotation and resize strategies.

Documentation

/video/merge

Merges files to generate videos

This robot merges a given audio file and given image (or many images) to generate a video. It can also merge videos and audio files together.

Documentation

/video/concat

Concatenates videos together

This robot concatenates several videos together.

Documentation

/media/playlist

Generates media playlist files.

Merges segment files to generate playlist files for HTTP Live Streaming (HLS).

Documentation

1.3 Audio Conversion Robots

Name Responsible for Description Documentation

/audio/encode

Audio encoding

This robot converts audio files into all kinds of formats for you. We provide encoding presets for the most common formats. This robot also handles HTTP Live Segmentation.

Documentation

/audio/concat

Audio concatenation

This robot concatenates several audio files together.

Documentation

/audio/merge

Audio merging

This robot overlays several audio files on top of each other.

Documentation

/audio/loop

Audio looping

This robot loops one audio files as often as is required to match a given duration.

Documentation

/audio/waveform

Generating waveform images for audio files

This robot generates waveform images for your audio files and allows you to change their colors and dimensions.

Documentation

/audio/artwork

Audio artwork extraction and insertion

This robot extracts the embedded cover artwork from audio files and allows you to pipe it into other Steps, for example into /image/resize Steps. It can also insert images into audio files as cover artwork.

Documentation

1.3 Image Conversion Robots

Name Responsible for Description Documentation

/image/resize

Manipulating and resizing images

This robot can change your images in all kinds of ways. It can resize and crop them, change colorization, rotation, and apply text and image watermarks.

Documentation

/image/optimize

Provides lossless image optimization to save up to 80% on image file sizes

This robot enables you to lower your storage and bandwidth costs, and improves your user experience and monetization by reducing the load time of image-intensive web pages.

Documentation

/image/facedetect

Allows you to detect and extract human faces from images

You can either just detect faces in images and return their coordinates, or cut them from the original images and have them returned as images.

Documentation

/html/convert

Generates screenshots from uploaded HTML files and web URLs

If you want to take screenshots of web pages or generate screenshots from HTML pages, this robot is for you.

Documentation

1.4 Assembly Flow Logic Robots

Name Responsible for Description Documentation

/file/filter

Filtering uploaded, imported or converted files

Think of this robot as your if/else checks to construct advanced file conversion workflows and to not convert certain files that your users uploaded depending on their meta data.

Documentation

/file/virusscan

Filtering uploaded or imported files, rejecting viruses

While 100% security is a myth, having /file/virusscan as a gatekeeper bot helps reject millions of trojans, viruses, malware & other malicious threats before they reach your platform.

Documentation

1.5 File Export Robots

Name Responsible for Documentation

/s3/store

Exporting files to Amazon S3

Documentation

/sftp/store

Exporting files to your own SFTP server

Documentation

/ftp/store

Exporting files to your own FTP server

Documentation

/cloudfiles/store

Exporting files to Rackspace Cloudfiles

Documentation

/youtube/store

Exporting videos to YouTube

Documentation

/azure/store

Exporting files to Microsoft Azure

Documentation

/softlayer/store

Exporting files to Softlayer / IBM Cloud

Documentation

1.6 Other Robots

Name Responsible for Description Documentation

/document/thumbs

Extracts one or more thumbnails from a document.

This robot can generate an image for each page in a PDF file or an animated gif file that loops through all pages.

Documentation

/meta/write

Writing meta data into files

Write meta data into any file.

Documentation

/file/decompress

Extracting ZIP or other archive files

Extract entire archives of files to be used with other robots.

Documentation

/file/compress

Create a zip or tar archive of file conversion results

Create entire archives of files or file conversion results.

Documentation

2. File Import Robots

2.1 Import Files Over HTTP

Our /http/import robot

The /http/import bot can be used to import files from URLs over HTTP.

The result of this robot will carry a field import_url in their metadata, which references the URL from which they were imported. Further conversion results that use this file will also carry this import_url field. This allows you to to match conversion results with the original import URL that you used.

Parameters

Name Type Default Description

url

(required) String or Array of Strings

""

The URL from which the file to be imported can be retrieved. You can also specify an array of URLs or a string of | delimited URLs to import several files at once. Please also check the url_delimiter parameter for that.

url_delimiter

(required) String

"|"

Provides the delimiter that is used to split the URLs in your url parameter value.

headers

(required) Array of Strings

[]

Custom headers to be sent for file import. This is an empty array by default, such that no additional headers expect the necessary ones (e.g. Host) are sent.

force_name

String

Custom name for the imported file. Defaults to null, which means the file name is derived from the supplied URL.

ignore_errors

(required) Boolean

false

There might be an error coming up when importing files or trying to extract meta data from them. Setting this to true will cause the robot to not stop the import (and the entire Assembly) when that happens. This is especially useful when you use an array of URLs for the url parameter and thereby import several files at once.

Examples

2.2 Import Files Over SFTP

Our /sftp/import robot

The /sftp/import bot imports all files from a specified server via SFTP.

Parameters

Name Type Default Description

user

(required) String

The user to use for the SFTP connection.

host

(required) String

The host to connect to via SFTP.

path

(required) String

null

The path on your SFTP server where to search for files.

ignore_errors

(required) Boolean

false

There might be an error coming up when trying to extract meta data from your imported files. This happens for files that are zero bytes big for example. Setting this to true will cause the robot to not stop the import (and the entire Assembly) when that happens.

port

Integer

22

The port to use for the connection.

Installation on Your Server

The method explained here is slightly more elaborate than handing out an SSH account with an authorized public key, but is more secure, as the user will not be able to traverse outside their home directory. This way, even if the user account is compromised at some point, the accessible data would be recently uploaded files.

The following explains how to create a dedicated user and group for Transloadit, and restrict access as shown in this article.

First let's create a dedicated group & user:

# Change these variables to suit your needs.
# For additional security, use a randomly picked username.
TL_USER="random873"
TL_PUBLIC_PATH="uploads"

groupadd sftponly
useradd -g sftponly -m ${TL_USER}

# This line sets a random 20-character password for the user.
# We work with keys, but this is required because some operating systems will
# consider the account locked without one.
echo "${TL_USER}:$(cat /dev/urandom | tr -dc _A-Z-a-z-0-9 | head -c20)" |chpasswd

mkdir -p /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}

echo "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA57GdwNLqsWz03X8MBEe4KoMSY2HOURjnUUe9zeTivASI+BLEe3cZcuJjsEBaRpISvCH04hosWUI0H4BQeB1dZZUUW1s4ttnVohCD9CfNiXJ7pwJAvgWb01dTW4YUWFKUTpTeUwQzgcNVLDtSVaQOYh4lAKvCZEcz17X9iZ7AeSEuQKe+QsrcwQoBdSpQ6FnzKwSZsggK81dPiGIW9Cw2z/EZWJpl9QBTYhw25NbNRtZj3fXVbrejnQQ985eZ6TlrvQFpUVwyk0QNHDsN+7zVISM3eXNpxof+vJyQNDLN9tb8vNPf/HXuw7MDJWMphrQevF5V26aMzszl3ZeO1779Mw== sftp@transloadit.com" >> /home/${TL_USER}/.ssh/authorized_keys

chown -R ${TL_USER}.sftponly /home/${TL_USER}
chown root.root /home/${TL_USER}

chmod -R 600 /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
chmod -R u+X /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}

Make sure to change ${TL_USER} and ${TL_PUBLIC_PATH} to suit your needs. Remember to use a random username for additional security.

Next, we will set up SSH to cage SFTP users in their home directory, and deny them regular shell access.

Enter ${EDITOR} /etc/ssh/sshd_config, and then find and comment out this line:

# Subsystem sftp /usr/lib/openssh/sftp-server

At the bottom of the same file, add the following:

Subsystem sftp internal-sftp

Match group sftponly
    ChrootDirectory /home/%u
    X11Forwarding no
    AllowTcpForwarding no
    ForceCommand internal-sftp

Finally, enter /etc/init.d/ssh restart to reflect the changes made.

2.3 Import Files Over FTP

Our /ftp/import robot

The /ftp/import bot imports all files from a specified server via FTP.

Parameters

Name Type Default Description

host

(required) String

The host to connect to via FTP.

user

(required) String

The user to use for the FTP connection. For additional security we recommend setting up a separate FTP user with a name that is hard to guess.

password

(required) String

The password to use for the FTP connection.

path

(required) String

null

The path on your FTP server where to search for files. Files are imported recursively from all sub-directories and sub-sub-directories (and so on) from this path.

ignore_errors

(required) Boolean

false

There might be an error coming up when trying to extract meta data from your imported files. This happens for files that are zero bytes big for example. Setting this to true will cause the robot to not stop the import (and the entire Assembly) when that happens.

passive_mode

Boolean

true

Determines if passive mode should be used for the FTP connection.

2.4 Import Files From Amazon S3

Our /s3/import robot

The /s3/import robot imports files from a specified Amazon S3 bucket and path. You can import a single file from a given file path, or all files in a given directory path.

Since you need to provide your S3 credentials to this robot, please always use this together with Templates, to hide your Assembly Instructions.

Parameters

Name Type Default Description

key

(required) String

""

Your Amazon S3 key.

secret

(required) String

""

Your Amazon S3 secret.

bucket

(required) String

""

Your Amazon S3 bucket name.

bucket_region

String

"us-east-1"

The AWS region that your S3 bucket is in. If not provided, Transloadit will figure that out for you at some speed cost.

path

(required) String or Array of Strings

null

The path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example: js/my_javascript_file.js If it points to a directory, then all files from this directory will be imported. For example: js/ For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a / slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another robot Step. If you want to import all files from the root directory, please use / as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with /, you'll receive an error: A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist. You can also use an array of path strings here to import multiple paths in the same robot Step.

ignore_errors

(required) Boolean

false

There might be an error coming up when trying to extract meta data from your imported files. This happens for files that are zero bytes big for example. Setting this to true will cause the robot to not stop the import (and the entire Assembly) when that happens.

3. Video Robots

3.1 Video Encoding

Our /video/encode robot

The /video/encode robot converts a single video file or animated gif image into a given format.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

preset

String

"flash"

Converts a video according to pre-configured settings. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "flash" preset is not applied. This is to prevent you from having to override each of the flash preset's values manually. For a list of video presets, see video presets.

width

1 - 1920

Width of the input video

Width of the new video, in pixels.

height

1 - 1080

Height of the input video

Height of the new video, in pixels.

resize_strategy

String

"pad"

See the available resize strategies.

background

String

"00000000"

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

rotate

Integer

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. If you set rotate to false no rotation is performed, even if the metadata contains such instructions.

hint

Boolean

false

Enables hinting for mp4 files, for RTP/RTSP streaming.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. For available options, see the FFmpeg documentation. If a preset is used, the options specified are merged on top of the ones from the preset. The FFmpeg r parameter (framerate) has a default value of 25 and maximum value of 60. If you use ffmpeg_stack v2.0.0 or higher, and set r to null, you clear the default of 25 and can preserve the original video's framerate. For example:

steps: {
 video_encode: {
  robot        : "/video/encode",
  use          : ":original",
  ffmpeg_stack : "v2.0.0",
  preset       : "iphone-high",
  ffmpeg       : {
   b: "600k"
  }
 }
} 

ffmpeg_stack

String

"v1.0.0"

Selects the FFmpeg stack for the encoding. Valid values are "v1.0.0" , "v2.0.0", "v2.1.0" and "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

Watermark Parameters

With watermarking you can add an image to a video. This is usually used for logos, but you could also Surround a video with a frame if you cut out a transparent center from your image.

Name Type Default Description

watermark_url

String

""

A URL indicating a PNG image to be overlaid above this image. Please note that you can also supply the watermark via another Assembly Step.

watermark_position

String or Array

"center"

The position at which the watermark is placed. The available options are "center", "top", "bottom", "left", and "right". You can also combine options, such as "bottom-right". An array of possible values can also be specified, in which case one value will be selected at random, such as [ "center", "left", "bottom-left", "bottom-right" ]. This setting puts the watermark in the specified corner. To use a specific pixel offset for the watermark, you will need to add the padding to the image itself.

watermark_size

String

""

The size of the watermark, as a percentage, such as "50%".

watermark_resize_strategy

String

"fit"

Available values are "fit" and "stretch".

Supplying the Watermark via an Assembly Step

It is now possible to pass both the video and the watermark image to an Assembly Step via the use parameter, allowing you to either have both be part of the upload or to use results of other Assembly Steps as input to your /video/encode Step.

For this to work you just need to use the as-syntax:

my_video_step: {
  robot : "/video/encode",
  use   : {
    steps : [
      { name: ":original", as: "video" },
      { name: ":original", as: "watermark "}
    ]
  }
}

Here both the video and the watermark image are taken from the uploaded files. They are recognized automatically based on their file type.

If you use several file input fields, then you can tell Transloadit which field supplies the base video and which the watermark. Suppose you have two file input fields named the_video and the_watermark. These Assembly Instructions will make it work using the fields condition:

my_video_step: {
  robot : "/video/encode",
  use   : {
    steps : [
      { name: ":original", fields: "the_video", as: "video" },
      { name: ":original", fields: "the_watermark", as: "watermark "}
    ]
  }
}

Please note that the robot's watermark_url parameter will still continue to work.

HTTP Live Streaming Parameters

Transloadit supports Apple's HTTP Live Streaming so that you can conform to the iOS app requirements for video.

Live segmentation can be hard to implement but when you use Transloadit you only have to enable the following options:

Name Type Default Description

segment

Boolean

false

Splits the file into multiple parts, to be used for Apple's HTTP Live Streaming. .

segment_duration

Integer

10

Specifies the length of each HTTP segment. This is optional, and the default value as recommended by Apple is 10. Do not change this value unless you have a good reason.

segment_prefix

String

Basename of input

The prefix used for the naming. For example, a prefix of "segment_" would produce files named "segment_0.ts", "segment_1.ts", and so on. This is optional, and defaults to the base name of the input file. Also see the related segment_name parameter.

segment_name

String

"${segment_prefix}${segment_number}.ts"

The name used for the final segment. Available variables are ${segment_prefix}, ${segment_number} and ${segment_id} (which is a UUID).

Please use our /media/playlist robot to generate master index files - a text file with the .m3u8 file extension, referencing all the different segments and their duration.

Also, if you want to store your segments using the /s3/store robot for example, there will be a new Assembly variable available called ${file.meta.segment_index} that you can use in the path parameter.

Examples

3.2 Extracting Thumbnails From Videos

Our /video/thumbs robot

The /video/thumbs robot extracts one or more thumbnails from a video.

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.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

count

1 - 999

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 thumbails we currently allow is 999.

offsets

Array

[]

An array of offsets representing seconds of the file duration, such as [ 2, 45, 120 ]. 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

"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

1 - 1920

Width of the video

The width of the thumbnail, in pixels.

height

1 - 1080

Height of the video

The height of the thumbnail, in pixels.

resize_strategy

String

"pad"

One of the available resize strategies.

rotate

Integer

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

String

"v1.0.0"

Selects the FFmpeg stack for the encoding. Valid values are "v1.0.0" , "v2.0.0", "v2.1.0" and "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

Examples

3.3 Video Merging/Generation

Our /video/merge robot

The /video/merge robot is able to merge different kinds of files in order to generate a video. It is able to generate a video from:

  • an image and an audio file
  • a video and an audio file
  • several images

Parameters

Name Type Default Description

preset

String

"flash"

Generates the video according to pre-configured video presets. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "flash" preset is not applied. This is to prevent you from having to override each of the flash preset's values manually.

width

1 - 1920

Width of the input image

Width of the generated video, in pixels.

height

1 - 1080

Height of the input image

Height of the generated video, in pixels.

resize_strategy

String

"pad"

If the given width/height parameters are bigger than the input image's dimensions, then the resize_strategy determines how the image will be resized to match the provided width/height. See the available resize strategies.

background

String

"00000000"

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

framerate

String

"1/5"

When merging images to generate a video this is the input framerate. A value of "1/5" means each image is given 5 seconds before the next frame appears (the inverse of a framerate of "5"). Likewise for "1/10", "1/20", etc. A value of "5" means there are 5 frames per second.

duration

Float

5.0

When merging images to generate a video this is the desired target duration in seconds. The float value can take one decimal digit. If you want all images to be displayed exactly once, then you can set the duration according to this formula: duration = numberOfImages / framerate. This also works for the inverse framerate values like 1/5.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. For available options, see the FFmpeg documentation. If a preset is used, the options specified are merged on top of the ones from the preset.

ffmpeg_stack

String

"v1.0.0"

Selects the FFmpeg stack for the encoding. Valid values are "v1.0.0" , "v2.0.0", "v2.1.0" and "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

Merging an Audio File and an Image

To merge an audio file and an image to create a video please pass both the audio file and the image to an Assembly Step via the use parameter. For this to work you just need to use the as-syntax:

"my_merge_step": {
  robot : "/video/merge",
  preset: "ipad-high",
  use   : {
    steps : [
      { name: ":original", as: "audio" },
      { name: ":original", as: "image"}
    ]
  }
}

Imagine you have uploaded both an image and an audio file in the same upload form. In the above example the system will automatically recognize the files properly if you use the same Step name twice (":original" in this case). Instead of using :original you could also use any other valid Assembly Step name.

If you are using multiple file input fields, then you can tell Transloadit which field supplies the audio file and which supplies the image. Suppose you have two file input fields named the_image and the_audio. These Assembly Instructions will make it work:

"my_merge_step": {
  robot : "/video/merge",
  preset: "ipad-high",
  use   : {
    steps : [
      { name: ":original", fields: "the_audio", as: "audio" },
      { name: ":original", fields: "the_image", as: "image"}
    ]
  }
}

Merging an Audio File and a Video

If you have a video file (without sound for example) and an audio track that you want the video to use you can merge them together with Transloadit. Just label the video as video and the audio file as audio using the as key in the JSON.

Imagine you have two file input fields in the same upload form - one to upload a video file and one for an audio file. You can tell Transloadit which field supplies the video and which the audio file using the file input field's name attribute. Just use the value for the name attribute as the value for the fields key in the JSON:

"my_merge_step": {
  robot : "/video/merge",
  preset: "ipad-high",
  use   : {
    steps : [
      { name: ":original", fields: "the_video", as: "video" },
      { name: ":original", fields: "the_audio", as: "audio "}
    ]
  }
}

You can also supply the video and audio file using other Assembly Steps of course and leave out the fields attribute.

Important when merging audio and video files, it's recommended to set target a format & codecs via a preset or via ffmpeg.codec:v, ffmpeg.codec:a and ffmpeg.f. If not, merging will default to backwards compatible, but non-desirable legacy codecs.

Merging Several Images to Generate a Video

It is possible to create a video from images with Transloadit. Just label all images as image using the as key in the JSON:

"my_merge_step": {
  robot : "/video/merge",
  preset: "ipad-high",
  use   : {
    steps : [
      { name: ":original", as: "image" }
    ]
  },
  framerate: "1/10",
  duration: 8.5
}

This will work fine in a multi-file upload context. Files are sorted by their basename. So if you name them 01.jpeg and 02.jpeg, they will be merged in the correct order. Note You need to add leading zeros to your number sorted names, if you use plain numbers like 1.jpeg and 2.jpeg, it won't work.

You can also supply your images using other Assembly Steps of course, results from image/resize Steps for example.

Examples

3.4 Video Concatenation

Our /video/concat robot

The /video/concat robot concatenates several video files together.

Important: All videos that you concatenate must have the same dimensions (width and height), and the same streams (audio and video streams) otherwise you will run into errors! If your videos do not have the desired dimensions when passing them to the /video/concat robot, please encode them first into the proper dimensions with our /video/encode robot. If your one of your videos has no audio stream, but the other ones have one, then please first add a video/merge step where you add a silent audio stream to the ones that don't have an audio stream.

Parameters

Name Type Default Description

preset

String

"flash"

Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "flash" preset is not applied. This is to prevent you from having to override each of the flash preset's values manually. For a list of video presets, see video presets.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

It is possible to concatenate a virtually infinite number of video files using the /video/concat robot.

Imagine you have three file input fields in the same upload form for video files that you want to concatenate. You can tell Transloadit in which order it should concatenate them using the file input field's name attribute. Just use the value for the name attribute as the value for the fields key in the JSON. Then set the proper order values in the as parameter. Valid values here are video_[[index]]. Transloadit will then concatenate them in the order of the index ascending:

"my_concat_step": {
  robot : "/video/concat",
  preset: "ipad-high",
  use   : {
    steps : [
      { name: ":original", fields: "first_video_file", as: "video_1" },
      { name: ":original", fields: "second_video_file", as: "video_2" },
      { name: ":original", fields: "third_video_file", as: "video_3" },
    ]
  }
}

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.

ffmpeg_stack

String

"v2.2.3"

Selects the FFmpeg stack for the encoding. Valid values are at the moment: "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

Examples

3.5 Media Playlist Generation

Our /media/playlist robot

The /media/playlist robot is able to generate playlist files for HTTP Live Streaming (HLS).

This robot accepts HLS segments generated by the /audio/encode and /video/encode robots. You need to pass an /audio/encode or /video/encode Step that had its segment parameter set to true to the use parameter of this robot.

The segments need to be passed to the robot all at the same time, and not one by one. That's why you must use the bundle_steps parameter, otherwise you will generate multiple playlist files each containing only one segment.

Also, please make sure that you export your segments (to Amazon S3 for example). If you do not do that your playlist file will become invalid after 24 hours, as we remove temporary result files after that time.

Here is a complete example on how to implement HTTP Live Streaming (HLS) for video with Transloadit. It also works with the /audio/encode robot, though.

Generating a Master Playlist - a Playlist of Playlists

You can also pipe the output of several playlist Steps into another playlist Step to build a HLS playlist of playlists. The master playlist will make use of the resolution and bandwidth parameters of the parameter playlists. Here is an example:

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Step bundling
This robot allows you to bundle several Steps to be used as the input. In fact for this robot you should use Step bundling, otherwise you will create one playlist file for each passed segment. If you set bundle_steps to true, however, it will create one playlist containing all the segments you pass to it. To achieve this, pass an object like the one below to the use parameter:
use: { steps: "segment_step_name", "bundle_steps": true }

Please keep in mind, that all input Steps must actually be present in your Template. If one of them is missing, no playlist is generated, because the robot waits forever for all input Steps to be finished first.

Grouping segments into several playlists
You can also set group_by_original to true, in order to create a separate playlist based on the segments for each of your uploaded or imported files, instead of creating a playlist containing all segments of all uploaded and imported files.

Demo
See a demo for the use parameter here.

name

String

"playlist.m3u8"

The final name of the playlist file.

relative_to

String

""

URL prefixes to use in the playlist file. Example: "/234p/"

resolution

String

""

The resolution reported in the playlist file. Example: "416x234". More info.

codecs

String

""

The codecs reported in the playlist file. Example: "avc1.42001e,mp4a.40.34". More info.

bandwidth

"auto" or Number in bits per second

"auto"

The bandwidth reported in the playlist file. Example: 2560000. More info.

meta_name

String

""

The meta name as used for NAME in the #EXT-X-STREAM-INF path in playlists. Can be different from the (file)name.

protocol

String

"http"

The URL protocol used for all URLs in playlists. Can be "http" or "https".

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

Examples

3.6 Video Presets

These are supported if you were to specify ffmpeg_stack: "v1.0.0" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
android-high mp4 libfaac 128k 48k libx264 700k 480x320
android-low mp4 libfaac 64k 48k libx264 96k 480x320
android mp4 libfaac 128k 48k libx264 512k 480x320
flash flv libmp3lame 64k 44100 flv 512k 320x240
ipad-high mp4 libfaac 128k 48k libx264 1200k 1024x768
ipad-low mp4 libfaac 128k 48k libx264 512k 1024x768
ipad mp4 libfaac 128k 48k libx264 700k 1024x768
iphone-high mp4 libfaac 128k 48k libx264 700k 480x320
iphone-low mp4 libfaac 64k 48k libx264 96k 480x320
iphone mp4 libfaac 128k 48k libx264 512k 480x320
ogv ogg libvorbis 128k 48k libtheora 700k
webm webm libvorbis 128k 48k libvpx 700k
wmv asf wmav2 wmv2

These are supported if you were to specify ffmpeg_stack: "v2.0.0" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
android-high mp4 libvo_aacenc 128k 48k libx264 700k 480x320
android-low mp4 libvo_aacenc 64k 48k libx264 96k 480x320
android mp4 libvo_aacenc 128k 48k libx264 512k 480x320
flash flv libmp3lame 64k 44100 flv 512k 320x240
ipad-high mp4 libvo_aacenc 128k 48k libx264 1200k 1024x768
ipad-low mp4 libvo_aacenc 128k 48k libx264 512k 1024x768
ipad mp4 libvo_aacenc 128k 48k libx264 700k 1024x768
iphone-high mp4 libvo_aacenc 128k 48k libx264 700k 480x320
iphone-low mp4 libvo_aacenc 64k 48k libx264 96k 480x320
iphone mp4 libvo_aacenc 128k 48k libx264 512k 480x320
ogv ogg libvorbis 128k 48k libtheora 700k
webm webm libvorbis 128k 48k libvpx 700k
wmv asf wmav2 wmv2

These are supported if you were to specify ffmpeg_stack: "v2.1.0" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
android-high mp4 libfdk_aac 128000 44100 libx264 700k 480x320
android-low mp4 libfdk_aac 128000 44100 libx264 96k 480x320
android mp4 libfdk_aac 128000 44100 libx264 512k 480x320
flash flv libmp3lame 64k 44100 flv 512k 320x240
ipad-high mp4 libfdk_aac 128000 44100 libx264 1200k 1024x768
ipad-low mp4 libfdk_aac 128000 44100 libx264 512k 1024x768
ipad mp4 libfdk_aac 128000 44100 libx264 700k 1024x768
iphone-high mp4 libfdk_aac 128000 44100 libx264 700k 480x320
iphone-low mp4 libfdk_aac 128000 44100 libx264 96k 480x320
iphone mp4 libfdk_aac 128000 44100 libx264 512k 480x320
ogv ogg libvorbis 128k 48k libtheora 700k
webm webm libvorbis 128k 48k libvpx 700k
wmv asf wmav2 wmv2

These are supported if you were to specify ffmpeg_stack: "v2.2.3" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
android-high mp4 libfdk_aac 128000 44100 libx264 700000 480x320
android-low mp4 libfdk_aac 128000 44100 libx264 96000 480x320
android mp4 libfdk_aac 128000 44100 libx264 512000 480x320
flash flv libmp3lame 64000 44100 flv 512000 320x240
ipad-high mp4 libfdk_aac 128000 44100 libx264 1200000 1024x768
ipad-low mp4 libfdk_aac 128000 44100 libx264 512000 1024x768
ipad mp4 libfdk_aac 128000 44100 libx264 700000 1024x768
iphone-high mp4 libfdk_aac 128000 44100 libx264 700000 480x320
iphone-low mp4 libfdk_aac 128000 44100 libx264 96000 480x320
iphone mp4 libfdk_aac 128000 44100 libx264 512000 480x320
ogv ogg libvorbis 128000 48000 libtheora 700000
webm webm libvorbis 128000 48000 libvpx 700000
wmv asf wmav2 wmv2

You can use our presets as Templates, and override specific options if needed. In this example we adjust the iPhone preset for iPhone5 usage, which has a bigger screen (width, height), and we'll also set a higher video bitrate because of that (b: "1200K").

{
  steps: {
    my_iphone_step: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone",
      width: 1136,
      height: 640,
      ffmpeg: {
        b: "1200K"
      }
    }
  }
}

4. Audio Robots

4.1 Audio Encoding

Our /audio/encode robot

The /audio/encode robot converts a single audio file to a given format.

Parameters

Name Type Default Description

preset

String

"mp3"

Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "mp3" preset is not applied. This is to prevent you from having to override each of the mp3 preset's values manually. For a list of audio presets, see audio presets.

bitrate

Integer

Bit rate of the input audio file

Bit rate of the resulting audio file, in bits per second.

sample_rate

Integer

Sample rate of the input audio file

Sample rate of the resulting audio file, in Hertz.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.

ffmpeg_stack

String

"v1.0.0"

Selects the FFmpeg stack for the encoding. Valid values are "v1.0.0" , "v2.0.0", "v2.1.0" and "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

HTTP Live Streaming Parameters

Transloadit supports Apple's HTTP Live Streaming so that you can conform to the iOS app requirements for video.

Live segmentation can be hard to implement but when you use Transloadit you only have to enable the following options:

Name Type Default Description

segment

Boolean

false

Splits the file into multiple parts, to be used for Apple's HTTP Live Streaming. .

segment_duration

Integer

10

Specifies the length of each HTTP segment. This is optional, and the default value as recommended by Apple is 10. Do not change this value unless you have a good reason.

segment_prefix

String

basename of input

The prefix used for segment output files. For example, a prefix of "segment_" would produce files named "segment_0.ts", "segment_1.ts", and so on. This is optional, and defaults to the base name of the input file.

Please use our /media/playlist robot to generate master index files - a text file with the .m3u8 file extension, referencing all the different segments and their duration.

Examples

4.2 Audio Concatenation

Our /audio/concat robot

The /audio/concat robot concatenates several audio files together.

Parameters

Name Type Default Description

preset

String

"mp3"

Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "mp3" preset is not applied. This is to prevent you from having to override each of the mp3 preset's values manually. For a list of audio presets, see audio presets.

bitrate

Integer

Bit rate of the input audio file

Bit rate of the resulting audio file, in bits per second.

sample_rate

Integer

Sample rate of the input audio file

Sample rate of the resulting audio file, in Hertz.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

It is possible to concatenate a virtually infinite number of audio files using the /audio/concat robot.

Imagine you have three file input fields in the same upload form for audio files that you want to concatenate. You can tell Transloadit in which order it should concatenate them using the file input field's name attribute. Just use the value for the name attribute as the value for the fields key in the JSON. Then set the proper order in the as parameter. Valid values here are audio_[[index]]. Transloadit will then concatenate them in the order of the index ascending:

"my_concat_step": {
  robot : "/audio/concat",
  preset: "mp3",
  use   : {
    steps : [
      { name: ":original", fields: "first_audio_file", as: "audio_1" },
      { name: ":original", fields: "second_audio_file", as: "audio_2" },
      { name: ":original", fields: "third_audio_file", as: "audio_3" },
    ]
  }
}

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.

ffmpeg_stack

String

"v2.2.3"

Selects the FFmpeg stack for the encoding. Valid values are at the moment: "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

4.3 Audio Merging

Our /audio/merge robot

The /audio/merge robot overlays several audio files on top of each other. This is ideal for audio watermarking.

Parameters

Name Type Default Description

preset

String

"mp3"

Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "mp3" preset is not applied. This is to prevent you from having to override each of the mp3 preset's values manually. For a list of audio presets, see audio presets.

bitrate

Integer

Bit rate of the input audio file

Bit rate of the resulting audio file, in bits per second.

sample_rate

Integer

Sample rate of the input audio file

Sample rate of the resulting audio file, in Hertz.

duration

string

"longest"

Duration of the output file compared to the duration of all merged audio files. Can be "first" (duration of the first input file), "shortest" (duration of the shortest audio file) or "longest" for the duration of the longest input file.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

It is possible to merge a virtually infinite number of audio files using the /audio/merge robot.

Imagine you have three file input fields in the same upload form for audio files that you want to merge. You can tell Transloadit in which order it should concatenate them using the file input field's name attribute. Just use the value for the name attribute as the value for the fields key in the JSON and audio as the as parameter.:

"my_merge_step": {
  robot : "/audio/merge",
  preset: "mp3",
  use   : {
    steps : [
      { name: ":original", fields: "first_audio_file", as: "audio" },
      { name: ":original", fields: "second_audio_file", as: "audio" },
      { name: ":original", fields: "third_audio_file", as: "audio" },
    ]
  }
}

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.

ffmpeg_stack

String

"v2.2.3"

Selects the FFmpeg stack for the encoding. Valid values are at the moment: "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

4.4 Audio Looping

Our /audio/loop robot

The /audio/loop robot loops an input audio file until a target duration is reached.

Parameters

Name Type Default Description

preset

String

"mp3"

Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the robot's ffmpeg parameter and you have not specified a preset, then the default "mp3" preset is not applied. This is to prevent you from having to override each of the mp3 preset's values manually. For a list of audio presets, see audio presets.

bitrate

Integer

Bit rate of the input audio file

Bit rate of the resulting audio file, in bits per second.

sample_rate

Integer

Sample rate of the input audio file

Sample rate of the resulting audio file, in Hertz.

duration

Float

60.0

Target duration for the whole process in seconds. The robot will loop the input audio file for as long as this target duration is not reached yet.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

FFmpeg Parameters

Name Type Default Description

ffmpeg

Object

{}

A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.

ffmpeg_stack

String

"v2.2.3"

Selects the FFmpeg stack for the encoding. Valid values are at the moment: "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

Examples

4.5 Audio Waveform Images

Our /audio/waveform robot

The /audio/waveform robot generates a waveform image (in "png" format) from audio files. All types of audio files are supported. If you need the image in a different format, please pipe the result of this robot into the /image/resize robot.

Here is an example waveform image:

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

format

String

"image"

The format of the result file. Can be "image" or "json".

width

Integer

256

The width of the resulting image if the format "image" was selcted.

height

Integer

64

The height of the resulting image if the format "image" was selcted.

background_color

String

"00000000"

The background color of the resulting image in the "rrggbbaa" format (red, green, blue, alpha), if the format "image" was selected.

center_color

String

"000000ff"

The color used in the center of the gradient. The format is "rrggbbaa" (red, green, blue, alpha).

outer_color

String

"000000ff"

The color used in the outer parts of the gradient. The format is "rrggbbaa" (red, green, blue, alpha).

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

We recommend that you use an /audio/encode step prior to your waveform Step to convert audio files to mp3. This way it is guaranteed that the audio/waveform robot accepts your audio file and you can also down-sample large audio files and save some money.

Examples

4.6 Audio Artwork Extraction and Insertion

Our /audio/artwork robot

The /audio/artwork robot extracts and inserts the cover art from and into audio files. For extraction it uses the image format with which the cover was encoded into the audio file - most of the time this should be jpg. If you need the image in a different format, please pipe the result of this robot into the /image/resize robot. The "method" parameter chooses which functionality to use.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

method

String

"extract"

What should be done with the audio file. A value of "extract" means audio artwork will be extract. A value of "insert" means the provided image will be inserted as audio artwork. Please check the demo below.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

Examples

4.7 Audio Presets

These are supported if you were to specify ffmpeg_stack: "v1.0.0" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
aac mp4 libfaac 128000 44100
alac ipod alac 128000 44100
flac flac flac 128000 44100
mp3 mp3 libmp3lame 128000 44100
ogg ogg libvorbis
wav wav pcm_s16le

These are supported if you were to specify ffmpeg_stack: "v2.0.0" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
aac mp4 libvo_aacenc 128000 44100
alac ipod alac 128000 44100
flac flac flac 128000 44100
mp3 mp3 libmp3lame 128000 44100
ogg ogg libvorbis
wav wav pcm_s16le

These are supported if you were to specify ffmpeg_stack: "v2.1.0" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
aac mp4 libfdk_aac 128000 44100
alac ipod alac 128000 44100
flac flac flac 128000 44100
mp3 mp3 libmp3lame 128000 44100
ogg ogg libvorbis
wav wav pcm_s16le

These are supported if you were to specify ffmpeg_stack: "v2.2.3" in your Assembly Instructions. The recommended version is: v2.2.3

Name Format Audio codec Audio bitrate Audio frequency Video codec Video bitrate Video resolution
aac mp4 libfdk_aac 128000 44100
alac ipod alac 128000 44100
flac flac 128000 44100
mp3 mp3 libmp3lame 128000 44100
ogg ogg libvorbis
wav wav pcm_s16le

5. Image Robots

5.1 Image Manipulation and Resizing

Our /image/resize robot

The /image/resize robot resizes a single image file, such as for generating thumbnails. It can also change colors, apply image or text watermarks and much more.

Parameters

Name Type Default Description

width

1 - 5000

Width of the input image

Width of the new image, in pixels

height

1 - 5000

Height of the input image

Height of the new image, in pixels

strip

Boolean

false

Strips all metadata from the image. This is useful to keep thumbnails as small as possible.

flatten

Boolean

true

Flattens all layers onto the specified background to achieve better results from transparent formats to non-transparent formats, as explained in the ImageMagick documentation. Note To preserve animations, GIF files are not flattened when this is set to true. To flatten GIF animations, use the frame parameter.

correct_gamma

Boolean

false

Prevents gamma errors common in many image scaling algorithms.

quality

1 - 100

Quality of the input image, or 92

Controls the image compression for JPG and PNG images. Please also take a look at our /image/optimize robot. Before: Quality 40 applied:

background

String

"#FFFFFF"

Either the hexadecimal code or name of the color used to fill the background (only used for the pad resize strategy). Note By default, the background of transparent images is changed to white. For details about how to preserve transparency across all image types, see this demo.

resize_strategy

String

"fit"

See the list of available resize strategies.

zoom

Boolean

true

If this is set to false, smaller images will not be stretched to the desired width and height. For details about the impact of zooming for your preferred resize strategy, see the list of available resize strategies.

crop

Object or JSON encoded String in the format: { x1: Integer, y1: Integer, x2: Integer, y2: Integer }

null

Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original image(s). For example, {x1: 80, y1: 100, x2: 160, y2: 180} will crop the area from (80, 100) to (160, 180) which is a square whose width and height are 80px. If crop is set, the width and height parameters are ignored, and the resize_strategy is set to crop automatically. You can also use a valid JSON string of such an object with coordinates.

format

String

Format of the input image

Some of the most important available formats are "jpg", "png", "gif", "tiff" and "pdf". For a complete lists of all formats that we can write to please check our supported image formats list.

gravity

String

center

The direction from which the image is to be cropped. The available options are "center", "top", "bottom", "left", and "right". You can also combine options with a hyphen, such as "bottom-right".

frame

Integer

null (all frames)

Use this parameter when dealing with animated GIF files to specify which frame of the GIF is used for the operation. Specify 1 to use the first frame, 2 to use the second, and so on.

colorspace

String

""

Sets the image colorspace. For details about the available values, see the ImageMagick documentation. Please note that if you were using "RGB", we recommend using "sRGB" instead as of 2014-02-04. ImageMagick might try to find the most efficient colorspace based on the color of an image, and default to e.g. "Gray". To force colors, you might then have to use this parameter in combination with type "TrueColor"

type

String

""

Sets the image color type. For details about the available values, see the ImageMagick documentation. If you're using colorspace, ImageMagick might try to find the most efficient based on the color of an image, and default to e.g. "Gray". To force colors, you could e.g. set this parameter to "TrueColor"

sepia

Number

null

Sets the sepia tone in percent. Valid values range from 0 - 99. Before:

rotation

String / Boolean / Integer

true

Determines whether the image should be rotated. Set this to true to auto-rotate images that are rotated in a wrong way, or depend on EXIF rotation settings. You can also set this to an integer to specify the rotation in degrees. You can also specify "degrees" to rotate only when the image width exceeds the height (or "degrees" if the width must be less than the height). Specify false to disable auto-fixing of images that are rotated in a wrong way.

compress

String

null

Specifies pixel compression for when the image is written. Valid values are None, "BZip", "Fax", "Group4", "JPEG", "JPEG2000", "Lossless", "LZW", "RLE", and "Zip". Compression is disabled by default. Please also take a look at our /image/optimize robot.

blur

String

null

Specifies gaussian blur, using a value with the form {radius}x{sigma}. The radius value specifies the size of area the operator should look at when spreading pixels, and should typically be either "0" or at least two times the sigma value. The sigma value is an approximation of how many pixels the image is "spread"; think of it as the size of the brush used to blur the image. This number is a floating point value, enabling small values like "0.5" to be used.

progressive

Boolean

false

Interlaces the image if set to true, which makes the image load progressively in browsers. Instead of rendering the image from top to bottom, the browser will first show a low-res blurry version of the images which is then quickly replaced with the actual image as the data arrives. This greatly increases the user experience, but comes at a cost of a file size increase by around 10%.

transparent

String

""

Make this color transparent within the image.

trim_whitespace

Boolean

false

This determines if additional whitespace around the image should first be trimmed away. If you set this to true this parameter removes any edges that are exactly the same color as the corner pixels.

clip

Mixed

false

Apply the clipping path to other operations in the resize job, if one is present. If set to true, it will automatically take the first clipping path. If set to a string it finds a clipping path by that name.

negate

Boolean

false

Replace each pixel with its complementary color, effectively negating the image. Especially useful when testing clipping.

density

String

null

While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. That is the density (in pixels per inch) of an image and defines how far apart (or how big) the individual pixels are. It defines the size of the image in real world terms when displayed on devices or printed. You can set this value to a specific width or in the format widthxheight. If your converted image has a low resolution, please try using the density parameter to resolve that.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

Watermark Parameters

Example:


After:

Name Type Default Description

watermark_url

String

""

A URL indicating a PNG image to be overlaid above this image. Please note that you can also supply the watermark via another Assembly Step.

watermark_position

String / Array

"center"

The position at which the watermark is placed. The available options are "center", "top", "bottom", "left", and "right". You can also combine options, such as "bottom-right". An array of possible values can also be specified, in which case one value will be selected at random, such as [ "center", "left", "bottom-left", "bottom-right" ]. This setting puts the watermark in the specified corner. To use a specific pixel offset for the watermark, you will need to add the padding to the image itself.

watermark_position_x

Number

0

The x-offset in number of pixels at which the watermark will be placed in relation to the position it has due to watermark_position. Values can be both positive (moves the watermark to the right) and negative (moves it to the left) here.

watermark_position_y

Number

0

The y-offset in number of pixels at which the watermark will be placed in relation to the position it has due to watermark_position. Values can be both positive (moves the watermark to the bottom) and negative (moves it to the top) here.

watermark_size

String

""

The size of the watermark, as a percentage. For example, a value of "50%" means that size of the watermark will be 50% of the size of image on which it is placed.

watermark_resize_strategy

String

"fit"

Available values are "fit" and "stretch".

Supplying the Watermark via an Assembly Step

It is now possible to pass both the base image file and the watermark image to an Assembly Step via the use parameter, allowing you to either have both be part of the upload or to use results of other Assembly Steps as input to your /image/resize Step.

For this to work you just need to use the as-syntax:

"my_image_step": {
  robot : "/image/resize",
  use   : {
    steps : [
      { name: ":original", as: "base" },
      { name: "watermark_step", as: "watermark "}
    ]
  }
}

Here the output of a watermark_step step is used as the watermark whereas the base image is taken from the uploaded files.

If you use several file input fields, then you can tell Transloadit which field supplies the base image and which the watermark. Suppose you have two file input fields named the_image and the_watermark. These Assembly Instructions will make it work using the fields condition:

"my_image_step": {
  robot : "/image/resize",
  use   : {
    steps : [
      { name: ":original", fields: "the_image", as: "base" },
      { name: ":original", fields: "the_watermark", as: "watermark "}
    ]
  }
}

Please note that the robot's watermark_url parameter will still continue to work.

Text Parameters

The following text parameters are intended to be used as properties for your array of text overlays. Here is an example:

image_step: {
  use: ":original",
  robot: "/image/resize",
  text: [
    {
      text: "Example text",
      size: 12,
      valign: "top"
    },
    {
      text: "Another example text",
      size: 10,
      valign: "bottom"
    }
  ]
}
Name Type Default Description

text

Array

[]

An array of objects each containing text rules. See our list of available text parameters.

font

String

"Arial"

The font family to use. Also includes boldness and style of the font. Here is a list of all supported fonts.

size

Number

12

The text size in pixels.

rotate

Number

0

The rotation angle in degrees.

color

String

"#000000"

The text color. All hex colors in the form "#xxxxxx" are supported, where each x can be 0-9 or a-f. "transparent" is also supported if you want a transparent text color. In that case use "stroke" instead, otherwise your text will not be visible.

background_color

String

"transparent"

The text color. All hex colors in the form "#xxxxxx" are supported, where each x is can be 0-9 or a-f. "transparent" is also supported.

stroke_width

Number

0

The stroke's width in pixels.

stroke_color

String

"transparent"

The stroke's color. All hex colors in the form "#xxxxxx" are supported, where each x is can be 0-9 or a-f. "transparent" is also supported.

align

String

"center"

The horizontal text alignment. Can be "left", "center" and "right".

valign

String

"center"

The vertical text alignment. Can be "top", "center" and "bottom".

x_offset

Number

0

The horizontal offset for the text in pixels that is added (positive integer) or removed (negative) integer from the horizontal alignment.

y_offset

Number

0

The vertical offset for the text in pixels that is added (positive integer) or removed (negative) integer from the vertical alignment.

Example:


After:

Resize Strategies

The examples below show the following image resized to 100px × 100px for each available strategy:

straw apple

Strategy Description

fit

Uses the width and height as the maximum values for the resize, preserving aspect ratio.

So if you wanted to resize a 300x400 image into 100x100, the resulting image would be 75x100 pixels.

min_fit

Just like fit, but uses the width and height as the minimum values for the resize, preserving aspect ratio.

So if you wanted to resize a 300x400 image into 100x100, the resulting image would be 100x133 pixels.

Note This strategy is not yet available for video robots.

stretch

Ignores aspect ratio, resizing the image to the exact width and height specified. This may result in a stretched or distorted image.

pad

Scales the image to fit, and then fills the remaining width and height with the specified background color (which here is "#aa0000"). If you use zoom: false with this strategy, smaller images will be centered horizontally and vertically, and have the background pad around them.

crop

Centers the image within the specified crop frame, discarding any overlapping parts. If the source image is smaller than the crop frame, it will be zoomed.

If crop coordinates are specified for the crop parameter, the image area specified by the coordinates is cut from the original, and no centering is performed.

Use the gravity parameter to change how the image is cropped.

fillcrop

Given a rectangle of the specified width and height, the image will be resized such that the rectangle fits completely inside the resulting image, with one of the image dimensions the same as that of the provided rectangle. Scaling is performed using the larger scale value; in other words, the larger of dw/w and dh/h is used to scale both dimensions. This means that the dimension of the provided rectangle closest to the actual dimension will be resized to match the rectangle dimension.

The resulting image is then cropped and horizontally/vertically centered to fill the rectangle, removing any overlaying parts.

Use gravity parameter to change how the image is cropped.

Note This strategy is not yet available for video robots.

Examples

5.2 Image Optimization With the /image/optimize Bot

Our /image/optimize robot

Reduce the file size of your JPEG, PNG, GIF and SVG images by up to 80% for big images and 65% for small to medium sized ones - while keeping their original quality!

This robot enables you to lower your storage and bandwidth costs, and improves your user experience and monetization by reducing the load time of image-intensive web pages.

It works well together with the /image/resize robot to bring the full power of resized and optimized images to your website or app.

Important: This robot accepts all image types and will just pass on unsupported image types unoptimized. Hence, there is no need to set up complicated /file/filter workflows for this.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

progressive

Boolean

false

Interlaces the image if set to true, which makes the result image load progressively in browsers. Instead of rendering the image from top to bottom, the browser will first show a low-res blurry version of the image which is then quickly replaced with the actual image as the data arrives. This greatly increases the user experience, but comes at a loss of about 10% of the file size reduction.

preserve_meta_data

Boolean

true

Specifies if the image's meta data should be preserved during the optimization, or not. If it is not preserved, the file size is even further reduced. This option is mandatory if you set png_tool to "pngquant"

fix_breaking_images

Boolean

true

If set to true this parameter tries to fix images that would otherwise make the underlying tool error out and thereby break your assemblies. This can sometimes result in a larger file size, though.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

Examples

5.3 Face Detection With the /image/facedetect Bot

Our /image/facedetect robot

This robot enables you to detect and extract human faces from your images. You can also specify a padding around the extracted faces.

It works well together with the /image/resize robot to bring the full power of resized and optimized images to your website or app.

Important: This robot accepts all image types. By giving the format parameter the value "preserve" the result face images will have the same image format (jpg, png, etc.).

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

crop

Boolean

false

Determine if the detected faces should be extracted. If this option is set to false, then the robot returns the input image again, but with the coordinates of all detected faces attached to file.meta.faces in the result JSON. If this parameter is set to true, the robot will output all detected faces as images.

crop_padding

String

5px

Specifies how much padding is added to the extracted face images if crop is set to true. Values can be in px (pixels) or % (percentage of the width and height of the particular face image).

format

String

preserve

Determines the output format of the extracted face images if crop is set to true. The default value "preserve" means that the input image format is re-used. Valid values are "jpg", "png", "tiff" and "preserve".

Examples

5.4 Taking Screenshots of Websites or Uploaded HTML Files

Our /html/convert robot

Converts the input HTML to an image of the rendered page. A URL can be provided instead of an input HTML file, to capture a screenshot from the website referenced by the URL.

Use the /image/resize robot to resize or crop the screenshot as needed.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

url

String

The URL of the web page to be converted.

format

String

"png"

The format of the resulting image. The supported values are "jpg", "jpeg" and "png".

width

Number

1024

The width of the resulting image containing the full web page. Change this to change the dimensions of the result image. The height will be calculated dynamically depending on the length of the web page.

height

Number

Height of the web page

The screen height that will be used. By default this equals the length of the web page.

delay

Number

2000

The delay (in milliseconds) applied to allow the page and all of its JavaScript to render before taking the screenshot.

Note A validation error will occur if neither an HTML file is uploaded nor an URL parameter is given.

Examples


6. Assembly Flow Logic Robots

Our /file/filter robot

6.1 File Filtering With the /file/filter Bot

This robot is responsible for filtering uploaded, imported or converted files.

Think of this robot as your if/else checks to construct advanced file conversion workflows and to not convert certain files that your users uploaded depending on their meta data.

The accepts and declines parameters can each be set to an array with three members:

  • A value or job variable, such as ${file.mime}
  • One of the following operators: =, <, >, <=, >=, !=, regex, !regex
  • A value or job variable, such as 50 or "foo"

Examples:

  • ['${file.meta.width}', '>', '${file.meta.height}']
  • ['${file.size}', '<=', '720']
  • ['720', '>=', '${file.size}']
  • ['${file.mime}', 'regex', 'image']

The following lists the supported job variables.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

accepts

Array

[]

Files that match at least one requirement will be accepted, or declined otherwise. Example:
[['${file.mime}', '=', 'image/gif']].
If the condition_type parameter is set to "and ", then all requirements must match for the file to be accepted.

declines

Array

[]

Files that match at least one requirement will be declined, or accepted otherwise. Example:
[['${file.size}','>','1024']].
If the condition_type parameter is set to "and ", then all requirements must match for the file to be declined.

condition_type

String

"or"

Specifies the condition type according to which the members of the accepts or declines arrays should be evaluated. Can be "or" or "and".

error_on_decline

Boolean

false

If this is set to true and one or more files are declined, the Assembly will be stopped and marked with an error.

error_msg

String

"One of your files was declined"

This is the error message shown to your users (such as by the jQuery SDK) when a file is declined and error_on_decline is set to true.

Available Job Variables

Note Conditions on properties that a file does not have will be ignored. For example, an image does not have ${file.meta.bitrate}. Also, note that since ${file.width} will be ignored, use ${file.meta.width} instead.

Variable Description

${account_id}

The ID of your Transloadit account.

${assembly.id}

The ID of the Assembly representing the current upload.

${unique_prefix}

A unique 33-character prefix used to avoid file name collisions, such as "f2/d3eeeb67479f11f8b091b04f6181ad"

${previous_step.name}

The name of the previous Step that produced the file currently uploaded by the S3 store robot.

${file.name}

The name of the stored file.

${file.url_name}

The name of the stored file, from which any characters other than A-Za-z0-9-_. are stripped, and with dashes instead of spaces.

${file.*}

Any file property available in the final results array, such as ${file.meta.width}. For details, see the metadata documentation.

Available Operators for the Conditions

Operator Description Example

=

equals

['${file.ext}', '=', 'jpg']

<

less than

['${file.size}', '<', '1024']

>

greater than

['${file.meta.widtd}', '>', '${file.meta.height}']

<=

less or equal

['${file.meta.audio_bitrate}', '<=', '256000']

>=

greater or equal

['${file.meta.audio_samplerate}', '>=', '44100']

!=

not equal to

['${file.ext}', '!=', 'jpg']

regex

regex match, case-insensitive per default

['${file.mime}', 'regex', 'image']

!regex

regex mismatch, case-insensitive per default

['${file.mime}', '!regex', 'image']

Examples

Our /file/virusscan robot

6.2 Antivirus Through the /file/virusscan Bot

While 100% security is a myth, having /file/virusscan as a gatekeeper bot helps reject millions of trojans, viruses, malware & other malicious threats before they reach your platform.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

error_on_decline

Boolean

false

If this is set to true and one or more files are declined, the Assembly will be stopped and marked with an error.

error_msg

String

"One of your files was declined"

This is the error message shown to your users (such as by the jQuery SDK) when a file is declined and error_on_decline is set to true.

Examples

7. File Export Robots

Our /s3/store robot

7.1 Export to Amazon S3 With the /s3/store Bot

Exports the input file into an Amazon S3 bucket. If you are new to Amazon S3, see our tutorial on using your own S3 bucket.

The URL to the result file in your S3 bucket will be returned in the Transloadit result JSON.

Important Our result URLs use the form http://{bucket}.s3.amazonaws.com/path/to/file, which means that your bucket name must be DNS-compliant. This includes that you do not use uppercase letters in your bucket name. For more information regarding this please see Amazon's recommendations. Please note that any non alphanumeric characters in the file names will be replaced with an underscore, and spaces are replaced with dashes. If your existing S3 bucket contains uppercase letters or is otherwise not DNS-compliant, please make sure to rewrite the result URLs using the robot's url_prefix parameter.

You will also need to add some permissions to your bucket so that Transloadit can access it properly. Here is an example IAM policy that you can use. It contains the minimum required permissions to export a file to your S3 bucket using Transloadit. You may require more permissions (especially viewing permissions) depending on your application.

Please change BUCKET_NAME and the values for Sid and Resource accordingly. Also, this policy will grant the minimum required permissions to all your users. We advise you to create a separate Amazon IAM user, and use its User ARN (can be found in the "Summary" tab of a user here) for the Principal value. More information about this can be found here.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowTransloaditToStoreFilesIn${BUCKET_NAME}Bucket",
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketLocation",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::${BUCKET_NAME}",
                "arn:aws:s3:::${BUCKET_NAME}/*"
            ]
        }
    ]
}

The Sid value is just an identifier for you to recognize the rule later. You can name it anything you like.

The policy needs to be separated into two parts, because the ListBucket action requires permissions on the bucket while the other actions require permissions on the objects in the bucket. When targeting the objects there's a trailing slash and an asterisk in the Resource parameter, whereas when the policy targets the bucket, the slash and the asterisk are omitted.

Please note that if you give the robot's acl parameter a value of "bucket-default", then you do not need the "s3:PutObjectAcl" permission in your bucket policy.

Since you can have S3 buckets in different regions, we sometimes have to figure out which endpoint to talk to. Allowing GetBucketLocation helps speed up that process. Otherwise we try many different regions following an algorithm for likely-hood, but that's obviously inefficient and causes slower Assemblies.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

bucket

(required) String

The name of the bucket to which the file is exported.

key

(required) String

Your Amazon access key ID

secret

(required) String

Your Amazon secret access Key

bucket_region

String

"us-east-1"

The AWS region that your S3 bucket is in. If not provided, Transloadit will figure that out for you at some speed cost.

path

String

"${unique_prefix}/${file.url_name}"

The path at which the file is to be stored. This may include any available Assembly variables.

url_prefix

String

"http://{bucket}.s3.amazonaws.com/"

The URL prefix used for the returned URL, such as "http://my.cdn.com/some/path".

acl

String

"public-read"

The permissions used for this file. This can be "public-read", "public", "private" or "bucket-default".

headers

String

{ "Content-Type": file.mime }

A JavaScript object containing a list of headers to be set for this file on S3, such as { FileURL: "${file.url_name}" }. This can also include any available Assembly variables. Here you can find a list of available headers.

host

String

"s3.amazonaws.com"

The host of the storage service used. This only needs to be set when the storage service used is not Amazon S3, but has a compatible API (such as hosteurope.de).

no_vhost

Boolean

false

Set to true if you use a custom host and run into access denied errors.

sign_urls_for

Boolean or Number

false

If set to a number this parameter provides signed urls in the result JSON (in the signed_url and signed_ssl_url properties). The number that you set this parameter to is the url expiry time in seconds. If set to false no url signing is done.

Examples

7.2 Export to Your SFTP Server With the /sftp/store Bot

Our /sftp/store robot

Exports the input file to the specified server, via SFTP.

This robot uses SSH keys, which is secure, but a little complicated to setup. If you prefer a less secure, but easier-to-setup solution, then please have a look at our /ftp/store robot.

Note The URLs in the result JSON already point to the file on your server, so you can just save that URL in your database. You can influence the URL using the robot's url_template parameter which is explained in the table below.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

user

(required) String

The username for the SFTP connection.

host

(required) String

The host with which to establish the SFTP connection.

path

String

"${unique_prefix}/${file.url_name}"

The path at which the file is to be stored. This may include any available Assembly variables.

url_template

String

"http://host/path"

The URL of the file in the result JSON. This may include any of the following supported Assembly variables.

ssl_url_template

String

"https://{HOST}/{PATH}"

The SSL URL of the file in the result JSON. The following Assembly variables are supported.

port

Integer

22

The port to be used for the SFTP connection.

file_chmod

null

"755"

This optional paramater controls how an uploaded file's permission bits are set. You can use any string format that the chmod command would accept. If you don't specify this option, no changing is of the file's permission bits is done at all, meaning it's up to your server's configuration (e.g. umask).

Things to Keep in Mind

  • Your server might be unresponsive from time to time, this happens and is OK. As a result, if this robot fails to store one of your files, it retries to store the file 5 times over 15 minutes.
  • This also means that when you gave it the wrong credentials (when testing for example) Assemblies can take up to 15min to complete. Please keep this in mind.
  • If an Assembly has an export Step and takes long to execute, it is almost always due to the export Step having wrong credentials or the server being unreachable.

Installation on Your Server

The method explained here is slightly more elaborate than handing out an SSH account with an authorized public key, but is more secure, as the user will not be able to traverse outside their home directory. This way, even if the user account is compromised at some point, the accessible data would be recently uploaded files.

The following explains how to create a dedicated user and group for Transloadit, and restrict access as shown in this article.

First let's create a dedicated group & user:

# Change these variables to suit your needs.
# For additional security, use a randomly picked username.
TL_USER="random873"
TL_PUBLIC_PATH="uploads"

groupadd sftponly
useradd -g sftponly -m ${TL_USER}

# This line sets a random 20-character password for the user.
# We work with keys, but this is required because some operating systems will
# consider the account locked without one.
echo "${TL_USER}:$(cat /dev/urandom | tr -dc _A-Z-a-z-0-9 | head -c20)" |chpasswd

mkdir -p /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}

echo "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA57GdwNLqsWz03X8MBEe4KoMSY2HOURjnUUe9zeTivASI+BLEe3cZcuJjsEBaRpISvCH04hosWUI0H4BQeB1dZZUUW1s4ttnVohCD9CfNiXJ7pwJAvgWb01dTW4YUWFKUTpTeUwQzgcNVLDtSVaQOYh4lAKvCZEcz17X9iZ7AeSEuQKe+QsrcwQoBdSpQ6FnzKwSZsggK81dPiGIW9Cw2z/EZWJpl9QBTYhw25NbNRtZj3fXVbrejnQQ985eZ6TlrvQFpUVwyk0QNHDsN+7zVISM3eXNpxof+vJyQNDLN9tb8vNPf/HXuw7MDJWMphrQevF5V26aMzszl3ZeO1779Mw== sftp@transloadit.com" >> /home/${TL_USER}/.ssh/authorized_keys

chown -R ${TL_USER}.sftponly /home/${TL_USER}
chown root.root /home/${TL_USER}

chmod -R 600 /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
chmod -R u+X /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}

Make sure to change ${TL_USER} and ${TL_PUBLIC_PATH} to suit your needs. Remember to use a random username for additional security.

Next, we will set up SSH to cage SFTP users in their home directory, and deny them regular shell access.

Enter ${EDITOR} /etc/ssh/sshd_config, and then find and comment out this line:

# Subsystem sftp /usr/lib/openssh/sftp-server

At the bottom of the same file, add the following:

Subsystem sftp internal-sftp

Match group sftponly
    ChrootDirectory /home/%u
    X11Forwarding no
    AllowTcpForwarding no
    ForceCommand internal-sftp

Finally, enter /etc/init.d/ssh restart to reflect the changes made.

Examples

7.3 Export to Your FTP Server With the /ftp/export Robot

Our /ftp/store robot

Exports the input file to the specified server, via FTP.

We advise you to use our /sftp/store robot when possible, as it is much more secure. The /ftp/store robot should only serve as a fallback for when SFTP cannot be used.

Note The URLs in the result JSON already point to the file on your server, so you can just save that URL in your database. You can influence the URL using the robot's url_template parameter which is explained in the table below.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

user

(required) String

The username for the FTP connection.

password

(required) String

The password for the FTP connection.

host

(required) String

The host to which the FTP connection is established.

path

String

"${unique_prefix}/${file.url_name}"

The path at which the file is to be stored. This can contain any available Assembly variables. Please note that you might need to include your homedir at the beginning of the path.

url_template

String

"http://{HOST}/{PATH}"

The URL of the file in the result JSON. The following Assembly variables are supported.

ssl_url_template

String

"https://{HOST}/{PATH}"

The SSL URL of the file in the result JSON. The following Assembly variables are supported.

Things to Keep in Mind

  • Your server might be unresponsive from time to time, this happens and is OK. As a result, if this robot fails to store one of your files, it retries to store the file 5 times over 15 minutes.
  • This also means that when you gave it the wrong credentials (when testing for example) Assemblies can take up to 15min to complete. Please keep this in mind.
  • If an Assembly has an export Step and takes long to execute, it is almost always due to the export Step having wrong credentials or the server being unreachable.

Examples

7.4 Export to Rackspace Cloudfiles

Our /cloudfiles/store robot

The /cloudfiles/store robot exports the input file into a Rackspace Cloud Files container.

Note The URLs in the result JSON already point to the file in your Cloudfiles container, so you can just save that URL in your database. You can influence the URL using the robot's path parameter which is explained in the table below.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

container

(required) String

The name of the container to which to export the file. Please only use the top level container name. If your container name contains a slash ("/"), then you are setting the wrong name here. Please use the path parameter for "folders" that are within your container.

user

(required) String

Your Rackspace API user name.

key

(required) String

Your secret Rackspace Cloudfiles API key. This is not your Rackspace account password. It is the API key.

account_type

(required) String

"us"

The type of your account, which can be "us" or "uk". For details, see the Rackspace documentation.

data_center

(required) String

"dfw"

The data center to use for your account. This is ignored for "uk" account types. Can be "dfw" for Dallas, "ord" for Chicago or "syd" for Sydney.

path

String

"${file.id}_${file.url_name}"

The path at which to store the file. This value can also contain Assembly variables.

A Note About URLs

If your container is CDN-enabled, the resulting file.url indicates the path to the file in your CDN container, or is null otherwise.

The storage container URL for this file is always available via file.meta.storage_url.

7.5 Export to YouTube With the /youtube/store Bot

Our /youtube/store robot

Uploads videos to YouTube. Note that this robot only accepts videos.

Installation

Note You need to know the username of your registered YouTube account. Since YouTube usernames are added after signup, make sure that a username is assigned to your account, to prevent robot errors.

You will also need to enable two-step verification, and generate an application-level password, as explained here.

Finally, we've seen issues in cases where customers had two YouTube accounts connected to a single Google account, something to watch out for.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

username

(required) String

""

The username of your YouTube account.

password

(required) String

""

The application-level password generated for your YouTube account. Note that this is not the password used to log in to the YouTube account. For details about how to generate an application-level password, see this documentation.

title

(required) String

""

The title of the video to be displayed on YouTube. Note that since the YouTube API requires titles to be within 80 characters, longer titles may be truncated.

description

(required) String

""

The description of the video to be displayed on YouTube.

category

(required) String

""

The category to which this video will be assigned, from one of the available categories.

keywords

(required) String

""

Tags used to describe the video, separated by commas. These tags will also be displayed on YouTube.

visibility

String

""

Defines the visibility of the uploaded video. This can be "public", "private", or "unlisted".

Note To change the title, description, category, or keywords per video we recommend to inject variables into your Template.

7.6 Export to Microsoft Azure

Our /azure/store robot

The /azure/store robot exports the input file into a Microsoft Azure storage container.

Note The URLs in the result JSON already point to the file in your Azure container, so you can just save that URL in your database. You can influence the URL using the robot's path parameter which is explained in the table below.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

account

(required) String

Your Microsoft Azure storage account name.

key

(required) String

Your Microsoft Azure primary or secondary access key.

container

(required) String

The name of the container to which the file is exported.

path

String

"${unique_prefix}/${file.url_name}"

The path at which the file is to be stored. This may include any available Assembly variables.

content_type

String

""

The content type with which to store the file. By default this will be guessed by Azure.

content_encoding

String

""

The content encoding with which to store the file. By default this will be guessed by Azure.

content_language

String

""

The content language with which to store the file. By default this will be guessed by Azure.

cache_control

String

""

The cache control header with which to store the file.

metadata

String

{}

A JavaScript object containing a list of metadata to be set for this file on Azure, such as { FileURL: "${file.url_name}" }. This can also include any available Assembly variables.

sas_expires_in

Number

null

Set this to a number to enable shared access signatures for your stored object. This reflects the number of seconds that the signature will be valid for once the object is stored. Enabling this will attach the shared access signature (SAS) to the result URL of your object.

sas_permissions

String

""

Set this to a combination of r (read), w (write) and d (delete) for your shared access signatures (SAS) permissions.

7.7 Export to Softlayer / IBM Cloud

Our /softlayer/store robot

The /softlayer/store robot exports the input file into a Softlayer object storage container.

Note There are no URLs in the result JSON for this robot. You will need to download files from the storage via the Softlayer API.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

user

(required) String

Your Softlayer user name.

key

(required) String

Your Softlayer API key.

auth_endpoint

(required) String

Your Softlayer auth endpoint URL.

container

(required) String

The name of the container to which the file is exported.

path

String

"${unique_prefix}/${file.url_name}"

The path at which the file is to be stored. This may include any available Assembly variables.

headers

String

{}

A JavaScript object containing a list of headers to be set for this file on S3, such as { FileURL: "${file.url_name}" }. This can also include any available Assembly variables.


8. Other Robots

Our /document/thumbs robot

8.1 Extracting Images From Documents

The /document/thumbs robot extracts one or more thumbnails from a document.

Note This robot currently only supports the conversion of PDF files. We will add support for other document formats later.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

page

Integer or null

null

The PDF's page that you want to convert to an image. By default the value is null which means that all pages will be converted into images.

format

String

"png"

The format of the extracted image(s). Supported values are "jpeg", "jpg", "gif" and "png". If you specify the value "gif" then an animated gif cycling through all pages is created. Please check out this demo to learn more about this.

delay

Integer or null

null

If your output format is "gif" then this parameter sets the number of 100th seconds to pass before the next frame is shown in the animation. Set this to 100 for example to allow 1 second to pass between the frames of the animated gif. If your output format is not "gif", then this parameter does not have any effect.

width

Integer

Width of the input document

The width of the result image, in pixels.

height

Integer

Height of the input document

The height of the result image, in pixels.

resize_strategy

String

"pad"

One of the available resize strategies.

background

String

"#FFFFFF"

Either the hexadecimal code or name of the color used to fill the background (only used for the pad resize strategy). Note by default, the background of transparent images is changed to white. For details about how to preserve transparency across all image types, see this demo.

density

String

null

While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. That is the density (in pixels per inch) of an image and defines how far apart (or how big) the individual pixels are. It defines the size of the image in real world terms when displayed on devices or printed. You can set this value to a specific width or in the format widthxheight. If your converted image has a low resolution, please try using the density parameter to resolve that.

trim_whitespace

Boolean

true

This determines if additional whitespace around the PDF should first be trimmed away before it is converted to an image. If you set this to true only the real PDF page contents will be shown in the image. If you need to reflect the PDF's dimensions in your image, it is generally a good idea to set this to false.

pdf_use_cropbox

Boolean

true

Some PDF documents lie about their dimensions. For instance they'll say they are landscape, but when opened in decent Desktop readers, it's really in portrait mode. This can happen if the document has a cropbox defined. When this option is enabled (by default), the cropbox is leading in determining the dimensions of the resulting thumbnails.

force_accept

Boolean

false

Robots may accept only certain file types - all other possible input files are ignored. This means the /video/encode robot for example will never touch an image while the /image/resize robot will never look at a video. With the force_accept parameter you can force a robot to accept all files thrown at him, regardless if it would normally accept them.

Things to Keep in Mind

  • If you convert a multi-page PDF file into several images, all result images will be sorted with the first image being the thumbnail of the first document page, etc.
  • You can also check the meta.thumb_index key of each result image to find out which page it corresponds to. Keep in mind that these thumb indices start at 0 and not at 1!

Examples

8.2 Metadata Writing

Our /meta/write robot

The /meta/write robot can write meta into images, videos audio and files.

This robot for now only accepts images, videos and audio files.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

data_to_write

Object

{}

A key/value map defining the meta data to write into the file.

ffmpeg_stack

String

"v1.0.0"

Selects the FFmpeg stack for the encoding. Valid values are "v1.0.0" , "v2.0.0", "v2.1.0" and "v2.2.3". These versions do not reflect any real FFmpeg versions, they reflect our own internal semantic versioning for our custom FFmpeg builds.

Examples

8.3 File Compression / Zipping

Our /file/compress robot

The /file/compress robot creates a zip or tar archive for the result files that you provide it with.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Step bundling
This robot allows you to bundle several Steps to be used as the input. The robot would normally create one zip file for each Step you pass to it. If you set bundle_steps to true, however, it will create one archive containing all the result files from all Steps you pass to it. To achieve this, pass an object like the one below to the use parameter:
use: { steps: [ ":original", "encode2", "resizing3" ], bundle_steps: true }

Demo
See a demo for the use parameter here.

format

String

"tar"

The format of the archive to be created. Supported values are "tar" and "zip". Note that "tar" without setting gzip to true results in an archive that's not compressed in any way.

gzip

Boolean

false

Determines if the result archive should also be gzipped. Gzip compression is only applied if you use the "tar" format.

compression_level

Number

-6

Determines how fiercly to try to compress the archive. -0 is compressionless, which is suitable for media that is already compressed. -1 is fastest with lowest compression. -9 is slowest with the highest compression. If you are using -0 in combination with the tar format with gzip enabled, consider setting gzip to false instead. This results in a plain tar archive, meaning it aleady has no compression.

file_layout

String

"advanced"

Determines if the result archive should contain all files in one directory (value for this is "simple") or in subfolders according to the explanation below (value for this is "advanced"). Files with same names are numbered in the "simple" file layout to avoid naming collisions.

Archive structure for the "advanced" file layout.

There are a few things that we kept in mind when designing the "advanced" archive structure:

  1. There could be naming collisions.
  2. You want to know which Step a result file belongs to.
  3. You want to know from which originally uploaded file a result file was generated.
  4. ideally you want subfolders for a better structure of files.

To achieve all this, we have created the following archive file structure.

  1. There is a subfolder for each Step name that has result files in the archive.
  2. Files are named according to [first_2_letters_of_unique_original_prefix]_[first_2_letters_of_unique_prefix]_[original_file_name]. If you do not know what the original prefixes are, please check our available Assembly variables and look for ${unique_original_prefix} and ${unique_prefix}.
  3. Files that belong to the :original Step (originally uploaded files) do not include the first two letters of the unique_original_prefix.
  4. If you are dealing with thumbnails from the /video/thumbs robot, there is an additional digit representing the order in the file name.

Here is an example:

:original
  gh_a.mov          // "gh" are the first 2 letters of the unique prefix.
                    // "a.mov" was the file name of the uploaded file.
  ff_b.mov
thumbs
  gh_e8_thumb_1.jpg // "gh" is the unique original prefix, meaning it's a result of a.mov.
                    // "e8" is the file's unique prefix.
                    // The "1" shows the thumbnail order.
  gh_cv_thumb_2.jpg
  ff_9b_thumb_3.jpg
resize
  gh_ll_thumb.jpg
  gh_df_thumb.jpg
  ff_jk_thumb.jpg   // is a child of b.mov, as it starts with "ff"

Examples

8.4 File Decompression

Our /file/decompress robot

The /file/decompress robot reads, decompresses and extracts all files from an archive file. The following archive formats are supported:

  • ZIP archives (with uncompressed or "deflate"-compressed entries)
  • 7-Zip archives
  • RAR archives
  • GNU tar format (including GNU long filenames, long link names, and sparse files)
  • Solaris 9 extended tar format (including ACLs)
  • Old V7 tar archives
  • POSIX ustar
  • POSIX pax interchange format
  • POSIX octet-oriented cpio
  • SVR4 ASCII cpio
  • POSIX octet-oriented cpio
  • Binary cpio (big-endian or little-endian)
  • ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions)
  • GNU and BSD "ar" archives
  • "mtree" format
  • Microsoft CAB format
  • LHA and LZH archives
  • XAR archives

This robot also detects and handles any of the following before evaluating the archive file:

  • uuencoded files
  • Files with RPM wrapper
  • gzip compression
  • bzip2 compression
  • compress/LZW compression
  • lzma, lzip, and xz compression

For security reasons, archives that contain symlinks to outside the archived dir, will error out the Assembly. Decompressing password-protected archives (encrypted archives) is currently not fully supported but will not cause an Assembly to fail.

Parameters

Name Type Default Description

use

(required) String or Array

The previous step

General
Specifies which step(s) to use as the input to this robot. The default is to use the previous Step defined above the current one.

Special Step names
A special Step name is ":original", which "uses" the originally uploaded files.

Passing several Steps as input
You can also add arrays here to use several steps:
use: [ ":original", "encode2", "resizing3" ]

Demo
See a demo for the use parameter here.

ignore_errors

(required) Boolean

false

There might be an error coming up when trying to extract meta data from the files inside your archive. This happens for files that are zero bytes big for example. Setting this to true will cause the robot to not stop the file decompression (and the entire Assembly) when that happens.

Examples