Building assembly instructions

This guide assumes that you are familiar with the Transloadit basics and the minimal integration.

Basics

Processing files is the heart of Transloadit. This is why we crafted a simple JSON format that you can use to make Transloadit do just about anything with your files.

Here is a simple example:

{
  "auth": {"key": "YOUR-API-KEY"},
  "steps":{
    "encode":{
        "robot": "/video/encode",
        "preset": "iphone"
    },
    "export":{
        "robot": "/s3/store",
        "key": "your-key",
        "secret": "your-secret",
        "bucket": "your-bucket"
    }
  }
}

These instructions consist of two assembly steps: "encode" and "export", but you can name your steps any way you want. Giving them names (instead of numbers), makes it easier to reference them.

Each step is defined as a JSON object that has a "robot" key that tells Transloadit which robot to use for this step. Any additional parameters are passed to the robot itself for doing its job.

Executing assembly instructions step by step

Transloadit's default mode of operation is to take your files through the series of assembly steps, using the result files from the previous assembly steps as the input for the next ones.

Consider this set of assembly instructions that takes a video file, encodes it to 320x240 and stores it in S3:

{
    "steps":{
        "encode":{
            "robot": "/video/encode",
            "preset": "iphone"
            "width": 320,
            "height": 240
        },
        "export":{
            "robot": "/s3/store",
            "bucket": "your-bucket",
            "key": "your-key",
            "secret": "your-secret"
        }
    }
}

Executing steps in parallel

However, sometimes you might want to do several things at once. For example lets say you would also like to extract thumbnails from your video:

{
    "steps":{
        "encode":{
            "use": ":original",
            "robot": "/video/encode",
            "preset": "iphone"
            "width": 320,
            "height": 240
        },
        "thumbs":{
            "use": ":original",
            "robot": "/video/thumbs",
            "count": 4
        },
        "export":{
            "use": ["encode", "thumbs"],
            "robot": "/s3/store",
            "bucket": "your-bucket",
            "key": "your-key",
            "secret": "your-secret"
        }
    }
}

The difference here is that we are telling Transloadit to "use" the ":original" file for the "encode" and the "thumbs" step. This causes them both to start at the same time, running in parallel.

The "export" step is setup to "use" the results from the previous two steps as they come in, spawning one internal job for each file.

As you can see, it is quite easy to execute advanced instructions using this format.

Special parameters

Special parameters are those that are interpreted by the assembly engine itself. They control order & behavior of your steps.

Parameter	Description
"robot"	Tells transloadit.com which robot to use for the step.
"use"	Tells transloadit.com which step to use. The default is to use the previous step defined above the current one. Special step names are: ":original": Uses the original uploaded files. You can also add arrays here to "use" several steps: "use": [":original", "encode2", "resizing3"] It is also important to note that each robot only accepts certain file types, all other possible input files are ignored. This means the /video/encode robot will never touch an image while the /image/resize robot will never look at a video. See a demo for the "use" parameter here.
"result"	You can set this to `true` for any intermediate step to get a temporary url to the result file. This is automatically set to `true` for all steps that have no next step to be executed afterwards.

Advanced "use" conditions

The special "use" parameter can also be assigned an object with additional conditions that decide which files are used as the input for a given step.

At this point the following sub-keys are supported:

Parameter	Description
"steps"	This is identical to providing a string or an array as the "use" parameter.
"fields"	An array of one or more field names (from the upload form). The step will only be executed for files that were submitted using one of the given fields. The default for this parameter is true, which means all fields are being accepted.

Notifications

Notifications are a way to have Transloadit contact your server and are part of assembly instructions. We thought they are important enough to have their own dedicated page, though.

Please head over to Notifications vs Redirect Url.

Comments