Media_processing.conf¶
The file defines the media processing rules to transform media representations to different media transformations.
It is a standard CollectiveAccess configuration file using the common configuration syntax.
CollectiveAccess supports media processing configuration for representations of the following items:
- representations (ca_object_representations, ca_object_representation_multifiles)
- attribute values (ca_attribute_value_multifiles)
- icons (ca_icons)
- user comments media (ca_item_comments_media)
- representation annotation previews (ca_representation_annotation_previews)
You may specify accepted media types, and different versions for the transformations, using rules.
Common configuration¶
| Top level key | Description | Default |
|---|---|---|
| use_external_url_when_available | If you want original media fetched from URLs to NOT be stored in CA, but rather for CA to directly reference the media via the URL used to fetch it set use_external_url_when_available to 1. If you have no idea what this means then leave this set to zero. | 0 |
| queue_threshold_in_bytes | Filesize (in bytes) above which media should be queued for background processing Files smaller than the threshold will be processed at the time of upload, so you should set this to a small enough value that your server has a shot at processing the media in near-realtime. A safe bet is 500,000 bytes (eg. 0.5 megabytes), but you may need to go lower (or higher). Note that you can override this setting for specific media types and versions below if you wish. Also keep in mind a few other fun facts:
|
1000 |
Organization¶
At the top level, media_processing.conf is structured as a series of blocks, one for each type of item to be processed:
- representations (ca_object_representations, ca_object_representation_multifiles)
- attribute values (ca_attribute_value_multifiles)
- icons (ca_icons)
- user comments media (ca_item_comments_media)
- representation annotation previews (ca_representation_annotation_previews)
For each table, there is an associative array, with the following keys:
- MEDIA_ACCEPT: Relates mimetypes and media types. Each type of media (Ex.
image) may have multiple mimetypes associated with it. - MEDIA_TYPES: Describes queueing and available representation versions in different sizes and flavours.
- MEDIA_TRANSFORMATION_RULES: Describes the rules to apply to transform a representation file.
This is an example of a media processing file:
ca_object_representations = {
MEDIA_METADATA = "media_metadata",
MEDIA_CONTENT = "media_content",
MEDIA_ACCEPT = {
image/jpeg = image,
image/gif = image,
image/png = image,
image/tiff = image,
image/x-bmp = image,
image/x-dcraw = image,
image/x-psd = image,
image/x-exr = image,
image/jp2 = image,
application/octet-stream = binaryfile
},
# ---------------------------------------------------------
MEDIA_TYPES = {
image = {
QUEUE = mediaproc,
QUEUED_MESSAGE = _("Image is being processed"),
QUEUE_USING_VERSION = original,
VERSIONS = {
thumbnail = {
RULE = rule_thumbnail_image, VOLUME = images,
QUEUE_WHEN_FILE_LARGER_THAN = <queue_threshold_in_bytes>
},
preview = {
RULE = rule_preview_image, VOLUME = images,
QUEUE_WHEN_FILE_LARGER_THAN = <queue_threshold_in_bytes>
},
original = {
RULE = rule_original_image, VOLUME = images,
USE_EXTERNAL_URL_WHEN_AVAILABLE = <use_external_url_when_available>
},
tilepic = {
RULE = rule_tilepic_image, VOLUME = tilepics,
QUEUE_WHEN_FILE_LARGER_THAN = <queue_threshold_in_bytes>
}
},
MEDIA_VIEW_DEFAULT_VERSION = tilepic,
MEDIA_PREVIEW_DEFAULT_VERSION = small
},
binaryfile = {
QUEUE = mediaproc,
QUEUED_MESSAGE = _("Image is being processed"),
QUEUE_USING_VERSION = original,
VERSIONS = {
thumbnail = {
RULE = rule_thumbnail_image, VOLUME = images, BASIS = large,
QUEUE_WHEN_FILE_LARGER_THAN = <queue_threshold_in_bytes>
},
preview = {
RULE = rule_preview_image, VOLUME = images, BASIS = large,
QUEUE_WHEN_FILE_LARGER_THAN = <queue_threshold_in_bytes>
},
original = {
RULE = rule_original_image, VOLUME = images,
USE_EXTERNAL_URL_WHEN_AVAILABLE = <use_external_url_when_available>
}
},
MEDIA_VIEW_DEFAULT_VERSION = large,
MEDIA_PREVIEW_DEFAULT_VERSION = small
}
},
MEDIA_TRANSFORMATION_RULES = {
# ---------------------------------------------------------
# Image rules
# ---------------------------------------------------------
rule_thumbnail_image = {
SCALE = {
width = 120, height = 120, mode = bounding_box, antialiasing = 0
},
SET = {quality = 75, format = image/jpeg}
},
rule_preview_image = {
SCALE = {
width = 180, height = 180, mode = bounding_box, antialiasing = 0
},
SET = {quality = 75, format = image/jpeg}
},
rule_original_image = {},
rule_tilepic_image = {
SET = {quality = 40, tile_mimetype = image/jpeg, format = image/tilepic}
}
# ---------------------------------------------------------
}
}
MEDIA_ACCEPT¶
One entry per mimetype. Each type of media (Ex. image) may have multiple mimetypes associated with it.
mimetype = media_type
MEDIA_TYPES¶
Each key is a media type descriptor, containing an associative array with queueing and representation version descriptions.
| Key | Description | Example |
|---|---|---|
| QUEUE | Queue to deliver the media type to. Only mediaproc is supported currently. |
QUEUE = mediaproc |
| QUEUED_MESSAGE | Message to show on queue listing | QUEUED_MESSAGE = _('Image is being processed') |
| QUEUE_USING_VERSION | Version to use when queueing.
Note here that you have to specify a version here that is not set to QUEUE,
and that you’d almost always want to be using original (a.k.a. the uploaded file). |
QUEUE_USING_VERSION = original |
| MEDIA_VIEW_DEFAULT_VERSION | Name of the media version that should be used as the default for display for the specified mimetype.
|
MEDIA_VIEW_DEFAULT_VERSION = tilepic |
| MEDIA_PREVIEW_DEFAULT_VERSION | Default version to display as a preview for the given field based upon the currently loaded row | MEDIA_PREVIEW_DEFAULT_VERSION = small |
| VERSIONS | Versions describe different representation versions. See VERSIONS for further details | VERSIONS = {
thumbnail = {
RULE = rule_thumbnail_image,
VOLUME = images,
QUEUE_WHEN_FILE_LARGER_THAN = 1000000
},
preview = {
RULE = rule_preview_image,
VOLUME = images,
QUEUE_WHEN_FILE_LARGER_THAN = 1000000
},
original = {
RULE = rule_original_image,
VOLUME = images,
QUEUE_WHEN_FILE_LARGER_THAN = 1000000
},
tilepic = {
RULE = rule_tilepic_image,
VOLUME = tilepics,
QUEUE_WHEN_FILE_LARGER_THAN = 1000000
}
}
|
VERSIONS¶
Each key is a version descriptor, containing an associative array, with a pointer to media transformation rules that help building a new derivative version of a media file.
| Key | Description | Example |
|---|---|---|
| RULE | Rule name | RULE = rule_thumbnail_image |
| VOLUME | A volume label from Media_volumes.conf file. Files will be stored in/retrieved from this volume. | VOLUME = images |
| QUEUE_WHEN_FILE_LARGER_THAN | Filesize (in bytes) above which media should be queued for background processing. Files smaller than the threshold will be processed at the time of upload, so you should set this to a small enough value that your server has a shot at processing the media in near-realtime. A safe bet is 500,000 bytes (eg. 0.5 megabytes), but you may need to go lower (or higher). Note that you can override this setting for specific media types and versions below if you wish. Also keep in mind a few other fun facts:
|
QUEUE_WHEN_FILE_LARGER_THAN = 1000 |
MEDIA_TRANSFORMATION_RULES¶
Rules that describe how to build a derivative version of a media file. There are operations on the image and also filters.
It is an associative array of operation keys.
Here it is a listing of available operations:
| Operation | Description | Example |
|---|---|---|
| ANNOTATE | Add annotations to a media file. Note that annotation requires an alpha channel. If none is available, an all opaque alpha channel is implicitedly created. Not available for GD image plugin. Parameters are:
|
ANNOTATE {
position = south_east,
text = "Annotation",
inset = 10,
font = Arial,
size = 16,
color = blue
}
|
| CROP | Crop the file. Params:
|
CROP {
width = 100,
height = 100,
x = 10,
y = 10
}
|
| FLIP | Reflect the scanlines in the vertical or horizontal direction.
The image will be mirrored upside-down or left-right. Set direction to
vertical or horizontal |
FLIP { direction = vertical }
|
| ROTATE | Rotate the file. Parameters:
|
ROTATE { angle = 30 }
|
| SCALE | Scale the file. Configure the following params:
|
# Limit higher dimension to 240px
SCALE = {
width = 240,
height = 240,
mode = bounding_box,
antialiasing = 0
}
# 200px Square thumbnails
SCALE = {
width = 200,
height = 200,
mode = fill_box,
crop_from = center,
antialiasing = 0
}
|
| SET | Set properties on the media processing handler. Available values are:
|
SET = {
quality = 75,
format = image/jpeg
}
|
| WATERMARK | Add a watermark to a media file. Parameters are:
|
WATERMARK = {
image = <ca_app_dir>/watermark.png,
width = 72,
height = 85,
position = south_east,
opacity = 0.4
},
|
Here it is a listing of available filters.
| Filter | Description | Example |
|---|---|---|
| DESPECKLE | Reduce the speckles within an image. No parameters. | DESPECKLE { }
|
| MEDIAN | Apply a median filter to the image, of the given radius. | MEDIAN { radius = 2 }
|
| SHARPEN | Use a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 to have the method select a suitable radius. The parameters are:
3 or more for sever sharpening. 0.5 to 1.0 is rather good. The larger the sigma the more it sharpens.
|
SHARPEN {
radius = 0,
sigma = 0.63
}
|
| UNSHARPEN_MASK | This filter sharpens an image. The image is convolved with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 to have the method select a suitable radius. The parameters are:
|
UNSHARPEN_MASK {
radius = 0,
sigma = 0.45,
amount = 1.5,
threshold = 0
}
|