# Transcode, resize, or watermark videos

Robot: `/video/encode`

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

The /video/encode Robot is a versatile tool for video processing that handles transcoding, resizing, and watermarking. It supports various formats including modern standards like HEVC (H.265), and provides features such as presets for common devices, custom FFmpeg parameters for powerusers, watermark positioning, and more.

## iPhone spatial audio

Videos recorded with iPhone spatial audio can contain a stereo AAC track alongside an Apple Positional Audio Codec (APAC) track. When unsupported audio is present, this <dfn>Robot</dfn> keeps one supported audio track by default. Spatial audio is not preserved or converted.

Files containing only unsupported audio still fail. Individual audio track selections and stream-copy requests keep the tracks you select; the output format must support copied tracks.

When adding watermarks or drawing with simple FFmpeg video filters such as `drawtext` to HLG or PQ HDR video, the video is tone-mapped to SDR BT.709 before drawing, so overlay colors retain their intended RGB values. SDR inputs keep their existing processing. A custom `ffmpeg.pre:filter:v` that supplies tone mapping controls its own color conversion. Custom multi-input `filter_complex` graphs must handle each input’s color space explicitly.

## Adding text overlays with FFmpeg

You can add text overlays to videos using FFmpeg's `drawtext` filter through this <dfn>Robot</dfn>'s `ffmpeg` parameter. Here are two examples — one with the default font and one with a custom font family name:

```json
{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "text_overlay_default": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "empty",
      "ffmpeg_stack": "v7",
      "ffmpeg": {
        "codec:a": "copy",
        "vf": "drawtext=text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
      },
      "result": true
    },
    "text_overlay_custom": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "empty",
      "ffmpeg_stack": "v7",
      "ffmpeg": {
        "codec:a": "copy",
        "vf": "drawtext=font='Times New Roman':text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
      },
      "result": true
    }
  }
}
```

**Notes:**

* Use the `font` attribute to reference a font by family name with FFmpeg's `drawtext`
* FFmpeg font family names typically do not contain dashes (e.g. `Times New Roman`), while
  ImageMagick uses dashed names (e.g. `Times-New-Roman`).
* File-loading `drawtext` options such as `textfile` and `fontfile` are not supported. Use
  inline `text` and a font family name instead.
* Preserve the source audio by setting `"codec:a": "copy"`.
* Position text with the `x` and `y` expressions. The example above centers the text.

See the [live text overlay demo](/demos/video-encoding/add-text-overlay.md).

Stage: ga

## Usage example

Transcode uploaded video to [HEVC](https://en.wikipedia.org/wiki/High_Efficiency_Video_Coding) (H.265):

```json
{
  "steps": {
    "hevc_encoded": {
      "preset": "hevc",
      "robot": "/video/encode",
      "use": ":original"
    }
  }
}
```

## Parameters

<span aria-hidden="true" id="interpolate"></span>



### `interpolate`

Controls whether Assembly Variables are interpolated for individual instruction fields.

By default, most Robot instruction fields interpolate Assembly Variables. Set this to `false` to treat every instruction field as literal text, or set an individual field path to `false` to treat only that field as literal text. For Robot-specific fields that are literal by default, set this to `true` or set that field path to `true` to opt back into interpolation.

Use field names such as `path`, or dotted paths such as `ffmpeg.vf` for nested objects.

Type: `boolean | Record<string, boolean>`

<span aria-hidden="true" id="output_meta"></span>



### `output_meta`

Allows you to specify a set of metadata that is more expensive on CPU power to calculate, and thus is disabled by default to keep your Assemblies processing fast.

For images, you can add `"has_transparency": true` in this object to extract if the image contains transparent parts and `"dominant_colors": true` to extract an array of hexadecimal color codes from the image.

For images, you can also add `"blurhash": true` to extract a [BlurHash](https://blurha.sh) string — a compact representation of a placeholder for the image, useful for showing a blurred preview while the full image loads.

For images, `"thumbhash": true` instead extracts a base64-encoded [ThumbHash](https://evanw.github.io/thumbhash/) into `meta.thumbhash`, together with `meta.has_alpha` (whether an alpha channel exists, even when fully opaque). It describes EXIF-oriented pixels and uses the first frame of animated images. Extraction is best-effort: images above 40 megapixels, unsupported formats, or a failed/bounded decode produce no placeholder. Successful extraction adds a metadata charge equivalent to 20% of that file's bytes. No ThumbHash surcharge applies when disabled or when no hash is produced.

Set this option on the Step producing the image, such as `/upload/handle` for uploaded originals or `/image/resize` for processed outputs. Setting it only on `/transloadit/store` does not request extraction: storage preserves the producer's metadata. Transloadit Storage persists a generated hash with its immutable version and returns it in stored results and native asset reads. Direct S3 uploads do not generate placeholders. A placeholder contains image information, so protect it with the same access controls as the full image.

For videos, you can add the `"colorspace": true` parameter to extract the colorspace of the output video.

For videos, you can also add `"interlaced": true` to detect whether the video is interlaced. This combines the cheap ffprobe `field_order` flag with a bounded `idet` sampling pass over the first frames of the source, exposing `interlaced`, `field_order`, and a diagnostic `interlace_detection` object under `file.meta`. This is computationally expensive and billed accordingly.

For audio, you can add `"mean_volume": true` to get a single value representing the mean average volume of the audio file.

You can also set this to `false` to skip metadata extraction and speed up transcoding.

Type: `Record<string, boolean> | boolean | Array<string>`

<span aria-hidden="true" id="user_meta"></span>



### `user_meta`

Adds custom JSON metadata to each emitted file without changing its contents. Nested objects and arrays are supported.

Inheritance depends on the Robot. Values merge with existing `user_meta` on the output file; the current Step replaces matching top-level keys. Assign required keys explicitly when a Robot creates fresh outputs.

In processing Steps, `${file.*}` refers to the first input and `${result.*}` to the emitted file. Values are evaluated per output after the Robot runs, before subsequent metadata extraction and temporary storage. On `:original`, values are evaluated per upload before metadata extraction.

Downstream Steps read `${file.user_meta.key}`. See [Custom metadata](https://transloadit.com/docs/topics/assembly-variables.md#user-meta) for a complete example and inheritance rules.

Type: `Record<string, any>`

Default: `{}`

<span aria-hidden="true" id="result"></span>



### `result`

Whether the results of this Step should be present in the Assembly Status JSON

Type: `boolean`

Default: `false`

<span aria-hidden="true" id="queue"></span>



### `queue`

Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times

Type: `batch`

<span aria-hidden="true" id="force_accept"></span>



### `force_accept`

Force a Robot to accept a file type it would have ignored.

By default, Robots ignore files they are not familiar with.
[🤖/video/encode](/docs/robots/video-encode.md), for
example, will happily ignore input images.

With the `force_accept` parameter set to `true`, you can force Robots to accept all files thrown at them.
This will typically lead to errors and should only be used for debugging or combatting edge cases.

Type: `boolean`

Default: `false`

<span aria-hidden="true" id="ignore_errors"></span>



### `ignore_errors`

Ignore errors during specific phases of processing.

Setting this to `["meta"]` will cause the Robot to ignore errors during metadata extraction.

Setting this to `["execute"]` will cause the Robot to ignore errors during the main execution phase.

Setting this to `true` is equivalent to `["meta", "execute"]` and will ignore errors in both phases.

Type: `boolean | Array<meta | execute>`

Default: `[]`

<span aria-hidden="true" id="use"></span>



### `use`

Specifies which Step(s) to use as input.

* You can pick any names for Steps except `":original"` (reserved for user uploads handled by Transloadit)
* You can provide several Steps as input with arrays:
  ```json
  {
    "use": [
      ":original",
      "encoded",
      "resized"
    ]
  }
  ```
* You can also tag input Steps with `as` to pass semantic intent to robots:
  ```json
  {
    "use": [
      {
        "name": ":original",
        "as": "image"
      },
      {
        "name": ":original",
        "as": "mask"
      }
    ]
  }
  ```

> [!Tip]
> That's likely all you need to know about `use`, but you can view [Advanced use cases](/docs/topics/use-parameter.md).

Type: `string | Array<string> | Array<object> | object`

<span aria-hidden="true" id="ffmpeg"></span>



### `ffmpeg`

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](https://ffmpeg.org/ffmpeg-doc.html). Options specified here take precedence over the preset options.

Type: `object`

<span aria-hidden="true" id="ffmpeg_stack"></span>



### `ffmpeg_stack`

Selects the FFmpeg stack version to use for encoding. We currently recommend using "v7". The exact versions "v6.0.0", "v7.0.0", and "v8.0.0" are legacy values that remain accepted for backward compatibility. Deprecated "v5.x" values are also accepted.

Type: `v6 | v7 | v8 | string`

Default: `"v6.0.0"`

<span aria-hidden="true" id="width"></span>



### `width`

Width of the new video, in pixels.

If the value is not specified and the `preset` parameter is available, the `preset`'s [supplied width](/docs/presets/video.md) will be implemented.

Type: `string | number | null`

<span aria-hidden="true" id="height"></span>



### `height`

Height of the new video, in pixels.

If the value is not specified and the `preset` parameter is available, the `preset`'s [supplied height](/docs/presets/video.md) will be implemented.

Type: `string | number | null`

<span aria-hidden="true" id="preset"></span>



### `preset`

Converts a video according to [pre-configured settings](/docs/presets/video.md).

You can use the value `'empty'` here if you specify your own FFmpeg parameters using the <dfn>Robot</dfn> or do not want Transloadit to set any encoding settings.

Type: `android | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video | dash-270p-video | dash-270p_video | dash-360p-video | dash-360p_video | dash-480p-video | dash-480p_video | dash-540p-video | dash-540p_video | dash-576p-video | dash-576p_video | dash-720p-video | dash-720p_video | dash/1080p-video | dash/1080p_video | dash/270p-video | dash/270p_video | dash/360p-video | dash/360p_video | dash/480p-video | dash/480p_video | dash/540p-video | dash/540p_video | dash/576p-video | dash/576p_video | dash/720p-video | dash/720p_video | dash_1080p-video | dash_1080p_video | dash_270p-video | dash_270p_video | dash_360p-video | dash_360p_video | dash_480p-video | dash_480p_video | dash_540p-video | dash_540p_video | dash_576p-video | dash_576p_video | dash_720p-video | dash_720p_video | flash | gif | hevc | hls-1080p | hls-270p | hls-360p | hls-480p | hls-540p | hls-576p | hls-720p | hls/1080p | hls/270p | hls/360p | hls/480p | hls/4k | hls/540p | hls/720p | hls_1080p | hls_270p | hls_360p | hls_480p | hls_540p | hls_576p | hls_720p | ipad | ipad-high | ipad-low | ipad_high | ipad_low | iphone | iphone-high | iphone-low | iphone_high | iphone_low | ogv | vod/1080p | vod/270p | vod/480p | vod/720p | vp9 | vp9-1080p | vp9-270p | vp9-360p | vp9-480p | vp9-540p | vp9-576p | vp9-720p | vp9_1080p | vp9_270p | vp9_360p | vp9_480p | vp9_540p | vp9_576p | vp9_720p | web/mp4-x265/1080p | web/mp4-x265/240p | web/mp4-x265/360p | web/mp4-x265/480p | web/mp4-x265/4k | web/mp4-x265/720p | web/mp4-x265/8k | web/mp4/1080p | web/mp4/240p | web/mp4/360p | web/mp4/480p | web/mp4/4k | web/mp4/540p | web/mp4/720p | web/mp4/8k | web/mp4_x265/1080p | web/mp4_x265/240p | web/mp4_x265/360p | web/mp4_x265/480p | web/mp4_x265/4k | web/mp4_x265/720p | web/mp4_x265/8k | web/webm-av1/1080p | web/webm-av1/240p | web/webm-av1/360p | web/webm-av1/480p | web/webm-av1/4k | web/webm-av1/720p | web/webm-av1/8k | web/webm/1080p | web/webm/240p | web/webm/360p | web/webm/480p | web/webm/4k | web/webm/720p | web/webm/8k | web/webm_av1/1080p | web/webm_av1/240p | web/webm_av1/360p | web/webm_av1/480p | web/webm_av1/4k | web/webm_av1/720p | web/webm_av1/8k | webm | webm-1080p | webm-270p | webm-360p | webm-480p | webm-540p | webm-576p | webm-720p | webm_1080p | webm_270p | webm_360p | webm_480p | webm_540p | webm_576p | webm_720p | wmv | aac | alac | audio/aac | audio/alac | audio/flac | audio/mp3 | audio/ogg | dash-128k-audio | dash-128k_audio | dash-256k-audio | dash-256k_audio | dash-32k-audio | dash-32k_audio | dash-64k-audio | dash-64k_audio | dash/128k-audio | dash/128k_audio | dash/256k-audio | dash/256k_audio | dash/32k-audio | dash/32k_audio | dash/64k-audio | dash/64k_audio | dash_128k-audio | dash_128k_audio | dash_256k-audio | dash_256k_audio | dash_32k-audio | dash_32k_audio | dash_64k-audio | dash_64k_audio | empty | flac | hg-transformers-audio | hg-transformers_audio | hg_transformers-audio | hg_transformers_audio | mp3 | ogg | opus | speech | wav`

<span aria-hidden="true" id="resize_strategy"></span>



### `resize_strategy`

See the [available resize strategies](/docs/topics/resize-strategies.md).

Type: `crop | fit | fillcrop | min_fit | pad | stretch`

Default: `"pad"`

<span aria-hidden="true" id="zoom"></span>



### `zoom`

If this is set to `false`, smaller videos 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](/docs/topics/resize-strategies.md).

Type: `boolean`

Default: `true`

<span aria-hidden="true" id="crop"></span>



### `crop`

Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original video(s). Values can be integers for absolute pixel values or strings for percentage based values.

For example:

```json
{
  "x1": 80,
  "y1": 100,
  "x2": "60%",
  "y2": "80%"
}
```

This will crop the area from `(80, 100)` to `(600, 800)` from a 1000×1000 pixels video, which is a rectangle whose width is 520px and height is 700px. 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:

```json
"{\"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer>}"
```

Type: `object | string`

<span aria-hidden="true" id="background"></span>



### `background`

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

Type: `string`

Default: `"#00000000"`

<span aria-hidden="true" id="rotate"></span>



### `rotate`

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.

Type: `0 | 90 | 180 | 270 | 360 | false`

<span aria-hidden="true" id="hint"></span>



### `hint`

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

Type: `boolean`

Default: `false`

<span aria-hidden="true" id="turbo"></span>



### `turbo`

Splits the video into multiple chunks so that each chunk can be encoded in parallel before all encoded chunks are stitched back together to form the result video. This comes at the expense of extra Priority Job Slots and may prove to be counter-productive for very small video files.

VP8 output and unresolved video-codec expressions use normal encoding even when `turbo` is `true`.

Type: `boolean`

Default: `false`

<span aria-hidden="true" id="chunk_duration"></span>



### `chunk_duration`

Allows you to specify the duration of each chunk when `turbo` is set to `true`. This means you can take advantage of that feature while using fewer <dfn>Priority Job Slots</dfn>. For instance, the longer each chunk is, the fewer <dfn>Encoding Jobs</dfn> will need to be used.

Requested durations below 5 seconds are treated as 5 seconds.

Type: `string | number`

<span aria-hidden="true" id="watermark_url"></span>



### `watermark_url`

A URL indicating a PNG image to be overlaid above this image. You can also [supply the watermark via another Assembly Step](/docs/topics/use-parameter.md#supplying-the-watermark-via-an-assembly-step).

Type: `"" | string`

Default: `""`

<span aria-hidden="true" id="watermark_position"></span>



### `watermark_position`

The position at which the watermark is placed.

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.

Type: `bottom | bottom-left | bottom-right | center | left | right | top | top-left | top-right | Array<bottom | bottom-left | bottom-right | center | left | right | top | top-left | top-right>`

Default: `"center"`

<span aria-hidden="true" id="watermark_x_offset"></span>



### `watermark_x_offset`

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.

Type: `string | number`

Default: `0`

<span aria-hidden="true" id="watermark_y_offset"></span>



### `watermark_y_offset`

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.

Type: `string | number`

Default: `0`

<span aria-hidden="true" id="watermark_size"></span>



### `watermark_size`

The size of the watermark, as a percentage, such as `"50%"`. How the watermark is resized greatly depends on the `watermark_resize_strategy`.

Type: `string`

<span aria-hidden="true" id="watermark_resize_strategy"></span>



### `watermark_resize_strategy`

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.

Type: `area | fit | stretch`

Default: `"fit"`

<span aria-hidden="true" id="watermark_start_time"></span>



### `watermark_start_time`

The delay in seconds from the start of the video for the watermark to appear. By default the watermark is immediately shown.

Type: `string | number`

Default: `0`

<span aria-hidden="true" id="watermark_duration"></span>



### `watermark_duration`

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.

Type: `string | number`

Default: `-1`

<span aria-hidden="true" id="watermark_opacity"></span>



### `watermark_opacity`

The opacity of the watermark. Valid values are between `0` (invisible) and `1.0` (full visibility).

Type: `string | number`

Default: `1`

<span aria-hidden="true" id="segment"></span>



### `segment`

Splits the file into multiple parts, to be used for Apple's [HTTP Live Streaming](https://developer.apple.com/resources/http-streaming/).

Type: `boolean`

Default: `false`

<span aria-hidden="true" id="segment_duration"></span>



### `segment_duration`

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.

Type: `string | number`

Default: `10`

<span aria-hidden="true" id="segment_prefix"></span>



### `segment_prefix`

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.

Type: `string`

Default: `""`

<span aria-hidden="true" id="segment_name"></span>



### `segment_name`

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

Type: `string`

Default: `""`

<span aria-hidden="true" id="segment_time_delta"></span>



### `segment_time_delta`

Delta to apply to segment duration. This is optional and allows fine-tuning of segment boundaries.

Type: `string | number`

<span aria-hidden="true" id="font_size"></span>



### `font_size`

Type: `string | number`

<span aria-hidden="true" id="font_color"></span>



### `font_color`

Type: `string`

<span aria-hidden="true" id="text_background_color"></span>



### `text_background_color`

Type: `string`
