Advanced use Parameter

The use parameter offers advanced options that enhance your control over how inputs are processed. These features are especially useful in complex scenarios, like when Steps need to combine inputs or follow specific processing sequences.

Step bundling

Some Robots can gather several Step results for a single invocation. For example, 🤖/file/compress would normally create one archive for each file passed to it. However, if you set bundle_steps to true, it will create one archive containing all the result files from every Step you hand it.

To enable bundling, provide an object like the one below to the use parameter:

"use": {
  "steps": [
    ":original",
    "encoded",
    "resized"
  ],
  "bundle_steps": true
}

Note: The bundle_steps parameter is essential for 🤖/video/adaptive. Without it, you'll generate one master playlist file for each viewing quality.

Group by original

The group_by_original parameter organizes output files by their originating input file, making it essential in workflows where you want to ensure outputs are grouped with the input file that produced them, for example when using the 🤖/file/compress Robot. In this case, you may want to create a separate archive for each uploaded or imported file, rather than creating one containing all original uploads (or one per resulting file).

Example:

"compress": {
  "use": {
    "steps": ["thumbnails"],
    "bundle_steps": true,
    "group_by_original": true
  },
  "robot": "/file/compress"
}

This configuration indicates that the compress Step should consider the output of the thumbnails Step, aggregate these outputs per original file, and then compress them accordingly.

Fields

You can filter and select specific files based on their field names by using the fields setting. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names.

The field names must match the names given to file input fields in your HTML form, as defined in the name attribute of the file input tag. When using a backend SDK, it corresponds with myFieldName1 in e.g.: $transloadit->addFile('myFieldName1', './chameleon.jpg').

Example:

"use": {
  "steps": [":original"],
  "fields": ["myFieldName1"]
}

This parameter is set to true by default, which means all fields are accepted.

Use as

Sometimes Robots take several inputs. For instance, 🤖/video/merge can create a slideshow from audio and images. You can map different Steps to the appropriate inputs by specifying the file type to treat the Step as.

"use": {
  "steps": [
    { "name": "audio_encoded", "as": "audio" },
    { "name": "images_resized", "as": "image" }
  ]
}

Step Ordering

Sometimes the ordering is important, for instance, with our concatenation family of Robots, you may want to specify an exact order to concatenate your media in. For these cases, you can add an index to the end of the file type, starting from 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:

"use": {
  "steps": [
    { "name": ":original", "fields": "myFirstVideo", "as": "video_1" },
    { "name": ":original", "fields": "mySecondVideo", "as": "video_2" },
    { "name": ":original", "fields": "myThirdVideo", "as": "video_3" }
  ]
}

When it is not apparent where to put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to 🤖/image/resize to burn the text into an image. But what happens if you are burning multiple watermarks into the image, how do you point to the text file you want to use? You can 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
    }
  ]
}