Our /file/compress Robot

Compress files

🤖/file/compress creates archives of files or file conversion results.

Usage example

Compress uploaded files into a ZIP archive:

{
  "steps": {
    "compressed": {
      "robot": "/file/compress",
      "use": {
        "steps": [":original"],
        "bundle_steps": true
      },
      "format": "zip"
    }
  }
}

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.

  • 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".

  • archive_name

    String ⋅ default: ''

    This allows you to set a name for the resulting archive file - for example my_archive.zip. If you omit the file extension, it will be added for you.

  • compression_level

    Integer ⋅ default: -6

    Determines how fiercely 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: 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 the first two letters of the unique original prefix + "_" + the first two letters of the unique prefix + "_" + the 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 🤖/video/thumbs, 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

Related blog posts