The /video/encode Robot

We offer a variety of video encoding features like optimizing for different devices, merging, injecting ads, changing audio tracks, or adding company logos.

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

Print your logo into the video stream for maximum brand awareness. You can also extract frames from a video and save them as image files.

Parameters

Name Type Default Description
use (required) String / Array of Strings / Object

General

Specifies which Step(s) to use as our input.

Special Step names

A special Step name is ":original", which provides user uploads handled by Transloadit. Outside of this restriction you can pick your own names.

Providing several Steps as input

You can add arrays to use several Steps:
"use": [
  ":original",
  "encoded",
  "resized"
]
:bulb: That's likely all you need to know about use, but you can view advanced use cases:
› Advanced use cases

Step bundling

Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive 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 also 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 (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here's a demo that showcases Step bundling.

Group by original

Sticking with the /file/compress Robot example, you can set group_by_original to true, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:
"use": {
  "steps": [
    "segmented"
  ],
  "bundle_steps": true,
  "group_by_original": true
}

Fields

You can be more discriminatory by only using files that match a field name by setting the fields property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in the name attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds with myFieldName1 in e.g.: $transloadit->addFile('myFieldName1', './chameleon.jpg'). This parameter is set to true by default, meaning all fields are accepted. Example:
"use": {
  "steps": [ ":original" ],
  "fields": [ "myFieldName1" ]
}

Use As

Sometimes Robots take several inputs. For instance, the /video/merge Robot can create a slideshow from audio and images. You can map different Steps to the appropriate inputs. Example:
"use": {
  "steps": [
    { "name": "audio_encoded", "as": "audio" },
    { "name": "images_resized", "as": "image" }
  ]
}
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different <input> names: Example:
"use": {
  "steps": [
    { "name": ":original", "fields": "myFirstVideo", "as": "video_1" },
    { "name": ":original", "fields": "mySecondVideo", "as": "video_2" },
    { "name": ":original", "fields": "myThirdVideo", "as": "video_3" }
  ]
}
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We use specify it via ${use.text_1}, to indicate the first text file that was passed. Example:
"watermarked": {
  "robot": "/image/resize",
  "use"  : {
    "steps": [
      { "name": "resized", as: "base" },
      { "name": "transcribed", as: "text" },
    ],
  },
  "text": [
    {
      "text"  : "Hi there",
      "valign": "top",
      "align" : "left",
    },
    {
      "text"    : "From the 'transcribed' Step: ${use.text_1}",
      "valign"  : "bottom",
      "align"   : "right",
      "x_offset": 16,
      "y_offset": -10,
    }
  ]
}
preset String "flash" Converts a video according to pre-configured settings. For a list of video presets, see video presets. If you specify your own FFmpeg parameters using the Robot's and/or do not not want Transloadit to set any encoding setting, starting ffmpeg_stack: "v3.3.3", you can use the value 'empty' here.
width Integer(1-1920) Width of the input video Width of the new video, in pixels.
height Integer(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.
turbo Boolean false Speeds up encoding greatly, especially for large non-adaptive workloads. Now in public beta.
FFmpeg Parameters
Name Type Default Description
ffmpeg_stack String "v1.0.0" Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use "v3.3.3" Other valid values can be found here. If you use ffmpeg_stack in conjunction with the /video/subtitle Robot, the default becomes "v3.3.3". Stack "v3.3.3" has a known regression when encoding to AIFF files with the alaw compression. If you need this, best use "v2.2.3".
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": "v3.3.3",
    "preset": "iphone-high",
    "ffmpeg": {
      "b": "600k"
    }
  }
}
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.
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, such as "50%". How the watermark is resized greatly depends on the watermark_resize_strategy.
watermark_resize_strategy String "fit" Available values are "fit", "stretch" and "area". To explain how the resize strategies work, let's assume our target video 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 video 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 video 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 image is stretched (meaning, it is resized without keeping its aspect ratio in mind) so that both sides take up 25% of the corresponding video side. Since our video 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.
watermark_start_time Float 0.0 The delay in seconds from the start of the video for the watermark to appear. By default the watermark is immediately shown.
watermark_duration Float -1.0 The duration in seconds for the watermark to be shown. Can be used together with watermark_start_time to create nice effects. The default value is -1.0, which means that the watermark is shown for the entire duration of the video.
watermark_opacity Float 1.0 The opacity of the watermark. Valid values are between 0 (invisible) and 1.0 (full visibility).
HLS Parameters

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

Demos

Our /video/encode Robot can be used in combination with other Robots, to create powerful workflows unique to your use case. Here are a few example scenarios that you can try live on our website:

Pricing

Transloadit is a SaaS with a subscription model.

Our /video/encode Robot counts towards your plan's data at a normal rate. It charges at minimum 0MB whenever it is used. Assuming the Startup Plan and an average video size of 80MB, you could transcode 102 videos for $49/month.

Just like with your mobile plan, pricing goes down considerably when you commit to larger monthly volumes. You can adjust this every month. More info and available plans on our Pricing page.

Blog posts about the /video/encode Robot

We wrote the following posts about the /video/encode Robot on our blog: