The /video/merge 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/merge Robot composes a new video by adding an audio track to existing still image(s) or video.

This Robot is perfect for music studios that want to turn music tracks into videos without manually recording one. Use an album cover instead and export the result to your video-sharing website of choice. We also offer the replacement of the audio track on a video.

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" Generates the video according to pre-configured video presets. If you specify your own FFmpeg parameters using the Robot's ffmpeg parameter and you have not specified a preset, then the default "flash" preset is not applied. This is to prevent you from having to override each of the flash preset's values manually.
width Integer(1-1920) Width of the input image Width of the generated video, in pixels.
height Integer(1-1080) Height of the input image Height of the generated video, in pixels.
resize_strategy String "pad" If the given width/height parameters are bigger than the input image's dimensions, then the resize_strategy determines how the image will be resized to match the provided width/height. See the available resize strategies.
background String "00000000" The background color of the resulting video the "rrggbbaa" format (red, green, blue, alpha) when used with the "pad" resize strategy. The default color is black.
framerate String "1/5" When merging images to generate a video this is the input framerate. A value of "1/5" means each image is given 5 seconds before the next frame appears (the inverse of a framerate of "5"). Likewise for "1/10", "1/20", etc. A value of "5" means there are 5 frames per second.
duration Float 5.0 When merging images to generate a video this is the desired target duration in seconds. The float value can take one decimal digit. If you want all images to be displayed exactly once, then you can set the duration according to this formula: duration = numberOfImages / framerate. This also works for the inverse framerate values like 1/5. If you set this value to null, then the duration of the input audio file will be used.
audio_delay Float 0.0 When merging a video and an audio file, and when merging images and an audio file to generate a video, this is the desired delay in seconds for the audio file to start playing. Imagine you merge a video file without sound and an audio file, but you wish the audio to start playing after 5 seconds and not immediately, then this is the parameter to use.
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.

Demos

Our /video/merge 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/merge 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 merge 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/merge Robot

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