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

1.1 Handle uploads

The /upload/handle Robot receives uploads that your users throw at you from browser or apps, or that you throw at us programatically.

Transloadit will handle file uploads for you wether you specify this Robot or not, so using it is optional.

It can still be good to define this Robot to make your Assembly Instructions explicit though, and to configure how exactly uploads should be handled. For example, what meta data we should extract for uploaded files?

There are three constraints when using this Robot, you must:

• not define a use parameter, contrary to all other Robots
• only use it once in a single set of Assembly Instructions
• name the Step that it's used in: :original

For example:

assembly.steps = {
  ':original': {
    robot: '/upload/handle',
    output_meta: {
      has_transparency: true,
    },
  },
  exported: {
    robot: '/s3/store',
    use: ':original',
    credentials: 'YOUR_S3_CREDENTIALS',
  },
}

Parameters

Examples featuring the /upload/handle Robot

• Specify multiple encoding Steps for a single file
• Automatically process multiple file types

2 File Importing

2.1 Import files from Dropbox

The /dropbox/import Robot imports whole directories of files from your Dropbox.

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

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /dropbox/import Robot

2.2 Import files from FTP servers

The /ftp/import Robot imports whole libraries of files from your FTP servers into Transloadit. No public key authentication is required. This Robot relies on password access.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Things to Keep in Mind

• Your server might be unresponsive from time to time. Since (S)FTP servers are harder to scale, we have seen this happen a lot. 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.

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

Examples featuring the /ftp/import Robot

• Copy many files from FTP into an Amazon S3 bucket
• Import files from an FTP server

2.3 Import files from webservers

The /http/import Robot imports any file that is publicly available via a web URL into Transloadit.

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

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /http/import Robot

• Concatenate two audio files
• Add watermark to a song
• Insert cover art into an audio file
• Import files over HTTP
• Concatenate video files
• Generate a video from an image sequence
• Merge an audio and a video file
• Merge an audio file and an image to generate a video

2.4 Import files from Amazon S3

The /s3/import Robot imports whole directories of files from your S3 bucket.

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

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /s3/import Robot

• Import a specific file from S3
• Import an entire folder of files from S3
• Resize all images in an S3 bucket

2.5 Import files from SFTP servers

The /sftp/import Robot imports whole libraries of files from your SFTP servers into Transloadit. This Robot relies on public key authentication.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Things to Keep in Mind

• Your server might be unresponsive from time to time. Since (S)FTP servers are harder to scale, we have seen this happen a lot. 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.

This robot uses SSH keys, which is more secure at the trade-off of a bit of complexity in setting up. If you prefer a less secure, but easier-to-setup solution, then please have a look at our /ftp/store and /ftp/import Robots.

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 featuring the /sftp/import Robot

• Import an entire folder of files from an SFTP Server

3 Video Encoding

3.1 Convert videos to HLS and MPEG-Dash

The /video/adaptive Robot encodes videos into HTTP Live Streaming (HLS) and MPEG-Dash supported formats and generates the necessary manifest and playlist files.

The /video/adaptive Robot generates the necessary manifest and playlist files based on a set of used video and audio files to make implementing HTTP Live Streaming (HLS) and MPEG-Dash streaming easy.

This Robot accepts all types of video files and audio files. Do not forget to use Step bundling in your use parameter to make the Robot work on several input files at once.

We have implemented video and audio encoding presets specifically for MPEG-Dash and HTTP Live Streaming support. These presets are prefixed with "dash" and "hls".

We deem this Robot ready for production, but since it hasn't seen a lot of such traffic yet, it's still labeled as beta.

Required CORS settings for MPEG-Dash

Playing back MPEG-Dash Manifest files requires CORS definitions on your Amazon S3 Bucket or other storage location. For convenience here you can find a working CORS definition:

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <ExposeHeader>Access-Control-Allow-Origin</ExposeHeader>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

To set up CORS for your S3 bucket:

1. Visit: https://s3.console.aws.amazon.com/s3/buckets/
2. Click on your bucket
3. Click "Permissions"
4. Click "CORS configuration"

Required CORS settings for HTTP Live Streaming

Playing back HLS playlist files may require a crossdomain policy file. For convenience here you can find a working file.

Please save this to a crossdomain.xml file and store it in the root folder of your Amazon S3 Bucket or other storage location of choice.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
  <allow-access-from domain="*" secure="false" />
  <allow-http-request-headers-from domain="*" headers="*" />
</cross-domain-policy>

Storing Segments and Playlist files

The Robot gives its result files (segments, initialization segments, MPD manifest files and M3U8 playlist files) the right meta data property relative_path, so that you can store them easily using one of our storage Robots.

In the path parameter of the storage Robot of your choice, please use the Assembly Variable ${file.meta.relative_path} to store files in the proper paths to make the playlist files work.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /video/adaptive Robot

• Make video compatible for all devices
• Implement HTTP Live Streaming (HLS)
• Implement MPEG-Dash using Transloadit

3.2 Concatenate videos

The /video/concat Robot concatenates several videos 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.

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:

concatenated: {
  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' },
    ]
  }
}

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /video/concat Robot

• Concatenate video files
• Join multiple videos sharing one audio track

3.3 Transcode, resize, or watermark videos

The /video/encode Robot encodes, resizes, applies watermarks to videos and animated GIFs.

On Watermarking

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.

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.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

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

Watermarking Parameters

HLS Parameters

This Robot used to support HLS parameters but we now recommend using our specialized /video/adaptive Robot instead.

Examples featuring the /video/encode Robot

• Export a video to YouTube
• Encode a video, extract 8 thumbnails and store everything in an S3 bucket
• Automatically decompress uploaded archives
• Reject videos that do not have an audio track
• Specify multiple encoding Steps for a single file
• Automatically process multiple file types
• Make video compatible for all devices
• Concatenate video files
• Encode video for Android, preserving the original quality
• Encode video for Android
• Encode video for browsers in 720p
• Encode video for iPad Air 2
• Encode video for iPhone and strip the sound
• Encode a video into WebM
• Encode video to HEVC
• Extract a 10 second clip from a video
• Extract 10 thumbnails and modify their size
• Extract audio from video files
• Implement HTTP Live Streaming (HLS)
• Implement MPEG-Dash using Transloadit
• Surround a video with a frame using a watermark
• Join multiple videos sharing one audio track
• Optimize videos for iPad
• Apply a watermark to videos

3.4 Merge video, audio, images into one video

The /video/merge Robot composes a new video by adding an audio track to existing still image(s) or video.

This Robot is able to generate a video from:

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

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.

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

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /video/merge Robot

• Add an audio track to video footage
• Convert any video to animated GIF
• Generate a video from an image sequence
• Join multiple videos sharing one audio track
• Merge an audio and a video file
• Merge an audio file and an image to generate a video

3.5 Add subtitles to videos

The /video/subtitle Robot adds subtitles to videos.

This robot supports both SRT and VTT subtitle files.

Imagine you have two file input fields in the same upload form - one for a video file and one for an SRT or VTT subtitle file. They are named "input_video" and "input_srt" (with the HTML "name" attribute). This is how you would go about adding the SRT subtitles into the video with Transloadit:

add_subtitles: {
  robot : '/video/subtitle',
  preset: 'ipad-high',
  use   : {
    steps : [
      { name: ':original', fields: 'input_video', as: 'video' },
      { name: ':original', fields: 'input_srt', as: 'subtitles' },
    ]
  }
}

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /video/subtitle Robot

3.6 Extract thumbnails from videos

The /video/thumbs Robot extracts any number of images from videos for use as previews.

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

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /video/thumbs Robot

• Encode a video, extract 8 thumbnails and store everything in an S3 bucket
• Specify multiple encoding Steps for a single file
• Automatically process multiple file types
• Make video compatible for all devices
• Convert any video to animated GIF
• Encode video for browsers in 720p
• Extract 10 thumbnails and modify their size

3.7 Video Encoding Presets

• v1.0.0
• v2.0.0
• v2.1.0
• v2.2.3
• v3.3.3

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

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

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

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

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

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

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
dash-1080p-video	mp4				libx264	7500000	1920x1080
dash-270p-video	mp4				libx264	460000	480x270
dash-360p-video	mp4				libx264	800000	640x360
dash-480p-video	mp4				libx264	1300000	854x480
dash-540p-video	mp4				libx264	1850000	960x540
dash-576p-video	mp4				libx264	2100000	1024x576
dash-720p-video	mp4				libx264	3300000	1280x720
flash	flv	libmp3lame	64000	44100	flv	512000	320x240
hls-1080p	mp4	libfdk_aac	256000	44100	libx264	7500000	1920x1080
hls-270p	mp4	libfdk_aac	32000	44100	libx264	550000	480x270
hls-360p	mp4	libfdk_aac	64000	44100	libx264	1000000	640x260
hls-480p	mp4	libfdk_aac	64000	44100	libx264	1300000	854x480
hls-540p	mp4	libfdk_aac	128000	44100	libx264	1600000	960x540
hls-576p	mp4	libfdk_aac	128000	44100	libx264	2100000	1024x576
hls-720p	mp4	libfdk_aac	192000	44100	libx264	4000000	1280x720
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-1080p	webm	libvorbis	256000	48000	libvpx	7500000	1920x1080
webm-270p	webm	libvorbis	64000	48000	libvpx	460000	480x270
webm-360p	webm	libvorbis	64000	48000	libvpx	800000	640x360
webm-480p	webm	libvorbis	64000	48000	libvpx	1400000	960x540
webm-540p	webm	libvorbis	128000	48000	libvpx	1850000	960x540
webm-576p	webm	libvorbis	128000	48000	libvpx	2100000	1024x576
webm-720p	webm	libvorbis	192000	48000	libvpx	3300000	1280x720
webm	webm	libvorbis	128000	48000	libvpx	700000
wmv	asf	wmav2			wmv2

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

The hls- and dash- presets are intended for use in combination with our /video/adaptive Robot.

These are supported if you were to specify ffmpeg_stack: "v3.3.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
dash-1080p-video	mp4				libx264	7500000	1920x1080
dash-270p-video	mp4				libx264	460000	480x270
dash-360p-video	mp4				libx264	800000	640x360
dash-480p-video	mp4				libx264	1300000	854x480
dash-540p-video	mp4				libx264	1850000	960x540
dash-576p-video	mp4				libx264	2100000	1024x576
dash-720p-video	mp4				libx264	3300000	1280x720
flash	flv	libmp3lame	64000	44100	flv	512000	320x240
hevc	mp4	libfdk_aac	128k	44100	libx265	1200000
hls-1080p	mp4	libfdk_aac	256000	44100	libx264	7500000	1920x1080
hls-270p	mp4	libfdk_aac	32000	44100	libx264	550000	480x270
hls-360p	mp4	libfdk_aac	64000	44100	libx264	1000000	640x260
hls-480p	mp4	libfdk_aac	64000	44100	libx264	1300000	854x480
hls-540p	mp4	libfdk_aac	128000	44100	libx264	1600000	960x540
hls-576p	mp4	libfdk_aac	128000	44100	libx264	2100000	1024x576
hls-720p	mp4	libfdk_aac	192000	44100	libx264	4000000	1280x720
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-1080p	webm	libvorbis	256000	48000	libvpx	7500000	1920x1080
webm-270p	webm	libvorbis	64000	48000	libvpx	460000	480x270
webm-360p	webm	libvorbis	64000	48000	libvpx	800000	640x360
webm-480p	webm	libvorbis	64000	48000	libvpx	1400000	960x540
webm-540p	webm	libvorbis	128000	48000	libvpx	1850000	960x540
webm-576p	webm	libvorbis	128000	48000	libvpx	2100000	1024x576
webm-720p	webm	libvorbis	192000	48000	libvpx	3300000	1280x720
webm	webm	libvorbis	128000	48000	libvpx	700000
wmv	asf	wmav2			wmv2

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

The hls- and dash- presets are intended for use in combination with our /video/adaptive Robot.

4 Audio Encoding

4.1 Extract or insert audio artwork

The /audio/artwork 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.

For extraction this Robot 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 determines wether to extract or insert.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /audio/artwork Robot

• Extract the cover art from an audio file
• Insert cover art into an audio file

4.2 Concatenate audio

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

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:

concatenated: {
  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' },
    ]
  }
}

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /audio/concat Robot

• Concatenate two audio files

4.3 Encode audio

The /audio/encode Robot converts audio files into all kinds of formats for you. We provide encoding presets for the most common formats.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

HLS Parameters

This Robot used to support HLS parameters but we now recommend using our specialized /video/adaptive Robot instead.

Examples featuring the /audio/encode Robot

• High-quality FLAC encoding
• High-quality MP3 encoding
• Encode to OGG with custom FFmpeg parameters
• Encoding with a specific bit rate
• Downmix multiple audio channels into one
• Extract a 10 second clip from audio

4.4 Loop audio

The /audio/loop Robot loops one audio file as often as is required to match a given duration.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /audio/loop Robot

• Audio Looping

4.5 Merge audio files into one

The /audio/merge Robot overlays several audio files on top of each other.

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 to merge 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' },
    ]
  }
}

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /audio/merge Robot

• Add watermark to a song

4.6 Generate waveform images from audio

The /audio/waveform Robot generates waveform images for your audio files and allows you to change their colors and dimensions.

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.

Similarly, if you need the output image in a different format, please pipe the result of this Robot into the /image/resize Robot.

Here is an example waveform image:

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /audio/waveform Robot

• Generate a waveform image from an audio file

4.7 Audio Encoding Presets

• v1.0.0
• v2.0.0
• v2.1.0
• v2.2.3
• v3.3.3

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

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

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

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

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

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

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
dash-128k-audio	mp4		128000	44100
dash-256k-audio	mp4		256000	44100
dash-32k-audio	mp4		32000	44100
dash-64k-audio	mp4		64000	44100
flac	flac		128000	44100
mp3	mp3	libmp3lame	128000	44100
ogg	ogg	libvorbis
wav	wav	pcm_s16le

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

The hls- and dash- presets are intended for use in combination with our /video/adaptive Robot.

These are supported if you were to specify ffmpeg_stack: "v3.3.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
dash-128k-audio	mp4		128000	44100
dash-256k-audio	mp4		256000	44100
dash-32k-audio	mp4		32000	44100
dash-64k-audio	mp4		64000	44100
empty
flac	flac		128000	44100
mp3	mp3	libmp3lame	128000	44100
ogg	ogg	libvorbis
opus	ogg	libopus	128000	48000
wav	wav	pcm_s16le

You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via a Robot's ffmpeg parameter.

The hls- and dash- presets are intended for use in combination with our /video/adaptive Robot.

5 Image Manipulation

5.1 Optimize images without quality loss

The /image/optimize Robot reduces the size of images while maintaining the same visual quality.

With this Robot it's possible to 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 /file/filter Robot workflows for this.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /image/optimize Robot

• Only resize larger images when resizing files
• Reduce image file sizes by up to 80% without quality loss

5.2 Convert, resize, or watermark images

The /image/resize Robot resizes, crops, changes colorization, rotation, and applies text and watermarks to images.

Parameters

Name	Type	Default	Description
use	(required) String / Array of Strings		General Specifies which Step(s) to use as the input to this Robot. Special Step names A special Step name is ":original", which provides user uploads handled by Transloadit. Providing several Steps as input You can add arrays to use several Steps: use: [ ':original', 'encoded', 'resized' ] Step bundling Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one Zip file for each file passed to it. If you'd set bundle_steps to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to the use parameter: use: { steps: [ ':original', 'encoded', 'resized' ], bundle_steps: true } This is a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality. Keep in mind that all input Steps must be present in your Template. If one of them is missing, no result is generated because the Robot waits indefinitely for all input Steps to be finished. Group by original Sticking with the /file/compress Robot example, you can set group_by_original to true, in order to create a separate Zip file for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is a crucial parameter for the /media/playlist Robot. Demo See a demo for the use parameter here.
format	String	Auto	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. If this parameter is not specified it will default to the format of the input image
width	Integer(1-5000)	Auto	Width of the new image, in pixels. If not specified, will default to the width of the input image
height	Integer(1-5000)	Auto	Height of the new image, in pixels. If not specified, will default to the height of the input image
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 / JSON String	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 JSON string of such an object with coordinates in similar fashion: "{ \"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer> }" To crop around human faces, see our /image/facedetect Robot.
gravity	String	center	The direction from which the image is to be cropped, when "resize_strategy" is set to "crop", but no crop coordinates are defined. The available options are "center", "top", "bottom", "left", and "right". You can also combine options with a hyphen, such as "bottom-right".
strip	Boolean	false	Strips all metadata from the image. This is useful to keep thumbnails as small as possible.
alpha	string	""	Gives control of the alpha/matte channel of an image. Valid options are "Activate", "Background", "Copy", "Deactivate", "Extract", "Off", "On", "Opaque", "Remove", "Set", "Shape", "Transparent"
preclip_alpha	string	""	Gives control of the alpha/matte channel of an image before applying the clipping path via clip: true. Valid options are "Activate", "Background", "Copy", "Deactivate", "Extract", "Off", "On", "Opaque", "Remove", "Set", "Shape", "Transparent"
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. 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	Integer(1-100)	Quality	Controls the image compression for JPG and PNG images. Please also take a look at our /image/optimize Robot. Before: Quality 92 applied: Quality 40 applied: If this parameter is not specified it will default to the quality of the input image, or 92
background	String	"#FFFFFF"	Either the hexadecimal code or name of the color used to fill the background (only used for the pad resize strategy). 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.
frame	Integer / Null	null	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. null means all frames.
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	Integer(0-99) / Null	null	Sets the sepia tone in percent. Before: After setting sepia to 90: After setting sepia to 40: After setting sepia to 10:
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	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	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	Boolean / String	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.
output_meta	Object	{}	Allows you to specify a set of meta data that is more expensive on cpu power to calculate, and thus is disabled by default to keep your Assemblies processing fast. You can add "has_transparency": true in this object to extract if the image contains transparent parts.

Text Overlay Parameters

Name	Type	Default	Description
text	Array of Objects	[]	An array of objects each containing text rules. The following text parameters are intended to be used as properties for your array of text overlays. Here is an example: watermarked: { use: 'resized', robot: '/image/resize', imagemagick_stack: 'v1.0.0', text: [ { text: '© 2018 Transloadit.com', size: 12, font: 'Ubuntu', color: '#eeeeee', valign: 'bottom', align: 'right', x_offset: 16, y_offset: -10, }, ], } Before: After:
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	Integer	12	The text size in pixels.
rotate	Integer	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	Integer	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	Integer	0	The horizontal offset for the text in pixels that is added (positive integer) or removed (negative integer) from the horizontal alignment.
y_offset	Integer	0	The vertical offset for the text in pixels that is added (positive integer) or removed (negative integer) from the vertical alignment.

Watermarking Parameters

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. With watermarking you can add an image onto another image. This is usually used for logos. Before: After:
watermark_position	String / Array of Strings	"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_x_offset	Integer	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 and negative and yield different results depending on the watermark_position parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point.
watermark_y_offset	Integer	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 and negative and yield different results depending on the watermark_position parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point.
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. The exact sizing depends on watermark_resize_strategy, too.
watermark_resize_strategy	String	"fit"	Available values are "fit", "stretch" and "area". To explain how the resize strategies work, let's assume our target image size is 800×800 pixels and our watermark image is 400×300 pixels. Let's also assume, the watermark_size parameter is set to "25%". For the "fit" resize strategy, the watermark is scaled so that the longer side of the watermark takes up 25% of the corresponding image side. And the other side is scaled according to the aspect ratio of the watermark image. So with our watermark, the width is the longer side, and 25% of the image size would be 200px. Hence, the watermark would be resized to 200×150 pixels. If the watermark_size was set to "50%"", it would be resized to 400×300 pixels (so just left at its original size). For the "stretch" resize strategy, the watermark is stretched (meaning, it is resized without keeping its aspect ratio in mind) so that both sides take up 25% of the corresponding image side. Since our image is 800×800 pixels, for a watermark size of 25% the watermark would be resized to 200×200 pixels. Its height would appear stretched, because keeping the aspect ratio in mind it would be resized to 200×150 pixels instead. For the "area" resize strategy, the watermark is resized (keeping its aspect ratio in check) so that it covers "xx%" of the video's surface area. The value from watermark_size is used for the percentage area size.

ImageMagick Parameters

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.

Resize Strategies

The examples below show how the resize_strategy impacts resizing a 400×300 pixel image to 100×100 pixels:

fit

Uses the larger side of the original image as a base for the resize. Aspect ratio is preserved. Either side will become at most 100 pixels.

For example: resizing a 400×300 image into 100×100, would produce a 100×75 image.

Before

Larger side

desert.jpg

19 KB ⋅ 400×300

After

100 px

desert-fit.jpg

4.6 KB ⋅ 100×75

fillcrop

Scales the image to fit into our 100×100 target while preserving aspect ratio, while trimming away any excess surface. This means both sides will become exactly 100 pixels, at the tradeoff of destroying parts of the image.

By default the resulting image is horizontally/vertically centered to fill the target rectangle. Use the gravity parameter to change where to crop the image, such as "bottom" or "left".

Before

desert.jpg

19 KB ⋅ 400×300

After

desert-fillcrop.jpg

5 KB ⋅ 100×100

min_fit

Uses the smaller side of the original image as a base for the resize. After resizing, the larger side will have a larger value than specified. Aspect ratio is preserved. Either side will become at least 100 pixels.

For example: resizing a 400×300 image into 100×100, would produce a 133×100 image.

Before

Smaller side

desert.jpg

19 KB ⋅ 400×300

After

100 px

desert-min_fit.jpg

5.4 KB ⋅ 133×100

pad

Scales the image to fit while preserving aspect ratio. Both sides of the resized image become exactly 100 pixels, and any remaining surface is filled with a background color.

In this example, the background color is determined by the Assembly Variable ${file.meta.average_color}. If you set zoom to false (default is true), smaller images will be centered horizontally and vertically, and have the background padding all around them.

Before

desert.jpg

19 KB ⋅ 400×300

After

desert-pad.jpg

4.7 KB ⋅ 100×100

stretch

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

Before

desert.jpg

19 KB ⋅ 400×300

After

desert-stretch.jpg

5 KB ⋅ 100×100

crop

Cuts an area out of an image, discarding any overlapping parts. If the source image is smaller than the crop frame, it will be zoomed. This strategy is implied when you specify coordinates in the crop parameter, and cannot be used without it.

To crop around human faces, see our /image/facedetect Robot instead.

Before

desert.jpg

19 KB ⋅ 400×300

After

desert-crop.jpg

4.3 KB ⋅ 100×100

Examples featuring the /image/resize Robot

• Add a sepia effect to an image
• Resize and apply transparency, based on a clipping path inside an image
• Avoid zooming small images when resizing
• Change the quality of a JPEG
• Convert an image from JPG to PNG
• Convert an image to WebP
• Crop an image based on cropping coordinates
• Crop a picture to 100×100 pixels
• Apply a watermark to images
• Properly preserve transparency across image types
• Remove a color around the edges of an image
• Resize an image to exactly 100×100 pixels
• Resize an image to exactly 75×75 pixels
• Rotate uploaded images
• Apply a text watermark to images

6 Computer Vision

6.1 Detect faces in images

The /image/facedetect Robot detects faces in images and returns their coordinates, or cuts them from the original images and returns those as new images.

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

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /image/facedetect Robot

• Automatically detect faces in images

7 Document Processing

7.1 Convert documents into different formats

The /document/convert Robot converts documents into different formats.

Note This Robot currently only supports the conversion of SRT files to VTT (video subtitle formats). We will add support for other document formats later.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /document/convert Robot

7.2 Extract thumbnail images from documents

The /document/thumbs Robot generates an image for each page in a PDF file or an animated gif file that loops through all pages.

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

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!

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /document/thumbs Robot

• Convert all pages of a document into an animated GIF
• Convert all pages of a document into separate images
• Convert the first page of a document into an image

7.3 Take screenshots of webpages

The /html/convert Robot takes screenshots of web pages or uploaded HTML pages.

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.

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

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /html/convert Robot

• Take a screenshot of a website (by uploading an HTML file)
• Take a screenshot of a website automatically (by using a URL)

8 File Filtering

8.1 Filter files

The /file/filter Robot is a gatekeeper that can direct files to different encoding Steps based on your conditions.

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

Important If you would like to match against a null value or a value that is not present (like an audio file does not have a video_codec property in its meta data), please match against '' (an empty string) instead. We'll support proper matching against null in the future, but we cannot easily right now without breaking backwards compatibility.

The following lists the supported job variables.

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.

Available Operators for the Conditions

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /file/filter Robot

• Automatically decompress uploaded archives
• Filter out videos that are larger than 20MB or longer than 5 minutes
• Filter out all audio files with a bit rate lower than 64K
• Filter out files that are smaller than 1KB
• Filter out anything other than image files
• Filter out anything other than video or image files
• Only resize larger images when resizing files
• Reject videos that do not have an audio track
• Resize and apply transparency, based on a clipping path inside an image
• Properly preserve transparency across image types
• Extract audio from video files

8.2 Scan files for viruses

The /file/virusscan Robot rejects millions of trojans, viruses, malware & other malicious threats before they reach your platform.

This Robot is built on top of ClamAV, the best open source antivirus engine available. We update its signatures on a daily basis.

By default, this Robot excludes all malicious files from further processing without any additional notification. This behavior can be changed by setting error_on_decline to true, which will stop Assemblies as soon as malicious files are found. Such Assemblies will then be marked with an error.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /file/virusscan Robot

• Automatically reject virus-infected files with an error

9 Media Cataloging

9.1 Generate media playlists

The /media/playlist Robot merges segment files to generate playlist files for HTTP Live Streaming (HLS).

Important The /media/playlist Robot is deprecated and will soon be removed! Please use our /video/adaptive Robot for all your HLS and MPEG-Dash needs instead.

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.

{
  steps: {
    segments: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone-high",
      segment: true,
      segment_duration: 10
    },
    stored_segments: {
      robot: "/s3/store",
      use: "segments",
      bucket: "YOUR_AMAZON_S3_BUCKET_NAME",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET"
    },
    playlist: {
      robot: "/media/playlist",
      use: {
        steps: "stored_segments",
        bundle_steps: true
      }
    },
    store_playlist: {
      robot: "/s3/store",
      use: "playlist",
      bucket: "YOUR_AMAZON_S3_BUCKET_NAME",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET"
    }
  }
}

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:

{
  steps: {
    iphone_high_segments: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone-high",
      segment: true,
      segment_duration: 10,
      width: 800,
      height: 600
    },
    stored_iphone_high_segments: {
      robot: "/s3/store",
      use: "iphone_high_segments",
      bucket: "YOUR_AMAZON_S3_BUCKET_NAME",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET"
    },
    iphone_high_playlist: {
      robot: "/media/playlist",
      use: {
        steps: "stored_iphone_high_segments",
        bundle_steps: true
      },
      resolution: "800x600",
      bandwidth: "auto"
    },
    iphone_low_segments: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone-low",
      segment: true,
      segment_duration: 10
    },
    stored_iphone_low_segments: {
      robot: "/s3/store",
      use: "iphone_low_segments",
      bucket: "YOUR_AMAZON_S3_BUCKET_NAME",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET"
    },
    iphone_low_playlist: {
      robot: "/media/playlist",
      use: {
        steps: "stored_iphone_low_segments",
        bundle_steps: true
      },
      resolution: "800x600",
      bandwidth: "auto"
    },
    store_playlist: {
      robot: "/s3/store",
      use: "iphone_low_playlist",
      bucket: "YOUR_AMAZON_S3_BUCKET_NAME",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET"
    },
    master_playlist: {
      robot: "/media/playlist",
      use: {
        steps: ["iphone_low_playlist", "iphone_high_playlist"],
        bundle_steps: true
      }
    }
  }
}

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /media/playlist Robot

9.2 Write metadata to media

The /meta/write Robot writes meta data into any file that supports it.

This Robot currently accepts images, videos and audio files.

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

FFmpeg Parameters

Examples featuring the /meta/write Robot

• Write meta data to an image

10 File Compressing

10.1 Compress files

The /file/compress Robot creates archives of files or file conversion results.

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
"thumbed":
  - 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
"resized":
  - gh_ll_thumb.jpg
  - gh_df_thumb.jpg
  - ff_jk_thumb.jpg   # is a child of b.mov, as it starts with "ff"

Parameters

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /file/compress Robot

• Create a gzipped tar archive containing multiple result files
• Create a Zip file for each uploaded file
• Create a single Zip file containing all uploaded files

10.2 Decompress archives

The /file/decompress Robot extracts entire archives of files to be consumed by other Robots or exported as individual files.

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

use: [
  ':original',
  'encoded',
  'resized'
]

  use: {
    steps: [
      ':original',
      'encoded',
      'resized'
    ],
    bundle_steps: true
  }

Examples featuring the /file/decompress Robot

• Extract all images from an archive and resize them
• Automatically extract all files from an archive
• Automatically decompress uploaded archives

11 File Exporting

11.1 Export files to Microsoft Azure