# 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 <dfn>Steps</dfn> need to
combine inputs or follow specific processing sequences.

## Step bundling

Some <dfn>Robots</dfn> can gather several <dfn>Step</dfn> results for a single invocation. For
example, [🤖/file/compress](/docs/robots/file-compress.md) 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 <dfn>Step</dfn> you hand it.

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

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

> [!NOTE] The `bundle_steps` parameter is essential for
> [🤖/video/adaptive](/docs/robots/video-adaptive.md). 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](/docs/robots/file-compress.md) <dfn>Robot</dfn>. 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:**

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

This configuration indicates that the `compress` <dfn>Step</dfn> should consider the output of the
`thumbnails` <dfn>Step</dfn>, 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 <dfn>Step</dfn> 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:**

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

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

## Use `as`

Sometimes <dfn>Robots</dfn> take several inputs. For instance,
[🤖/video/merge](/docs/robots/video-merge.md) can create a slideshow from audio and images. You can
map different <dfn>Steps</dfn> to the appropriate inputs by specifying the file type to treat the <dfn>Step</dfn> as.

```json
"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 <dfn>Robots</dfn>, 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:

```json
"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 <dfn>Assembly Variables</dfn> to be
specific. For instance, you may want to pass a text file to
[🤖/image/resize](/docs/robots/image-resize.md) 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:**

```json
"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
    }
  ]
}
```

### Supplying the watermark via an Assembly Step

You can also pass both the base image file and the watermark image to an <dfn>Assembly Step</dfn>
via the `use` parameter, allowing you to have both be part of the upload, or to use the results of
other <dfn>Assembly Steps</dfn> as input to your
[🤖/image/resize](/docs/robots/image-resize.md) <dfn>Step</dfn>.

For this to work, you just need to use the `as` syntax:

```json
"my_image_step": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": ":original", "as": "base" },
      { "name": "watermark_step", "as": "watermark" }
    ]
  }
}
```

Here the output of a `watermark_step` step is used as the watermark whereas the base image is taken
from the uploaded files.

If you use several file input fields, then you can tell Transloadit which field supplies the base
image and which the watermark. Suppose you have two file input fields named `the_image` and
`the_watermark`. These <dfn>Assembly Instructions</dfn> will make it work using the `fields`
condition:

```json
"my_image_step": {
  "robot": "/image/resize",
  "use": {
    "steps": [
      { "name": ":original", "fields": "the_image", "as": "base" },
      { "name": ":original", "fields": "the_watermark", "as": "watermark" }
    ]
  }
}
```

Please note that the <dfn>Robot</dfn>'s `watermark_url` parameter will still continue to work.