The /file/filter Robot

Transloadit gives its customers the power to reject, or direct files against different encoding steps.

The /file/filter Robot is a gatekeeper that can direct files to different encoding Steps based on your conditions.

Parameters

Name Type Default Description
accepts Array of Arrays [] Files that match at least one requirement will be accepted, or declined otherwise. Example:
[['${file.mime}', '=', 'image/gif']].
If the condition_type parameter is set to "and ", then all requirements must match for the file to be accepted.
declines Array of Arrays [] Files that match at least one requirement will be declined, or accepted otherwise. Example:
[['${file.size}','>','1024']].
If the condition_type parameter is set to "and ", then all requirements must match for the file to be declined.
condition_type String "or" Specifies the condition type according to which the members of the accepts or declines arrays should be evaluated. Can be "or" or "and".
error_on_decline Boolean false If this is set to true and one or more files are declined, the Assembly will be stopped and marked with an error.
error_msg String "One of your files was declined" This is the error message shown to your users (such as by the jQuery SDK) when a file is declined and error_on_decline is set to true.

Example use cases

Our /file/filter Robot can be used in combination with other Robots, to create powerful workflows unique to your use case.
Here are a few example scenarios, and the required the Assembly Instructions to implement them.
You can also try demos of these examples right here, live on our website.

Automatically extract uploaded archives

{
  "steps": {
    "archives": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.mime}",
          "regex",
          "application/(rar|x-7z-compressed|x-cab|x-cpio|x-debian-package|x-gtar-compressed|x-gzip|x-lzh|x-redhat-package-manager|x-tar|zip)"
        ]
      ],
      "error_on_decline": false
    },
    "non-archives": {
      "use": ":original",
      "robot": "/file/filter",
      "declines": [
        [
          "${file.mime}",
          "regex",
          "application/(rar|x-7z-compressed|x-cab|x-cpio|x-debian-package|x-gtar-compressed|x-gzip|x-lzh|x-redhat-package-manager|x-tar|zip)"
        ]
      ],
      "error_on_decline": false
    },
    "extracted": {
      "use": "archives",
      "robot": "/file/decompress"
    },
    "encoded-ipad": {
      "use": [
        "non-archives",
        "extracted"
      ],
      "robot": "/video/encode",
      "ffmpeg_stack": "v2.2.3",
      "preset": "ipad-high",
      "result": true
    },
    "encoded-webm": {
      "use": [
        "non-archives",
        "extracted"
      ],
      "robot": "/video/encode",
      "ffmpeg_stack": "v2.2.3",
      "preset": "webm",
      "result": true
    },
    "exported": {
      "use": [
        ":original",
        "encoded-ipad",
        "encoded-webm"
      ],
      "robot": "/s3/store",
      "key": "YOUR_AWS_KEY",
      "secret": "YOUR_AWS_SECRET",
      "bucket": "YOUR_S3_BUCKET"
    }
  }
}

Filter out videos that are larger than 20MB or longer than 5 minutes

{
  "steps": {
    "files": {
      "use": ":original",
      "robot": "/file/filter",
      "declines": [
        [
          "${file.size}",
          ">",
          "20971520"
        ],
        [
          "${file.meta.duration}",
          ">",
          "300"
        ]
      ],
      "error_on_decline": true
    }
  }
}

Filter out all audio files with a bit rate smaller than 64K

{
  "steps": {
    "files": {
      "use": ":original",
      "robot": "/file/filter",
      "declines": [
        [
          "${file.meta.audio_bitrate}",
          "<",
          "64000"
        ]
      ],
      "result": true
    }
  }
}

Filter out files that are smaller than 1KB

{
  "steps": {
    "files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.size}",
          ">=",
          "1024"
        ]
      ],
      "result": true
    }
  }
}

Filter out anything other than image files

{
  "steps": {
    "files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.mime}",
          "regex",
          "image"
        ]
      ],
      "error_on_decline": true
    }
  }
}

Filter out anything other than video or image files

{
  "steps": {
    "files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.mime}",
          "regex",
          "image"
        ],
        [
          "${file.mime}",
          "regex",
          "video"
        ]
      ],
      "error_on_decline": true
    }
  }
}

Only resize larger images when resizing files

{
  "steps": {
    "large-files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.meta.width}",
          ">",
          "2048"
        ],
        [
          "${file.meta.height}",
          ">",
          "2048"
        ]
      ],
      "condition_type": "or"
    },
    "smaller-files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.meta.width}",
          "<=",
          "2048"
        ],
        [
          "${file.meta.height}",
          "<=",
          "2048"
        ]
      ],
      "condition_type": "or"
    },
    "large-resized": {
      "use": "large-files",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 2048,
      "height": 2048
    },
    "smaller-resized": {
      "use": "smaller-files",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": "${file.meta.width}",
      "height": "${file.meta.height}"
    },
    "optimized": {
      "use": [
        "smaller-resized",
        "large-resized"
      ],
      "robot": "/image/optimize"
    },
    "exported": {
      "use": [
        "optimized",
        ":original"
      ],
      "robot": "/s3/store",
      "key": "YOUR_AWS_KEY",
      "secret": "YOUR_AWS_SECRET",
      "bucket": "YOUR_S3_BUCKET"
    }
  }
}

Reject videos that do not have an audio track

{
  "steps": {
    "files": {
      "use": ":original",
      "robot": "/file/filter",
      "declines": [
        [
          "${file.meta.audio_bitrate}",
          "=",
          ""
        ]
      ],
      "error_on_decline": true
    },
    "iphone_video": {
      "use": ":original",
      "robot": "/video/encode",
      "result": true,
      "ffmpeg_stack": "v2.2.3",
      "preset": "iphone"
    }
  }
}

Properly preserve transparency across image types

{
  "steps": {
    "nontransparent": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.mime}",
          "=",
          "image/jpeg"
        ],
        [
          "${file.mime}",
          "=",
          "image/jpg"
        ]
      ],
      "error_on_decline": false
    },
    "maybetransparent": {
      "use": ":original",
      "robot": "/file/filter",
      "declines": [
        [
          "${file.mime}",
          "=",
          "image/jpeg"
        ],
        [
          "${file.mime}",
          "=",
          "image/jpg"
        ]
      ],
      "error_on_decline": false
    },
    "resize_nontransparent": {
      "use": "nontransparent",
      "robot": "/image/resize",
      "result": true,
      "resize_strategy": "fit",
      "width": 400,
      "height": 300
    },
    "resize_maybetransparent": {
      "use": "maybetransparent",
      "robot": "/image/resize",
      "result": true,
      "resize_strategy": "fit",
      "background": "none",
      "width": 400,
      "height": 300
    }
  }
}

Related blog posts

Over the years we wrote the following posts about Our /file/filter robot on our blog:

Did you know?

You can easily combine Robots to create powerful workflows, unique to your business.
This is the power of Transloadit.