Compress files

Parameters

• 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:

  › 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 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,
        }
      ]
    }
    

• format

  String ⋅ default: "tar"

  The format of the archive to be created. Supported values are "tar" and "zip".

  Note that "tar" without setting gzip to true results in an archive that's not compressed in any way.

• gzip

  Boolean ⋅ default: false

  Determines if the result archive should also be gzipped. Gzip compression is only applied if you use the "tar" format.

• password

  String ⋅ default: null

  This allows you to encrypt all archive contents with a password and thereby protect it against unauthorized use. To unzip the archive, the user will need to provide the password in a text input field prompt.

  This parameter has no effect if the format parameter is anything other than "zip".

• compression_level

  Integer ⋅ default: -6

  Determines how fiercly to try to compress the archive. -0 is compressionless, which is suitable for media that is already compressed. -1 is fastest with lowest compression. -9 is slowest with the highest compression.

  If you are using -0 in combination with the tar format with gzip enabled, consider setting gzip to false instead. This results in a plain Tar archive, meaning it already has no compression.

• file_layout

  String ⋅ default: "advanced"

  Determines if the result archive should contain all files in one directory (value for this is "simple") or in subfolders according to the explanation below (value for this is "advanced").

  Files with same names are numbered in the "simple" file layout to avoid naming collisions.

Archive structure for the "advanced" file layout.

There are a few things that we kept in mind when designing the "advanced" archive structure:

• There could be naming collisions.
• You want to know which Step a result file belongs to.
• You want to know from which originally uploaded file a result file was generated.
• Ideally, you want subfolders for a better structure of files.

To achieve all this, we have created the following archive file structure.

• There is a subfolder for each Step name that has result files in the archive.
• Files are named according to [first_2_letters_of_unique_original_prefix]_[first_2_letters_of_unique_prefix]_[original_file_name]. If you do not know what the original prefixes are, please check our available Assembly variables and look for ${unique_original_prefix} and ${unique_prefix}.
• Files that belong to the :original Step (originally uploaded files) do not include the first two letters of the unique_original_prefix.
• If you are dealing with thumbnails from the /video/thumbs Robot, there is an additional digit representing the order in the file name.

Here is an example:

":original":
  - gh_a.mov          # "gh" are the first 2 letters of the unique prefix.
                      # "a.mov" was the file name of the uploaded file.
  - ff_b.mov
"thumbed":
  - gh_e8_thumb_1.jpg # "gh" is the unique original prefix, meaning it's a result of a.mov.
                      # "e8" is the file's unique prefix.
                      # The "1" shows the thumbnail order.
  - gh_cv_thumb_2.jpg
  - ff_9b_thumb_3.jpg
"resized":
  - gh_ll_thumb.jpg
  - gh_df_thumb.jpg
  - ff_jk_thumb.jpg   # is a child of b.mov, as it starts with "ff"

Demos

• Convert document files to PDF format
• Create a Zip file for each uploaded file
• Create a gzipped tar archive containing multiple result files
• Create a single Zip file containing all uploaded files

Related blog posts

• A Happy 2014 from Transloadit! January 14, 2014
• Create Zip and Tar Archives of Encoded Files September 4, 2013