Assembly Instructions

To learn about Assembly Instructions let's look at this example:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "imported_watermark": {
      "robot": "/http/import",
      "url": "https://transloadit.com/assets/images/face.jpg"
    },
    "resized": {
      "robot": "/image/resize",
      "use": {
        "steps": [
          { "name": ":original", "as": "base" },
          { "name": "imported_watermark", "as": "watermark" }
        ]
      },
      "width": 400,
      "height": 400,
      "watermark_position": "center",
      "watermark_size": "30%"
    },
    "exported": {
      "robot": "/s3/store",
      "use": [":original", "resized"],
      "credentials": "my_cloud_storage_credentials",
      "path": "/my_images/${file.id}/${file.url_name}"
    }
  }
}

The example shows four Steps: :original, imported_watermark, resized and exported. You can name your Steps anything you like with the exception of :original, which refers to uploaded files and must use the 🤖/upload/handle robot.

Notice how both the :original and imported_watermark Steps are used as an input to the resized Step via the use parameter. We use Step bundling here via the "as" syntax to pass multiple files to the resized Step at the same time - one "as" the base image and one "as" the watermark to be printed on top of the base image. Different robots provide different possibilities for the "as" syntax, which makes things very powerful!

The exported step then just uses most of the other Steps as input and stores them on S3 - one by one, without Step bundling. The used Variables ${file.id} and ${file.url_name} are available to all Steps and can be used to create unique filenames for each file.

This way we will be able to handle uploaded files, watermark them and have both the uploaded image and the resized and watermarked redition exported to S3.

Not all Steps require inputs. Our imported_watermark Step for instance provides the first input by downloading it, so that's where we'll omit use. Other examples of Robots that don't require input files are 🤖/html/convert, which can take a screenshot from a website and create the first file that way, or the 🤖/upload/handle, which takes its files from your app's visitors, instead of from another Step.

With one simple change we could make this app truly dynamic. Imagine replacing the static url in the imported_watermark Step with a dynamic one from a field in your app. All we need to do is change the "url" parameter to "${fields.watermark_url}" in our Template and then supply this input field in our HTML web form (or via an additional POST field in our request) to make the watermarking truly dynamic!

Step parameters

As you can see, each Step is defined as an object with a handful of properties, or parameters. Most of them are in fact Robot Parameters as they instruct, for instance, the width of an image after a resize. Those are all covered in the respective Robot docs. There are, however, also 4 parameters that instruct the Assembly engine itself, defining which Robots are invoked and how they are interconnected:

• use

  String / Array of Strings / Object required

  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:

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

  💡 That’s likely all you need to know about use, but you can view Advanced use cases.

• robot

  String required

  Specifies which Robot should process files passed to this Step.

  There are 75 Robots, each with their own parameters, such as width to control how an image is resized. The full list of parameters per Robot can be taken from the Robot docs.

• result

  Boolean ⋅ default: Automatic

  Controls whether the results of this Step should be present in the Assembly Status JSON.

  If set to true, the result of this Step will be present. If files from that Step weren't exported to your storage, their location will be set to a temporary URL.

  By default, we set this to true for leaf Steps and false for any intermediate Step.

  Explicitly setting it to false can be a useful tool in keeping the Assembly Status JSON small.

  Setting result: true on storage Steps does not add those Steps to the Assembly JSON, but only changes the returned URL values for the results of any transcoding Steps passed into those storage Steps. If you pipe a transcoding Step into multiple storage Steps (for example /s3/store) with each having result: true, then multiple results for this transcoding Step will be added to the Assembly JSON, giving you a quick overview of all file URLs for the various S3 buckets (in this example).

• force_accept

  Boolean ⋅ default: false

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

  By default Robots ignore files they are not familiar with. 🤖/video/encode, for example, will happily ignore and refuse to emit 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.

Order of execution

In order to speed up Assemblies, Steps will be executed as soon as their input Steps emit files. In other words, many things are processed in parallel. For example, let's say you want to encode an uploaded video and would also like to extract thumbnails from it:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/1080p"
    },
    "thumbed": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 4
    },
    "exported": {
      "use": ["encoded", "thumbed"],
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS"
    }
  }
}

Both the encoded and the thumbed Steps will be executed in parallel as soon as the first file upload is complete. The exported Step is fired for each of the files coming from encoded and thumbed. It is likely that the thumbnails will hit your S3 bucket before the video that was optimized for iPad, even though thumbnails were defined later. So, the order of Steps does not really matter. The use parameter defines the input for each Step and this ultimately dictates how our Steps are chained.

Filtering to make Steps conditional

Using 🤖/file/filter, you can execute Steps based on a file's properties. This allows you to create Assembly Instructions that: cater to both video and audio uploads, reject files that are too small, only apply an effect on images that have transparent areas, etc. These and more things are also covered in the Robot's docs.