Overview

Main registry

The class madam.core.Madam manages the extensions that can be used to process different file formats. It provides convenience methods to read and to write files.

Media assets

At the core of MADAM are assets in the form of madam.core.Asset objects. Asset objects are immutable and provide access the raw data via the file-like attribute essence and to the metadata via the dictionary metadata.

Processors

The extensions used to read, process, and write file formats are called processors. Usually, they are interfaces to external libraries that are used in the background to do all the heavy lifting. There are two types of processors in MADAM:

Essence processors (or just processors)

Represented by madam.core.Processor objects. Essence processors are responsible to read and write the actual data in a specific file format. They also offer various operations that can be performed to modify the data, e.g. to resize or to rotate an image. One implementation of this interface is the madam.image.PillowProcessor class.

Metadata processors

Represented by madam.core.MetadataProcessor objects. Metadata processors are responsible to read and write metadata only. Prominent examples of such metadata could be ID3 in MP3 audio files, or Exif in JPEG images. For example, the implementation for Exif metadata is the madam.exif.ExifMetadataProcessor class.

Operators

Essence processors provide methods to modify assets, which are called operators. As operations are usually performed on many media assets, operators are implemented as partial methods that can be pre-configured and then applied to one or many assets.

Note

Operators can raise exceptions of the type madam.core.OperatorError if something goes wrong.

Pipelines

The utility class madam.core.Pipeline makes it easy to apply a sequence of operators to one or many assets.

portrait_pipeline = Pipeline()
portrait_pipeline.add(processor.resize(width=300, height=300, mode=ResizeMode.FIT))
portrait_pipeline.add(processor.sharpen())

for processed_asset in portrait_pipeline.process(*portrait_assets):
    with open(processed_asset.filename, 'wb') as file:
        file.write(processed_asset.essence.read())

Storage

In MADAM, media assets are organized using modular storage backends. Backends have to subclass madam.core.AssetStorage and behave like Python dictionaries. It will store a media asset together with its metadata and a set of tags using a unique key. The basic expression to store an asset would be backend[asset_key] = asset, tags. Here is a short explanation of the elements in this expression:

  • asset_key is a unique value. Its data type depends on the storage backend.

  • The asset is an madam.core.Asset object with essence and metadata.

  • The set tags stores strings that can be used to filter assets.

Storage bakends also support filtering of assets by metadata or tags with the methods madam.core.AssetStorage.filter() and madam.core.AssetStorage.filter_by_tags().

Note

Two basic backend implementations are provided: