Filter Configuration

In order for the Cleaver to be able to perform any filtering, you must configure it correctly, by adding configurations to your cleaver-config.yaml file. For Docker-based installations, you will find this file in your installation's docker folder (docker/cleaver-config.yaml). For bare metal installations you will find it in the /etc/escenic folder (/etc/escenic/cleaver-config.yaml).

All filtering configurations are grouped under a filters entry:

filters:
  - name: clean-metadata
    execute: auto
    description: "Removes metadata exif information"
    command: "convert -strip {input} -strip {output}"
  - name: watermark
    execute: auto
    description: "Adds a Escenic watermark to the picture"
    command: "composite -dissolve 20% -gravity center /path/to/watermark.png {input} {output}"
    extensions: [jpg,  JPG, jpeg, JPEG]
  ...etc.

and may contain the following settings:

name

Required. The name you want to give to the filter. The name setting must be preceded by a - (hyphen) to indicate the start of a new filter item.

execute

Optional. If you specify execute: auto, then this filter will be automatically applied to all images handled by the Cleaver (unless excluded by the extensions setting – see below). If you omit this setting, then the filter will only be applied if explicitly requested.

description

Optional. A brief description of what the filter does.

command

Required. The operating system command required to execute the filter operation. In the example shown above, the command:

convert -strip {input} -strip {output}

uses the ImageMagick convert utility to remove EXIF metadata from images. Whatever command you use, you must include the placeholders {input} and {output} in the correct positions in the command.

extensions

Optional. A comma-separated list of filename extensions, enclosed in square brackets ([ and ]). If specified, then the filter will only be applied to images with one of the specified extensions. If extensions is not specified, then the filter is applied to all images.

If you configure more than one filter, then they will be executed in the order they are specified in the configuration file. In some cases, the order in which filters are executed may be significant, so you should think about this when editing your filter configurations.

The default cleaver-config.yaml configuration file contains a number of predefined filter configurations, most of which make use of ImageMagick utilities, so in order to use them, you need to make sure ImageMagick is installed together with the Cleaver. Two of the predefined configurations, however (base64 and guetzli) make use of the Gueztli compression tool, so in order to use them you need to make sure that this tool is installed together with the Cleaver. For information about this tool, see https://github.com/google/guetzli.

You can, of course create filters that make use of other image processing tools. Any tool with a command line interface can be used to implement a Cleaver filter.